输入类 · Radio
单选框
用户使用单选框来从少量的选项集合中选择单个选项

使用场景

单选框(Radio)也叫单选按钮,它允许用户在一组选项中选择其中一个。
当选项很多时,单选下拉菜单(Select)可能比较适合,因为它所占用的画面空间比单选按钮来得要少。

代码演示

如何引入

基本用法

带辅助文本

通过extra设置辅助文本,可以是任意类型的 ReactNode
extra在 v0.25.0 后开始提供

禁用

Radio 不可用

高级模式

高级模式(mode='advanced')checked 可以通过点击转换为 unchecked。

单选组合

一组互斥的 Radio 配合使用

垂直排列

可通过给 RadioGroup 设置 direction属性来决定 组内的 radio 元素水平排列或者垂直排列

按钮样式

version: >=1.26.0
可以利用 type='button' 来设置 button 样式类型的单选器,并且,button 类型单选器支持三种尺寸大小。
需要注意的是: button 类型的单选器暂不支持辅助文本(extra)和垂直排列(direction='vertical')。

卡片样式

version: >=1.30.0
可以给 RadioGroup 设置 type='card' 实现带有背景的卡片样式。

无 radio 的纯卡片样式

version: >=1.30.0
可以给 RadioGroup 设置 type='pureCard' 实现带有背景且无 radio 的纯卡片样式。

配置 options

通过配置 options 参数来渲染单选框

API 参考

Radio

属性说明类型默认值
addonClassName包裹内容容器的样式类名
v1.16.0 后提供
string
addonIdaddon 节点 id,aria-labelledby 指向这个 id,若无设置会随机生成一个 id
v2.11.0 后提供
string
addonStyle包裹内容容器的内联样式
v1.16.0 后提供
CSSProperties
aria-labelRadio 的 labelstring-
nameRadio组件中input[type="radio"]name属性,具有相同name的Radio属于同一个RadioGroup,name属性可参考MDN Radiostring-
autoFocus自动获取焦点booleanfalse
checked指定当前是否选中booleanfalse
type设置 radio的样式类型,可选值为:defaultbuttoncardpureCard
该 api 在 v2.18.0 后提供
stringdefault
className样式类名string
defaultChecked初始是否选中booleanfalse
disabled禁选单选框booleanfalse
extra副文本,只对type='default'生效
v0.25.0 后提供
ReactNode-
extraId副文本的 id,aria-describedby 指向这个 id,若无设置会随机生成一个 id
v2.11.0 后提供
ReactNode-
mode高级和普通模式,高级模式可以在 checked 时点击变成 unchecked,可选值 advancedstring-
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
style内联样式CSSProperties
value根据 value 进行比较,判断是否选中string | number-
onChange选项变化时的回调函数function(e:Event)-
onMouseEnter鼠标移入选项时的回调函数function(e:Event)-
onMouseLeave鼠标移出选项时的回调函数function(e:Event)-

RadioGroup

单选框组合,用于包裹一组 Radio
属性说明类型默认值
aria-labelRadioGroup 的 labelstring-
buttonSizetype='button'的radio的尺寸大小,可选值为:smallmiddlelarge
v1.26.0 后提供
stringmiddle
className样式类名string
defaultValue默认选中的值string | number-
directionradio 排列方向, 只对type='default'生效,可选值horizontalvertical
v0.31.0 后提供
stringhorizontal
disabled禁选所有子单选器booleanfalse
mode高级和普通模式,可以在 checked 时点击变成 unchecked,可选值 advanced
v1.9.0 后提供
string-
nameRadioGroup 下所有 input[type="radio"]name 属性string-
options以配置形式设置子元素Array-
style内联样式CSSProperties
value用于设置当前选中的值string | number-
type设置所有radio的样式类型,可选值为:defaultbuttoncardpureCard
该 api 在 v1.26.0 后提供,其中 card 和 pureCard 在 v1.30.0 后提供
stringdefault
onChange选项变化时的回调函数function(e:Event)-

方法

Radio

名称描述
blur()移除焦点
focus()获取焦点

Accessibility

ARIA

  • aria-label:用于解释 Radio 或 RadioGroup 的作用
  • aria-labelledby 默认指向 addon 节点,用于解释 Radio 的内容
  • aria-describedby 默认指向 extra 节点,用于补充解释 Radio 的内容

键盘和焦点

  • RadioGroup 可以被获取焦点,初始焦点设置:
    • 当 RadioGroup 中没有被选择项时,初始焦点为第一个 Radio 项上
    • 当 RadioGroup 中有选中项时,初始焦点为选中的 Radio 项上
  • 在同一个 radiogroup 内
    • 可以通过 右箭头下箭头 将焦点移动到下一个 Radio 项上,同时取消先前的 Radio 项的选中状态,并选中当前聚焦的 Radio 项
    • 可以通过 左箭头上箭头 将焦点移动到上一个 Radio 项上,同时取消先前的 Radio 项的选中状态,并选中当前聚焦的 Radio 项
  • 若 RadioGroup 中没有选中项,可以 Space 键选中初始焦点

文案规范

  • 首字母大写
  • 不使用标点符号

设计变量