跳到主要内容

Radio 单选

受控单选控件。Radio 必须放在 Radio.Group 内,选中值与变更回调由组统一提供。

代码演示​

报表周期
客户等级
当前:日报 · VIP

状态​

状态视觉
未选20×20 圆,1.5px 描边 c.outline
已选20×20 圆,1.5px 主橙描边 + 中心 8×8 主橙圆点
禁用opacity: 0.5

用法​

import { Radio } from '@unif/react-native-design';

<Radio.Group value={tier} onChange={setTier} accessibilityLabel="客户等级">
<Radio value="vip" label="VIP 客户" />
<Radio value="normal" label="普通客户" />
<Radio value="pending" accessibilityLabel="待审核客户" />
</Radio.Group>;

API​

<Radio.Group>​

来源:src/components/ui/Radio/types.ts、RadioGroup.tsx。

参数类型默认值说明
valuestring | number—当前选中值(受控)
onChange(value: string | number) => void—切换回调
accessibilityLabelstring—单选组自身的 accessible name(必填)
childrenReactNode—<Radio> 列表(渲染为普通 <View>,组内 gap: space[1])
testIDstring?—容器 testID;每个 Radio 自动派生 ${testID}-${value}

<Radio>​

来源:src/components/ui/Radio/types.ts、Radio.tsx。

参数类型默认值说明
valuestring | number—此项的值(与 Group 的 value 比较得 checked)
labelstring与 accessibilityLabel 二选一可见右侧文字,同时作为默认 accessible name
accessibilityLabelstring与 label 二选一无可见文字时必填;有 label 时可覆盖读屏文案
disabledboolean?false禁用时移除 handler、上报 disabled 并半透明
testIDstring?—单项 testID(不传则从父 Group 派生 ${groupTestID}-${value})

<Radio> 必须放在 <Radio.Group> 内使用;脱离 Group 会打 warn 并渲染空 <View>。

RadioProps 是 named union:label: string 分支可选 accessibilityLabel;不渲染 label 的分支必须提供 accessibilityLabel: string。

无障碍(a11y)​

来源:src/components/ui/Radio/Radio.tsx、RadioGroup.tsx、types.ts。

  • 默认 role:每个有效命名的 <Radio> 是 'radio';<Radio.Group> 的本地 <View> 是 'radiogroup'。组名会 trim,空白时在 effect 诊断。
  • 单项 accessible name:优先 trim 后非空的 accessibilityLabel,否则回退可见 label;最终仍空白时移除 handler/action 语义并在 effect 诊断。
  • 状态语义:accessibilityState={{ checked, disabled: !!disabled }}——checked 由 Radio.Group 的受控 value 派生(ctx.value === value),disabled 映射本项 disabled prop。
  • 禁用语义:同时传 disabled={true} 与 onPress={undefined},不是在 handler 内静默 no-op。
  • 圆形指示器与可见文字只在本地 RN View / Text 上复用共享 A11Y_HIDDEN_PROPS,外层 radio 是唯一的选项焦点。
// label 同时作为 SR 朗读文案;checked 由 Group 的 value 决定
<Radio.Group value={tier} onChange={setTier} accessibilityLabel="客户等级">
<Radio value="vip" label="VIP 客户" />
<Radio value="normal" accessibilityLabel="普通客户" />
</Radio.Group>

与 Checkbox 的区别​

RadioCheckbox
同组只能选一个多选
圆形指示器方形指示器
用 <Radio.Group> 包裹独立使用,多个 <Checkbox>
适合"在 N 个选项中选一个"适合"勾选若干项"