跳到主要内容

Radio 单选Radio · RadioGroup

从一组互斥的选项里选一个，并且希望所有选项都摆在明面上。选项多于五六个时用 Select；两三个短选项也可以用 Segmented；带示意图的用 OptionCard。

基本用法

Radio 放在 RadioGroup 里使用。组放进 Field 会自动用 Field 的标签命名，否则请给 aria-label。

横向与说明文字

状态

请选择一种发票类型

受控用法

RadioGroup 的 onChange 参数是选中项的 value。value 传 null 表示都没选。

当前：pro

API

RadioGroup

属性类型默认值说明
valuestring | null—选中项的 value（受控）；null 表示没选。
defaultValuestring | nullnull初始选中项（非受控）。
onChange(value: string) => void—选中项变化时触发。
namestring自动生成字段名。同名的原生单选才能用方向键互相移动，所以不传也会生成一个。
orientation'vertical' | 'horizontal''vertical'排列方向。
disabledboolean—整组禁用。
requiredboolean—必填。
invalidboolean—校验失败。在 Field 里默认跟随 Field。

Radio

属性类型默认值说明
value*string—这一项的值。
descriptionReactNode—标签下的说明文字。
disabledboolean—禁用这一项。
onChange(value: string) => void—这一项被选中时触发。不在 RadioGroup 里单独使用时配合 checked / name 用。
rootClassName / rootStylestring / CSSProperties—外层 <label> 的类名与样式。className / style 同样落在 <label> 上。
…restInputHTMLAttributes—其余原生属性和 ref 落在 <input type="radio"> 上。

无障碍

  • 组是 role="radiogroup"，每一项是真的 <input type="radio">。
  • Tab 进入组时落在选中项上（都没选则落在第一项），再按 Tab 离开整组。
  • ↑ ↓ ← → 在组内移动并同时选中，到头循环；Space 选中当前项。这是同名原生单选的浏览器行为，没有用脚本重做。
  • 禁用项会被方向键跳过。
  • 组的名称来自 Field 的标签（aria-labelledby）或 aria-label；必填与校验状态通过 aria-required / aria-invalid 标在组上。