Radio 单选框

在多个备选项中选中一个。

何时使用

• 在一组备选项中选中单一选项。
• 与 <c-radio-group> 搭配，在多个 Radio 之间形成互斥关系。

基本使用

将 v-model 与每个 <c-radio> 的 label 比对决定选中状态；值可以是字符串、数字或布尔值。

禁用

disabled 让单项不可选；常用于"权限不足 / 暂不开放"。

单选框组

<c-radio-group> 把一组 Radio 收纳到统一的 v-model 下，免去给每个 Radio 单独绑值。

排列方向

direction 切换纵向（默认）/ 横向。

整组禁用

在 <c-radio-group> 上加 disabled 一次性禁用整组。

切换前钩子

before-change 返回 false / Promise<false> 时阻止本次切换，常用于"二次确认"或"先做异步校验"。

监听 change

change 事件返回新值，用于联动其他状态。

键盘与表单

RadioGroup 会为组内原生 radio 使用同一个 name：Tab 进入当前选中项后，可使用方向键切换选项，并用 Space 选择。向 RadioGroup 传入 name 后，选中值会以该字段名随原生表单提交；未传入时组件会自动生成分组名，需要读取原生 FormData 时建议显式传入稳定名称。

API

Radio Props

参数	类型	默认值	说明
modelValue	string | number | boolean	—	绑定值（与 label 比较决定是否选中），支持 v-model
label	string | number | boolean	''	本项的值
name	string	''	独立使用时的原生 name；组内使用 RadioGroup 的 name
disabled	boolean	false	是否禁用
beforeChange	BeforeChangeType	—	切换前的钩子，返回 false 或拒绝 Promise 时阻止切换

Radio Events

事件	回调签名	说明
change	(value: string | number | boolean) => void	值改变时触发

RadioGroup Props

参数	类型	默认值	说明
modelValue	string | number | boolean	—	被选中的值，支持 v-model
name	string	''	组内原生 radio 的 name，用于表单提交
disabled	boolean	false	整组禁用
direction	DirectionType	'column'	排列方向（row / column）
beforeChange	BeforeChangeType	—	切换前的钩子，返回 false 或拒绝时阻止

RadioGroup Events

事件	回调签名	说明
change	(value: string | number | boolean) => void	值改变时触发

Slots

名称	说明
default	单选框右侧文本

类型定义

type RadioValue = string | number | boolean
type BeforeChangeType = (value: RadioValue) => boolean | Promise<boolean>
type DirectionType = 'row' | 'column'