RadioGroup

从互斥选项中选择一项。中文惯用名：单选框。设计文档原名：Radio。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.radio-group`
名称	RadioGroup
二级分类	数据录入（`data-entry`）
用途	从互斥选项中选择一项
描述	中文惯用名：单选框。设计文档原名：Radio。

预览

静态结构：RadioGroup 为 data-slot="radio-group" 容器（Base UI 原语），每个选项为 data-slot="radio-group-item" 圆点（选中态显示 data-slot="radio-group-indicator"）+ 旁侧 label，label 经 htmlFor 关联选项自身 id，点击文字即选中该项。direction="horizontal" 时容器叠加 flex flex-wrap 横排（gap-x-6 / gap-y-2），缺省 vertical 竖排；选项级 disabled 与整体 disabled 均使圆点与文字半透明。始终受控：未选中时以空值占位，不命中任何选项。Form 内声明非空 name 时经 FieldShell 包裹（label + 校验错误行）。

DSL 结构

DslNode

{
  "type": "RadioGroup",
  "props": {
    "name": "period",
    "label": "统计周期",
    "direction": "horizontal",
    "options": [
      {
        "label": "按日",
        "value": "day"
      },
      {
        "label": "按周",
        "value": "week"
      },
      {
        "label": "按月",
        "value": "month"
      }
    ],
    "value": "week"
  }
}

何时用

何时使用

少量（2-5 个）互斥选项中选一个：统计周期、性别、优先级、配送方式。
选项需要平铺对比、一次点击完成选择（相比 Select 少一次展开）。
表单内的枚举单选字段：声明 name 即自动注册，参与校验与提交。

何时不用

选项较多或需搜索：使用 Select / Combobox；RadioGroup 全部平铺会挤占版面。
选项需即时生效、切换的是同区域视图：使用 Segmented（更紧凑，且不承载表单语义）。
布尔开关（开 / 关）：使用 Switch 或 Checkbox；RadioGroup 用于「多于两个」的互斥选项。
可多选：使用 Checkbox 组。

变体

变体	视觉形态	适用场景
vertical 竖排（缺省）	选项纵向排列，逐行可点	选项文案较长、横向空间不足
horizontal 横排	flex 横排自动换行（gap-x-6）	2-4 个短文案选项（如「按日 / 按周 / 按月」）
选项级 disabled	单个选项半透明不可选	无权限 / 不可用的候选项
Form 表单项	FieldShell：label + 选项组 + 校验错误行	表单内枚举单选字段（声明 name 自动注册）
disabled 整体禁用	全部选项禁用	只读回显、按当前状态不可变更

API 属性

属性	类型	默认值	说明
`name`	`string`	—	字段名；在 Form 内声明即自动成为表单项
`label`	`string`	—	表单项标签（FieldShell 呈现）
`rules`	`FieldRule[]`	—	校验规则
`options`	`RadioGroupOption[]`	[]	选项列表（可含表达式解析后的数组）；项结构 { label, value: string
`direction`	`'horizontal'	'vertical'`	'vertical'
`value`	`string	number	boolean`
`disabled`	`boolean`	false	整体禁用；选项级禁用用 options 项的 disabled
`onChange`	`(value: string	number	boolean) => void`
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为控件包裹）

使用规范

选项控制在 2-5 个、文案短；更多或更长时改用 Select，避免平铺占满整屏。
选项 value 类型保持一致（string / number / boolean 不混用），否则选中态匹配错位。
direction 按文案长度选：短文案横排更紧凑，长文案竖排更易读；同一表单内保持一致。
必选项配 rules.required 并在 label 上标明；不要靠「默认选中第一个」掩盖未填写。
与 Segmented 的边界：需要提交进表单、有 name / rules 语义用 RadioGroup；纯视图切换用 Segmented。

正例

✓ 表单「统计周期」：options 三项 + direction="horizontal"，name + rules 必填。
✓ 配送方式：竖排选项，每项含一句说明文案，选择后驱动运费计算。
✓ 无权限选项：选项级 disabled 并保留可见，让用户理解为何不可选。

反例

✕ 用 RadioGroup 平铺二十个选项（应使用 Select / Combobox）。
✕ 用两个选项的 RadioGroup 表达开关语义并期待即时生效（应使用 Switch）。
✕ 同一组内选项 value 混用字符串与数字，回填时选中态丢失。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。