组件 · 数据录入
RadioGroup 单选组
互斥单选表单控件组。
使用建议
- 避免：与 Checkbox 混用互斥语义
- 限制：属性与导出以 @selrux/ui 对应子路径 d.ts/源码为准，禁止臆造
引入
import {
RadioGroup,
RadioGroupButton,
RadioGroupItem,
RadioGroupLabel,
} from '@selrux/ui/radio-group';演练场
调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。
代码演示
基础用法
RadioGroupItem 组合，name 用于表单提交。
按钮样式
optionType="button"，buttonStyle 为 outline / solid，options 配置式传入。
受控与校验
value / onValueChange 受控；required、invalid 标记校验状态；disabled 禁用整组；size；dir 方向。
按钮样式
RadioGroupButton 的 value、label 与 disabled。
API
属性覆盖：示例用到 18 / 18 个自有属性（100%）
由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。
RadioGroup.form：原生 form 关联（外部 form id），无可见效果
RadioGroup
解析尺寸与按钮外观，并将 options 展开为 styled 项后再交给行为层。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
name * | 写到所有原生 radio；必填且非空，禁止随机字段名。 | string | - |
form | 下传每个 input 的 form，而非只给外层 div。 | string | - |
defaultValue | 受控时禁止初始值。 | string | null | - |
dir | 同步 DOM 与左右方向键；未传时继承。 | "ltr" | "rtl" | - |
disabled | 下传所有 input；优先于单项 disabled。 | boolean | - |
value | 当前选中值；null 表示未选。 | string | null | - |
onValueChange | 用户选择新项时通知；同值、reset、prop 更新不调用。 | ((value: string) => void) | - |
required | 原生 radio 组校验：至少有可校验成员且未选时阻止提交。 | boolean | - |
orientation | 排版与主要导航方向，默认 vertical。 | "horizontal" | "vertical" | vertical |
invalid | 组与项的无效状态；显式 aria-invalid 优先。 | boolean | - |
options | - | readonly RadioGroupOption[] | - |
size | 显式尺寸优先于 Provider，最终回退 md。 | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | - |
optionType | 配置模式下项外观；复合 Button 组忽略此项的 default。 | "button" | "default" | - |
buttonStyle | 按钮描边或填底；仅按钮外观生效。 | "outline" | "solid" | - |
另有 275 项原生属性与事件继承自 HTMLAttributes，原样透传。
RadioGroupButton
按钮皮项：隐藏系统圆点，由 CSS 绘制分段按钮外观。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
value * | 选择标识与提交值；组内唯一非空字符串。 | string | - |
label | 与原生 input 同处一个 label；省略时须提供 ARIA 名称。 | ReactNode | - |
disabled | 本项禁用。 | boolean | - |
children | input 不接受子节点。 | undefined | - |
另有 298 项原生属性与事件继承自 HTMLAttributes / InputHTMLAttributes，原样透传。
RadioGroupItem
圆形项：添加尺寸类与强调样式钩子。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
value * | 选择标识与提交值；组内唯一非空字符串。 | string | - |
label | 与原生 input 同处一个 label；省略时须提供 ARIA 名称。 | ReactNode | - |
disabled | 本项禁用。 | boolean | - |
children | input 不接受子节点。 | undefined | - |
另有 298 项原生属性与事件继承自 HTMLAttributes / InputHTMLAttributes，原样透传。
RadioGroupLabel
为组名添加静态类名。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
children | 组名称内容。 | ReactNode | - |
另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。
导出类型：HeadlessGroupWithoutOptions、RadioGroupButtonComponent、RadioGroupButtonProps、RadioGroupButtonStyle、RadioGroupControlledProps、RadioGroupItemComponent、RadioGroupItemProps、RadioGroupLabelComponent、RadioGroupLabelProps、RadioGroupOption、RadioGroupOptionType、RadioGroupOrientation、RadioGroupProps、RadioGroupSize、RadioGroupUncontrolledProps、RadioGroupVisualProps
无障碍
摘自源码 JSDoc。
RadioGroup.dir：同步 DOM 与左右方向键；未传时继承。RadioGroup.invalid：组与项的无效状态；显式 aria-invalid 优先。RadioGroupButton.label：与原生 input 同处一个 label；省略时须提供 ARIA 名称。RadioGroupItem.label：与原生 input 同处一个 label；省略时须提供 ARIA 名称。