0 Fork 0

Files

T

2026-10-08 22:38:34 +08:00

3.5 KiB

Raw Blame History

title, description

title	description
Radio 单选框	与 RadioGroup 组合使用，在一组选项里选中一个

Radio 单选框

G3Radio 必须放在 G3RadioGroup 里才能互斥。组负责值、禁用与 name，单选项只声明自己的 value 和内容。

何时使用

选项少（2-5 个）且需要一次看全时，比 Select 更快；
选项是互斥的、必须选一个时使用；可以不选时用 Select 更合适；
选项超过 5 个、或需要展示更多信息时，用 Select；
只是控制某个功能的开与关，用 Switch。

基础用法

:::demo{name="radio/basic"} :::

组会自动生成唯一的原生 name（useId），因此同页多组之间不会互相干扰，键盘方向键也能在组内来回切换。

纵向排列与整组禁用

组默认是水平换行的 inline-flex；纵向排列用外部 style 改 flex-direction，或给组包一层纵向容器。

:::demo{name="radio/vertical"} :::

卡片式选择

默认插槽可以放任意内容，配合 style 就能做成卡片选择器（常见于套餐、模板选择）。

:::demo{name="radio/cards"} :::

API

Props（Radio）

名称	类型	默认值	说明
`value`	`string \| number \| boolean`	必填	选项值。与组 `modelValue` 做 `Object.is` 比较决定是否选中
`disabled`	`boolean`	`false`	单独禁用该项（组禁用时以组为准）

Props（RadioGroup）

名称	类型	默认值	说明
`modelValue`	`string \| number \| boolean`	—	双向绑定的选中值
`disabled`	`boolean`	`false`	禁用整组
`name`	`string`	自动生成	原生 radio 组名，不传时用 `useId` 生成

Events（RadioGroup）

名称	参数	说明
`update:modelValue`	`(value: string \| number \| boolean)`	选中项变化
`change`	`(value: string \| number \| boolean)`	同上，便于只监听变化

Slots

组件	插槽	说明
Radio	`default`	选项文案，可放富内容
RadioGroup	`default`	组内的 `G3Radio` 列表

类型定义

export type RadioValue = string | number | boolean

export interface RadioProps {
  value: RadioValue
  disabled?: boolean
}

export interface RadioGroupProps {
  modelValue?: RadioValue
  disabled?: boolean
  name?: string
}

export interface RadioGroupContext {
  name: ComputedRef<string | undefined>
  modelValue: ComputedRef<RadioValue | undefined>
  disabled: ComputedRef<boolean>
  select: (value: RadioValue) => void
}

样式变量

变量	默认值	说明
`--g3-radio-size`	`16px`	圆圈直径
`--g3-color-primary`	`#18181b`	选中态边框与内点
`--g3-bg-disabled` / `--g3-text-disabled`	`rgba(0,0,0,.04 / .25)`	禁用态

实现说明

底层同样是原生 input[type=radio]：组用 <div> 包裹、每项用 <label> 包裹，浏览器原生提供「组内互斥 + 方向键切换」；
选中判断用 Object.is（而不是 ===），这样 NaN 之类的值也能正确比较；
组上下文通过 provide 下发：{ name, modelValue, disabled, select }，单选项目通过 inject 读取；脱离组单独使用时会退化为「永不选中」的原生 radio（不会报错，但也不会有选中态），因此务必成对使用；
未显式传 name 时用 useId 生成组名，避免同页多个 radio 组因为浏览器按 name 分组而互相影响。

3.5 KiB Raw Blame History Unescape Escape