Arco Design React 单选框 Radio 组件完全指南:API、单选组与源码原理
Arco Design React 单选框 Radio 组件完全指南:API、单选组与源码原理
在 Arco Design React 组件库中,Radio(单选框)用于在一组相关且互斥的数据中让用户只能选择一个选项,是表单场景中最常见的数据输入控件之一。本文将基于当前仓库中 components/Radio 的官方文档(components/Radio/README.en-US.md)、完整 API 定义与源码实现,系统讲解 Radio 与 Radio.Group 的全部配置参数、基础用法、按钮模式、尺寸与方向控制、自定义渲染等高阶用法,并深入源码解析其受控/非受控逻辑、Context 传值机制与样式 Token,帮助你从"会用到"进阶到"用得对、调得深"。
一、组件概览:Radio 的设计定位
Radio 组件隶属于 Arco Design React 的 Data Entry(数据输入)分类,其核心语义在官方文档中表述为:
在一组相关且互斥数据中,用户仅能选择一个选项。
这意味着 Radio 天然以"组"的形式存在,单个 Radio 之间通过相同的分组逻辑实现互斥。仓库中组件的入口文件 components/Radio/index.tsx 同时导出了 RadioProps 与 RadioGroupProps 两个类型,并在 components/Radio/radio.tsx 中通过 Radio.Group = Group 将分组能力挂载到 Radio 命名空间下,因此你可以通过 Radio.Group 或 import { RadioGroup } 的方式使用分组功能。
二、Radio 基础用法与 API 详解
2.1 最基础的用法
单选框可以直接独立使用,也可以与 Space 组合排列。官方基础示例(components/Radio/demo/basic.md)如下:
import { Radio, Space } from '@arco-design/web-react';
const App = () => {
return (
<Space size={40}>
<Radio>Radio</Radio>
<Radio checked disabled>
Disabled Radio
</Radio>
</Space>
);
};
export default App;
其中 checked 是受控属性,直接指定选中态;disabled 则禁用该单选框。需要说明的是,独立使用的 Radio 本身不提供"再次点击取消选中"之外的互斥逻辑,真正的互斥行为由 Radio.Group 承担。
2.2 Radio 全部 API 参数
根据官方文档(components/Radio/README.en-US.md)与类型定义文件 components/Radio/interface.ts,Radio 组件支持的属性如下:
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
checked |
是否选中(受控模式) | boolean |
- |
defaultChecked |
初始是否选中(非受控) | boolean |
- |
disabled |
是否禁用 | boolean |
- |
className |
节点类名 | string | string[] |
- |
style |
节点样式 | CSSProperties |
- |
value |
控件的 value |
T |
- |
onChange |
值变化的回调 | (checked: boolean, event: ChangeEvent) => void |
- |
children |
节点内容,也可以是函数 | ReactNode | ((value: { checked: boolean; disabled: boolean }) => ReactNode) |
- |
值得注意的两点实现细节:
- 泛型 value:
RadioProps<T = any>中的value是泛型类型T,意味着你可以传任意类型的值而不只是字符串; - children 函数:自
2.29.0起(见 components/Radio/changelog/index.zh-CN.md),children支持传入函数,接收{ checked, disabled }两个参数,用于完全自定义节点的渲染内容;到2.66.14时该回调进一步增加了disabled参数,以支持在禁用状态下展示不同内容。
2.3 受控与非受控切换的源码逻辑
Radio 内部通过 useMergeValue Hook(见 components/Radio/radio.tsx)同时处理受控与非受控两种模式:
const [checked, setChecked] = useMergeValue(false, {
value: mergeProps.checked,
defaultValue: mergeProps.defaultChecked,
});
当传入 checked 时,选中态完全由外部控制(受控);未传入时则退化为使用 defaultChecked 的初始值并内部维护状态(非受控)。其点击回调逻辑在 components/Radio/radio.tsx:
const onChange = (event) => {
const { onChange, value } = mergeProps;
if (disabled) return;
if (context.group) {
context.onChangeValue && context.onChangeValue(value, event);
} else if (!('checked' in props) && !checked) {
setChecked(true);
}
!checked && onChange && onChange(true, event);
};
对应测试 components/Radio/test/index.test.tsx 验证了:非受控模式下点击后元素会获得 arco-radio-checked 类名;而受控模式下(checked={false})点击后 onChange 被调用但类名保持不变——这正是受控组件"状态由外部决定"的行为特征。
三、Radio.Group 单选组:互斥的核心
3.1 两种声明方式:children 与 options
官方文档(components/Radio/README.en-US.md)指出 Radio.Group 支持两种用法:通过 children 组合子 Radio,或者通过 options 数组一次性配置。完整示例见 components/Radio/demo/radio_group.md:
import { Radio } from '@arco-design/web-react';
const RadioGroup = Radio.Group;
const App = () => {
return (
<div>
<RadioGroup defaultValue="a" style={{ marginBottom: 20 }}>
<Radio value="a">A</Radio>
<Radio value="b">B</Radio>
<Radio value="c">C</Radio>
<Radio disabled value="d">D</Radio>
</RadioGroup>
<RadioGroup options={['A', 'B', 'C', 'D']} style={{ marginBottom: 20 }} />
<RadioGroup
options={[
{ label: 'A', value: 'a' },
{ label: 'B', value: 'b' },
{ label: 'C', value: 'c' },
{ label: 'D', value: 'd', disabled: true },
]}
/>
</div>
);
};
其中 options 数组的每一项可以是:
string:如'A',此时 label 与 value 相同;number:同上;- 对象
{ label: ReactNode; value: any; disabled?: boolean }:label 支持任意 ReactNode(可传图标、富文本),并可单独控制该项的禁用状态。
3.2 Radio.Group 全部 API 参数
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
disabled |
禁用整个单选组 | boolean |
- |
name |
Radio 的 name 属性,用于表单提交分组 |
string |
- |
direction |
排列方向 | 'vertical' | 'horizontal' |
horizontal |
size |
按钮类型单选框尺寸(仅 type="button" 时生效) |
'small' | 'default' | 'large' | 'mini' |
- |
type |
单选类型 | 'radio' | 'button' |
radio |
mode |
按钮模式(源码扩展属性) | 'outline' | 'fill' |
outline |
className |
节点类名 | string | string[] |
- |
defaultValue |
默认选中的值(非受控) | any |
- |
options |
以数组配置的形式设置单选组 | (string | number | { label: ReactNode; value: any; disabled?: boolean })[] |
- |
style |
节点样式 | CSSProperties |
- |
value |
选中的值(受控模式) | any |
- |
onChange |
点击单选的回调 | (value: any, event: ChangeEvent) => void |
- |
其中 mode 属性存在于类型定义 components/Radio/interface.ts 与组件的默认配置(mode: 'outline')中,用于控制按钮类型的展示模式;defaultValue、value、onChange 三者的关系是:传 value + onChange 即受控模式,只传 defaultValue 即非受控模式。
3.3 Group 的 Context 互斥机制
Radio.Group 的互斥实现依赖 React Context。在 components/Radio/group.tsx 中创建了 RadioGroupContext,并把 { type, value, disabled, group: true, name, onChangeValue } 注入到 Provider 中(components/Radio/group.tsx):
const contextProp = {
onChangeValue,
type,
value,
disabled,
group: true,
name,
};
子 Radio 在 components/Radio/radio.tsx 中消费该 Context:
if (context.group) {
mergeProps.checked = context.value === props.value; // 由组的 value 决定选中态
mergeProps.disabled = 'disabled' in props ? props.disabled : context.disabled;
}
从源码结构看,子 Radio 的选中态完全由组的 value 与自身 value 的相等性决定,因此同一组内天然互斥;子级自身的 disabled 优先级高于组的 disabled("disabled in props" 时采用子级配置)。组的 onChangeValue 在 components/Radio/group.tsx 中统一分发:仅在值确实变化时才触发外部 onChange,且非受控模式下会先内部 setValue。
测试文件 components/Radio/test/group.test.tsx 覆盖了 children 与 options 两种声明方式、受控 value 切换、以及"组禁用 + 单项禁用"的优先级场景,可作为行为验证参考。
3.4 竖直单选组
设置 direction="vertical" 即可展示竖直排列的单选组(示例见 components/Radio/demo/direction.md):
<RadioGroup direction="vertical" defaultValue="a">
<Radio value="a">A</Radio>
<Radio value="b">B</Radio>
<Radio value="c">C</Radio>
<Radio disabled value="d">D</Radio>
</RadioGroup>
样式层面对应的规则在 components/Radio/style/index.less:竖直方向下 .arco-radio 变为 display: block 且清除水平间距,按钮类型则会隐藏相邻按钮之间的分割线。
四、按钮类型(type="button")与尺寸控制
4.1 按钮样式单选组
指定 type="button" 后,单选组会以按钮组的形式呈现,通常用于"分段选择"类交互(示例见 components/Radio/demo/radio_button.md):
<RadioGroup type="button" name="lang" defaultValue="Guangzhou" style={{ marginRight: 20, marginBottom: 20 }}>
<Radio value="Beijing">Beijing</Radio>
<Radio value="Shanghai">Shanghai</Radio>
<Radio disabled value="Guangzhou">Guangzhou</Radio>
<Radio value="Shenzhen">Shenzhen</Radio>
</RadioGroup>
从源码看,type === 'button' 时子 Radio 的类名变为 arco-radio-button(components/Radio/radio.tsx),渲染的文本容器变为 .arco-radio-button-inner(components/Radio/radio.tsx),并借助 components/Radio/style/index.less 中的伪元素实现按钮间的分割线、选中态背景与 hover 效果——选中按钮两侧的分割线会自动消失。
4.2 四个尺寸
按钮类型的单选组共分 4 个尺寸:mini、small、default、large(示例见 components/Radio/demo/size.md):
<RadioGroup options={options} size="mini" type="button" defaultValue="Beijing" />
<RadioGroup options={options} size="small" type="button" defaultValue="Beijing" />
<RadioGroup options={options} size="default" type="button" defaultValue="Beijing" />
<RadioGroup options={options} size="large" type="button" defaultValue="Beijing" />
尺寸规则定义在样式文件 components/Radio/style/index.less:default 对应默认行高 @radio-size-default-height,small、large、mini 分别切换为 @radio-size-small-height、@radio-size-large-height、@radio-size-mini-height,同时联动字体大小(如 mini 使用 @radio-font-text-size_mini,即 @font-size-body-1,见 components/Radio/style/token.less)。
另外,Group 中 const size = props.size || ctxSize(components/Radio/group.tsx)表明:未显式传 size 时,会回退使用 ConfigProvider 注入的全局上下文尺寸,方便整体控制组件尺寸体系。
五、自定义渲染:函数式 children(2.29.0+)
5.1 函数 children 的核心用法
从 2.29.0 版本起(components/Radio/changelog/index.zh-CN.md),Radio 支持将 children 写为函数,接收 { checked, disabled } 并返回任意节点。官方示例 components/Radio/demo/custom_render.md 展示了两种典型场景:
按钮风格的卡片单选(用 checked 状态驱动 Button 类型):
<Radio.Group defaultValue="Beijing" name="button-radio-group">
{['Beijing', 'Shanghai', 'Guangzhou'].map((item) => (
<Radio key={item} value={item}>
{({ checked }) => (
<Button tabIndex={-1} shape="round" type={checked ? 'primary' : 'default'}>
{item}
</Button>
)}
</Radio>
))}
</Radio.Group>
自定义卡片单选:
<Radio.Group name="card-radio-group">
{[1, 2].map((item) => (
<Radio key={item} value={item}>
{({ checked }) => (
<Space
align="start"
className={`custom-radio-card ${checked ? 'custom-radio-card-checked' : ''}`}
>
<div className="custom-radio-card-mask">
<div className="custom-radio-card-mask-dot"></div>
</div>
<div>
<div className="custom-radio-card-title">Radio Card {item}</div>
<Typography.Text type="secondary">this is a text</Typography.Text>
</div>
</Space>
)}
</Radio>
))}
</Radio.Group>
5.2 实现原理与无障碍细节
函数 children 的实现位于 components/Radio/radio.tsx:当 isFunction(children) 时,直接调用 children({ checked, disabled }) 渲染自定义内容,并跳过默认的圆形 mask 与文本渲染。
这里有一个值得注意的交互细节:由于自定义内容中可能包含表单元素,label 的默认行为会导致点击无法触达隐藏的 input<a href="https://link.gitcode.com/i/f25e0a55be236096514b717c5c5e5425" target="_blank">type=radio],因此源码在 [components/Radio/radio.tsx 中通过 onLabelClick 对函数 children 场景调用 e.preventDefault() 并手动触发 inputRef.current.click(),确保点击自定义内容时选中逻辑依然正常。配套的 CSS(示例中的 :focus-visible + .arco-btn、.custom-radio-card 系列规则)则用来补充键盘聚焦时的视觉反馈。
六、带图标的单选框与组合示例
Radio 的 children 是任意 ReactNode,因此可以直接在文本旁组合图标或图片(示例见 components/Radio/demo/icon.md):
<RadioGroup>
<Radio value="BCY">
<img src="..." style={{ width: 30, height: 30, verticalAlign: 'middle' }} />
BCY
</Radio>
<Radio disabled value="xigua">
<img src="..." style={{ width: 30, height: 30, verticalAlign: 'middle' }} />
Xigua Video
</Radio>
</RadioGroup>
这也印证了 options 对象形式中 label: ReactNode 的类型设计——富文本内容可以完全复用 children 的渲染通道。
七、样式体系与主题定制
7.1 类名结构与样式入口
Radio 的样式入口为 components/Radio/style/index.less,其类名体系包括:
.arco-radio:普通单选框(含圆形 mask);.arco-radio-button:按钮类型;.arco-radio-group/.arco-radio-group-type-button:分组容器;.arco-radio-group-direction-vertical:竖直排列;.arco-radio-size-{mini|small|default|large}:按钮尺寸;.arco-radio-mode-{outline|fill}:按钮模式;.arco-radio-rtl/.arco-radio-group-rtl:RTL 布局适配。
其中隐藏的 input<a href="https://link.gitcode.com/i/392c40708913cd0099e23dab22aa8c56" target="_blank">type=radio] 通过 opacity: 0; width: 0; height: 0 在视觉上隐藏但仍保持可访问性([components/Radio/style/index.less),键盘焦点通过 :focus-visible + 选择器映射到可见的 mask/按钮上。
7.2 设计 Token
样式 Token 集中在 components/Radio/style/token.less,均引用 Arco 的 CSS 变量(如 --color-primary-6、--color-neutral-3),这意味着你可以通过 ConfigProvider 的主题配置或在全局 CSS 中覆盖这些 CSS 变量来完成定制,而无需修改源码:
- 圆形 mask:边框色
--color-neutral-3、选中背景@color-primary-6、圆形圆角@radius-circle; - 文字与禁用态:
--color-text-1、--color-text-4; - 按钮类型:选中背景
--color-bg-5、选中文字@color-primary-6、加粗@font-weight-500,分割线使用--color-neutral-3的 1px 竖线; - 暗色模式:
<a href="https://link.gitcode.com/i/b4892372716acf616a1020a6e276f071" target="_blank">arco-theme='dark']下按钮选中背景切换为--color-fill-3(见 [components/Radio/style/index.less)。
八、测试保障与版本演进要点
仓库为 Radio 提供了三层测试保障:
- 挂载与组件配置测试:
mountTest(Radio)与componentConfigTest(Radio, 'Radio')(components/Radio/test/index.test.tsx)确保组件可正常挂载且支持ConfigProvider级别的组件默认配置; - 分组行为测试:components/Radio/test/group.test.tsx 覆盖受控切换、children/options 双声明方式、禁用优先级;
- Demo 冒烟测试:components/Radio/test/demo.test.ts 通过
demoTest('Radio')渲染全部官方示例,防止示例代码回归。
从 components/Radio/changelog/index.zh-CN.md 的演进记录看,组件经历了多个关键迭代:2.29.0 引入函数 children 自定义渲染;2.34.0 完善 children 的 TS 定义;2.51.0 修复 children 为 0 时文本色异常;2.62.0 修复组禁用与子项禁用配置的优先级问题;2.66.12 修复按钮类型下 direction="vertical" 不生效的问题;2.66.14 为函数 children 增加 disabled 参数。这些记录为你在升级依赖时的行为变化排查提供了参考。
结语
从独立 Radio 的受控/非受控双模式,到 Radio.Group 基于 Context 的互斥机制,再到按钮类型、尺寸体系、函数 children 自定义渲染与主题 Token,Arco Design React 的 Radio 组件在保持简单 API 的同时提供了完整的定制能力。建议你在实际项目中优先使用 Radio.Group + options 的配置式写法处理常规选项,仅在需要高度自定义的视觉场景(卡片、图标按钮等)时使用函数 children,并善用 ConfigProvider 统一控制按钮尺寸与全局配置。