跳到主要内容

RadioGroup

  • 组件说明：单选按钮组，用于一组互斥选项中的单选。
  • 交互特征：当前规范覆盖未选中、选中、禁用和悬停主矩阵。
  • 实现约定：RadioGroup 保留互斥选择结构，design 层统一接管边框、填充和内圆视觉。
  • Figma 规范

基础用法​

传入 label 后整行（控件 + 文字）均可点击。

结果
Loading...
实时编辑器
render(
  <RadioGroup defaultValue="option1" aria-label="Favorite fruit">
    <RadioGroupItem value="option1" label="Apple" />
    <RadioGroupItem value="option2" label="Banana" />
    <RadioGroupItem value="option3" label="Cherry" />
  </RadioGroup>,
)

禁用状态​

结果
Loading...
实时编辑器
render(
  <RadioGroup defaultValue="option1" disabled aria-label="Disabled group">
    <RadioGroupItem value="option1" label="Selected (disabled)" />
    <RadioGroupItem value="option2" label="Unselected (disabled)" />
  </RadioGroup>,
)

悬停与主矩阵​

结果
Loading...
实时编辑器
render(
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 24, alignItems: 'center' }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <RadioGroup aria-label="Unchecked default">
        <RadioGroupItem value="default-unchecked" aria-label="Unchecked default" />
      </RadioGroup>
      <span style={{ fontSize: 12, color: '#999' }}>未选中 Default</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <RadioGroup aria-label="Unchecked hover">
        <RadioGroupItem value="hover-unchecked" className="border-[var(--Labels-Primary)]" aria-label="Unchecked hover" />
      </RadioGroup>
      <span style={{ fontSize: 12, color: '#999' }}>未选中 Hover</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <RadioGroup defaultValue="default-checked" aria-label="Checked default">
        <RadioGroupItem value="default-checked" aria-label="Checked default" />
      </RadioGroup>
      <span style={{ fontSize: 12, color: '#999' }}>选中 Default</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <RadioGroup defaultValue="disabled-checked" disabled aria-label="Checked disabled">
        <RadioGroupItem value="disabled-checked" aria-label="Checked disabled" />
      </RadioGroup>
      <span style={{ fontSize: 12, color: '#999' }}>选中 Disabled</span>
    </div>
  </div>,
)

命名空间用法​

结果
Loading...
实时编辑器
render(
  <Controls.RadioGroup defaultValue="a" aria-label="Namespace radio">
    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
      <Controls.RadioGroupItem value="a" aria-label="A" />
      <span style={{ fontSize: 14 }}>Controls.RadioGroupItem</span>
    </div>
  </Controls.RadioGroup>,
)

RadioGroup Props​

属性类型默认值说明
valuestring—受控选中值
defaultValuestring—非受控默认选中值
disabledbooleanfalse禁用整组
onValueChange(value: string) => void—选中值变化回调
orientation'horizontal' | 'vertical''vertical'排列方向
classNamestring—自定义样式类
aria-labelstring—无障碍标签

RadioGroupItem Props​

属性类型默认值说明
valuestring—选项值（必填）
labelstring—标签文字，传入后整行（控件 + 文字）均可点击
disabledbooleanfalse禁用该项
labelClassNamestring—label 行的自定义样式类
classNamestring—自定义样式类
aria-labelstring—无障碍标签