Radio 单选框
Radio 现在不再只是一个带颜色和尺寸的原生 input。它同时支持带说明内容的单选项、配置驱动的 Radio.Group、按钮化选项,以及更清晰的受控 / 非受控 API。
何时使用
- 需要在少量、彼此可直接比较的选项中选出唯一结果。
- 需要用配置数组快速生成单选组,而不是手写重复结构。
- 希望把单选项组织成按钮组或说明卡片,但仍保持 radio 的语义。
推荐优先使用Radio.Group + options组织业务表单;手写 children 更适合定制结构和说明文案。
# 基础用法
展示原生 radio 体验,同时让受控写法更直接。
当前选择:startup
# 带说明的单选项
给 children 加一层描述结构,就可以把 Radio 组织成卡片式选项。
当前选择:team
# Radio.Group 配置模式
options 是推荐写法,适合 schema、配置表单和动态渲染。
当前计费周期:monthly
# 按钮样式
Radio.Button 是 Radio 的按钮糖衣,组内也可以统一切到按钮风格。
Outline
Solid
当前组合:comfortable / classic
# 尺寸
展示基础 xs 到 xl 的尺寸层,并补充 small / middle / medium / large 别名。
# 颜色
使用颜色修饰,同时能作为按钮组选中色复用。
# 禁用状态
单项和整组都支持禁用,组禁用时会向下同步到所有 input。
# 自定义颜色
如果需要品牌色或语义强化,仍然可以直接叠加 Tailwind 工具类。
API
Radio.Button等价于Radio optionType="button"。推荐在配置驱动场景下优先使用Radio.Group的options入口。
Radio / Radio.Button
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
buttonStyle | 按钮形态下的视觉风格,Radio.Button 或 optionType="button" 时生效 | 'outline' | 'solid' | 'outline' |
checked | 受控选中状态 | boolean | - |
className | 默认模式作用于 input,按钮模式作用于按钮表面 | string | - |
color | 选中点或按钮激活色 | 'neutral' | 'primary' | 'secondary' | 'accent' | 'success' | 'warning' | 'info' | 'error' | - |
contentClassName | 包裹 children 内容区域的类名 | string | - |
defaultChecked | 非受控初始选中状态 | boolean | false |
disabled | 禁用单个选项 | boolean | false |
onChange | 值变化时回调,返回 event 和 { checked, value, optionType } | (event, meta) => void | - |
onCheckedChange | 仅关心 checked 布尔值时使用 | (checked, event) => void | - |
optionType | 切换为默认圆点形态或按钮形态 | 'default' | 'button' | 'default' |
rootClassName | 外层 label 容器类名,适合做卡片式单选项 | string | - |
size | 尺寸,支持 xs 到 xl 以及 small / middle / medium / large 别名 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'small' | 'middle' | 'medium' | 'large' | - |
value | 选项值,供 Group 或业务状态比较使用 | string | number | boolean | - |
Radio.Group
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
block | 让选项按容器宽度伸展,适合卡片或按钮组 | boolean | false |
buttonStyle | 按钮组的视觉风格 | 'outline' | 'solid' | 'outline' |
color | 组选中态的默认颜色,可被单个 option 覆盖 | 'neutral' | 'primary' | 'secondary' | 'accent' | 'success' | 'warning' | 'info' | 'error' | - |
defaultValue | 非受控默认值 | string | number | boolean | - |
disabled | 禁用整个单选组 | boolean | false |
name | 组内 input 的 name;未传时会自动生成 | string | 自动生成 |
onChange | 组选中值变化时回调,返回 nextValue、event 和 meta | (value, event, meta) => void | - |
options | 推荐的配置化写法,适合表单 schema 或配置驱动页面 | Array<RadioOption | string | number | boolean> | - |
optionType | 统一控制组内是默认单选点还是按钮风格 | 'default' | 'button' | 'default' |
orientation | 排列方向,优先级高于 vertical | 'horizontal' | 'vertical' | 'horizontal' |
size | 组选项默认尺寸,options 模式最适合统一控制 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'small' | 'middle' | 'medium' | 'large' | - |
value | 受控当前值 | string | number | boolean | - |
vertical | 纵向排列快捷开关 | boolean | false |
RadioOption
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
className | 选项外层类名,适合做卡片边框、间距等布局样式 | string | - |
color | 单独覆盖某个选项的选中色 | 'neutral' | 'primary' | 'secondary' | 'accent' | 'success' | 'warning' | 'info' | 'error' | - |
disabled | 禁用当前选项 | boolean | false |
id | 透传到 input 的 id | string | - |
label | 选项展示内容,支持字符串或 JSX 结构 | any | - |
onChange | 该选项被选中时的局部回调 | (event, meta) => void | - |
required | 透传到 input 的 required | boolean | false |
size | 单独覆盖某个选项的尺寸 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'small' | 'middle' | 'medium' | 'large' | - |
style | 选项外层样式对象 | CSSProperties | - |
title | 透传到外层 label 的 title | string | - |
value | 选项值 | string | number | boolean | - |