Arco Design React 单选框 Radio 组件完全指南:API、单选组与源码原理

原创2026-10-15 09:19:341,686 阅读
文章标签:UI组件前端设计系统

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) -

值得注意的两点实现细节:

  1. 泛型 value:RadioProps<T = any> 中的 value 是泛型类型 T,意味着你可以传任意类型的值而不只是字符串;
  2. 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 提供了三层测试保障:

  1. 挂载与组件配置测试:mountTest(Radio) 与 componentConfigTest(Radio, 'Radio')(components/Radio/test/index.test.tsx)确保组件可正常挂载且支持 ConfigProvider 级别的组件默认配置;
  2. 分组行为测试:components/Radio/test/group.test.tsx 覆盖受控切换、children/options 双声明方式、禁用优先级;
  3. 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 统一控制按钮尺寸与全局配置。

登录后查看全文
arco-design