Ant Design Radio 禁用态disabled完全指南从 Demo 用法到源码级状态传递原理【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designRadio单选框的禁用态看似是一个简单布尔值但它在 Ant Design 中实际是一条贯穿「组件自身属性 → Radio.Group 上下文 → ConfigProvider/Form 全局级联 → 底层原生 input」的完整状态链。本文以官方演示文档 components/radio/demo/disabled.mdRadio 不可用 / Radio unavailable与其对应示例 disabled.tsx 为主体结合 radio.tsx、group.tsx 等源码与单元测试系统讲解 Radio 禁用态的声明方式、三种作用域层级、底层实现原理以及如何用按钮动态切换禁用状态帮助你彻底掌握单选框禁用场景下的正确写法与排查思路。一、Demo 本体静态禁用 按钮动态切换官方disabled演示对应的完整示例位于 components/radio/demo/disabled.tsx展示两个禁用中的单选以及一个用于动态切换禁用状态的按钮import React, { useState } from react; import { Button, Radio } from antd; const App: React.FC () { const [disabled, setDisabled] useState(true); const toggleDisabled () { setDisabled(!disabled); }; return ( Radio defaultChecked{false} disabled{disabled} Disabled /Radio Radio defaultChecked disabled{disabled} Disabled /Radio br / Button typeprimary onClick{toggleDisabled} style{{ marginTop: 16 }} Toggle disabled /Button / ); }; export default App;该 Demo 值得拆解的要点两个 Radio 均通过disabled{disabled}绑定同一个 state初始值useState(true)表示页面刚渲染时两个单选框都是不可用状态与演示标题一致一个未选中、一个默认选中第一个defaultChecked{false}表示初始不选中第二个defaultChecked等价于defaultChecked{true}用于演示禁用状态下已选中项依然可见、但不能取消/切换的效果。由于这里采用的是非受控的defaultCheckeddisabled切换不会改变其选中结果动态切换由 Button 完成点击 Toggle disabled 后setDisabled(!disabled)取反 stateRadio 随之在禁用/可用之间切换直观验证禁用是运行时属性、可响应更新这一行为。Demo 说明文档的双语登记与disabled.tsx配套的 disabled.md 是 Ant Design 文档体系中标准的双语演示说明仅用两句话概括语义zh-CNRadio 不可用。en-USRadio unavailable.这类短说明在组件主文档 index.zh-CN.md代码演示章节中以code src./demo/disabled.tsx不可用/code的方式引用中对应着标题不可用 / Disabled承担的是一句话演示意图 可运行源码的组合结构真正的技术细节需要结合源码展开。二、API 语义Radio / Radio.Group / options 三处的 disabled在 index.zh-CN.md 的 API 表格中disabled出现在三个不同的位置作用域各不相同API 归属说明类型默认值Radio禁用 RadiobooleanfalseRadio.Group禁选所有子单选器booleanfalseoptions 中的单个 option指定 Radio 选项是否要禁用booleanfalse也就是说禁用并不是 Radio 组件的专利单个Radio disabled /只影响这一个单选框同时影响其所在的选项组语义——见下文的组上下文合并规则Radio.Group disabled /从组件类型定义看RadioGroupProps中声明了disabled?: boolean见 interface.ts其作用是将组内所有子 Radio 一并禁用options配置中的disabled使用options声明式配置组选项时可为某个具体选项单独设置disabled实现组可交互但个别选项不可选的细粒度控制该能力随 options 模式于 4.4.0 引入className字段 5.25.0 可用。类型定义层面单选本身的禁用能力继承自 checkbox 的AbstractCheckboxPropsRadioProps extends AbstractCheckboxPropsRadioChangeEvent其中包含disabled?: boolean与defaultChecked、checked、onChange等共享字段见 components/checkbox/Checkbox.tsx 中的AbstractCheckboxProps定义。三、禁用状态如何叠加与合并源码级原理掌握声明方式只是第一步。关键在于弄清多个层级的 disabled 同时出现时最终以谁为准。这一逻辑位于 radio.tsx 的渲染核心函数InternalRadio中。3.1 从 context 逐层读取单选框渲染时会读取两个上下文来补全自己的禁用状态radio.tsx#L69-L85// Disabled const disabled React.useContext(DisabledContext); // ConfigProvider / Form 级级联 ... if (groupContext) { radioProps.disabled radioProps.disabled ?? groupContext.disabled; } radioProps.disabled radioProps.disabled ?? disabled;其合并顺序可概括为一条优先级链Radio 自身 props.disabled最高 → Radio.Group 的 groupContext.disabled → ConfigProvider / Form 注入的 DisabledContext这一链式??空值合并写法保证了只要某一层显式声明了disabled就不再继续向后取默认值三个来源都未声明时最终为undefined底层 input 不写死禁用属性。3.2 Group 如何把禁用传给每个子项当使用Radio.Group时group.tsx 会把组级disabled通过两个通道下发给子项Context 通道RadioGroupContextProvider提供的memoizedValue中携带disabledgroup.tsx#L132-L135供所有子孙 Radio 通过React.useContext(RadioGroupContext)读取这正是上一步groupContext.disabled的数据来源options 渲染通道当以options声明子项时每个渲染出的 Radio 会执行disabled{option.disabled || disabled}group.tsx#L94-L110实现选项自身禁用优先级高于组禁用的效果——即option.disabled: true时即使组是启用态该项也禁用。因此 Demo 中两个直接书写的Radio若处于某个 Group 内只要 Group 加了disabled它们同样会被禁用无需逐个声明。3.3 全局级联ConfigProvider 与 FormDisabledContext来自 components/config-provider/DisabledContext.tsx其定义默认值为false并提供了DisabledContextProvider用于向下级联export const DisabledContextProvider: React.FCDisabledContextProps ({ children, disabled }) { const originDisabled React.useContext(DisabledContext); return ( DisabledContext.Provider value{disabled ?? originDisabled} {children} /DisabledContext.Provider ); };在 components/form/Form.tsx 中Form disabled正是通过包裹DisabledContextProvider把禁用状态注入表单内所有相关组件也就是说整个表单禁用与单个 Radio 禁用在源码层面共用同一套状态通道radio.tsx#L70 中的React.useContext(DisabledContext)即是该级联的消费端。四、禁用后发生了什么类名、水波与原生行为禁用不仅是逻辑上的状态还会同步反映到 DOM 与交互表现上从 radio.tsx 的渲染输出可以找到三处直接证据语义化类名wrapper 上会附加${prefixCls}-wrapper-disabledradio.tsx#L105-L121即默认前缀下为ant-radio-wrapper-disabled供主题样式调整禁用态视觉灰色圆点、弱化文字等原生 input 禁用底层实际渲染的是来自rc-component/checkbox、typeradio的组件radioProps包含最终合并出的disabled被整体透传radio.tsx#L138-L146。可以推断该属性最终落到真正的input typeradio disabled上从而从浏览器原生层面阻止选中变化并保证表单语义点击水波效果关闭Radio 外围包裹的Wave点击波纹显式传入了disabled{radioProps.disabled}radio.tsx#L128禁用态下点击不会产生按压水波动画交互反馈与视觉状态保持一致。此外在Radio.Group内部单选触发onChange时会先调用自身props.onChange再透传给组回调groupContext.onChangeradio.tsx#L41-L44。由于禁用 input 不会产生点击选中事件禁用项天然不会进入该回调链。五、测试验证优先级与取值行为仓库的单元测试直接锁定了上述合并语义。在 components/radio/tests/radio.test.tsx 中存在两条针对性用例it(should use own disabled status first, () { // Form disabledRadio disabled{false} //Form // expect(getByRole(radio)).not.toBeDisabled(); }); it(should obtained correctly disabled status, () { // Form disabledRadio.Group disabled{false}.../Radio.Group/Form // expect(getByRole(radio)).not.toBeDisabled(); });第一条验证自身禁用状态优先即使外层Form disabled只要 Radio 自身显式声明disabled{false}最终仍为可用态第二条验证组内覆盖同样生效Radio.Group disabled{false}也能在禁用表单环境中为组内子单选解禁。结合 3.1 中的??链可以发现两条用例恰好分别击中了链式优先级的第一段与第二段属于对自身 Group 全局级联规则的回归保障也解释了在某层显式关闭禁用即可抵消上层禁用这一重要使用技巧。六、实战建议小结回到 disabled.tsx 这个最小可运行场景可以把它的使用价值延伸到日常开发最简单的禁用给 Radio 加disabled即可无需关心底层多选一并禁用时改用Radio.Group disabled组内部分禁用改用options并在对应选项上声明disabled保留其余选项可交互受 Form 整体禁用影响时局部放行利用优先级链在 Radio 或 Radio.Group 上显式写disabled{false}其生效前提是理解Form disabled→DisabledContext→ Radio 这条级联路径动态切换将disabled绑定到 state 即可即 Demo 中useState Button 切换的范式注意若配合defaultChecked使用非受控选中禁用状态的切换不会重置选中值若需要禁用同时重置选中应改用受控checked与onChange。总而言之Ant Design 的 Radio 禁用态是一个组件属性 两级上下文 原生 input共同作用的结果Demo 展示了最直观的声明与动态切换用法源码则揭示了自身 props → Radio.Group → DisabledContext的合并优先级与 DOM 表现测试用例则为该优先级提供了可回归的依据。掌握这条链路后无论单选框嵌套在 Form、Radio.Group 还是纯独立场景你都能准确预判禁用行为。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考