前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载RadioButton单选按钮是 Material Design 中互斥选择的核心控件。本文将围绕 react-toolbox 仓库中 components/radio/readme.md 展开完整讲解 RadioGroup 与 RadioButton 的属性 API、受控用法、事件机制、源码级实现原理以及 CSS Modules 主题定制方案。读完本文你将能在 react-toolbox 项目中正确、熟练地使用单选组件并深入理解其底层组合工厂与主题系统。一、什么是 RadioButton何时该使用它RadioButton 允许用户从一组选项中选择一个。Material Design 规范建议当用户需要并排看到所有可选选项、且选择互斥exclusive selection时使用单选按钮如果选项较多、空间有限则应改用下拉框dropdown因为下拉框比平铺展示所有选项更节省空间。在 react-toolbox 中单选按钮必须配合RadioGroup一起使用——单个 RadioButton 无法独立表达一组互斥选项的语义。RadioGroup负责维护当前选中值并把checked、disabled、onChange等状态自动派发给内部每个 RadioButton。主题注入键文档给出的主题 key 为ToolboxButton原文档如此描述在源码层面组件实际通过themr(RADIO, theme)注册主题RADIO常量定义于 components/identifiers.js默认主题样式来自 components/radio/theme.module.css。二、快速开始一个完整可运行的示例从react-toolbox/lib/radio导入RadioGroup与RadioButton然后像使用任何受控组件一样维护选中值。以下示例直接取自 components/radio/readme.mdimport { RadioGroup, RadioButton } from react-toolbox/lib/radio; class RadioTest extends React.Component { state { value: vvendetta }; handleChange (value) { this.setState({value}); }; render () { return ( RadioGroup namecomic value{this.state.value} onChange{this.handleChange} RadioButton labelThe Walking Dead valuethewalkingdead/ RadioButton labelFrom Hell valuefromhell disabled/ RadioButton labelV for a Vendetta valuevvendetta/ RadioButton labelWatchmen valuewatchmen/ /RadioGroup ); } }要点解析RadioGroup的value是当前选中值onChange在选中值变化时回调回调参数为被选中 RadioButton 的value每个RadioButton通过value标识自身label为显示文本disabled可使单个选项禁用示例中V for a Vendetta的value为vvendetta与初始state.value一致因此默认处于选中状态。仓库 spec/components/radio.js以及 TypeScript 版本 spec/ts/radio.tsx中还有一个更完整的演示额外展示了onFocus/onBlur的用法RadioGroup namecomic value{this.state.value} onChange{this.handleChange} RadioButton labelThe Walking Dead valuethewalkingdead / RadioButton labelFrom Hell valuefromhell disabled / RadioButton labelV for a Vendetta valuevvendetta onFocus{this.handleFocus} / RadioButton labelWatchmen valuewatchmen onBlur{this.handleBlur} / /RadioGroup三、RadioGroup API容器如何管理选中状态RadioGroup是单选组的容器。它接收的属性和事件会被有选择地派发给子级但每个 RadioButton 也可以独立声明自己的行为。3.1 属性总览来自原文档NameTypeDefaultDescriptionclassNameString为组添加类用于自定义样式。disabledBooleanfalse为 true 时整个组以禁用状态显示。nameString输入元素组的 name。onChangeFunction值变化时被调用的回调函数。valueAny单选组中默认选中的值。3.2 源码实现状态如何下发给子级在 components/radio/RadioGroup.js 中renderRadioButtons()使用React.Children.map遍历子元素并通过isComponentOfType来自 components/utils/is-component-of-type.js判断子级是否为 RadioButton只对真正的 RadioButton 注入派生属性React.Children.map(this.props.children, child ( !isComponentOfType(RadioButton, child) ? child : React.cloneElement(child, { checked: child.props.value this.props.value, disabled: this.props.disabled || child.props.disabled, onChange: this.handleChange.bind(this, child.props.value), }) ))由此可以推断出三条关键规则checked完全由组决定child.props.value this.props.value选中逻辑与每个按钮自身的checked属性无关disabled是或关系组禁用或按钮自身禁用任一为 true 即禁用onChange被包装点击某个按钮触发的是handleChange它把该按钮的value作为第一个参数回调this.props.onChange(value, event)这正是示例中handleChange (value) ...能直接拿到值的原因。非 RadioButton 的子元素如普通节点会被原样保留因此你可以在组内混排说明文字等自定义内容。3.3 组级禁用RadioGroup的默认disabled为false。设置为true后所有子按钮均显示为禁用态CSS 层面由disabled主题类控制见第五节。四、RadioButton API单个选项的行为与事件RadioButton是构成单选组的内部组件渲染为 HTMLinput typeradio与它相关的属性会透传给该 input 元素。4.1 属性总览来自原文档NameTypeDefaultDescriptioncheckedBooleanfalse为 true 时input 元素默认被选中。由父级传递。classNameString为单选按钮添加类用于自定义样式。disabledBooleanfalse为 true 时该项以禁用状态显示。labelStringornode单选按钮的标签文本。nameStringinput 元素的 name。onBlurFunctioninput 失焦时被调用的回调函数。onChangeFunction值变化时被调用的回调函数。onFocusFunctioninput 聚焦时被调用的回调函数。valueAny单选按钮的值。4.2 源码实现点击、聚焦与渲染逻辑components/radio/RadioButton.js 是核心实现有几个值得注意的细节点击事件处理。组件通过handleClick接管点击逻辑handleClick (event) { const { checked, disabled, onChange } this.props; if (event.pageX ! 0 event.pageY ! 0) this.blur(); if (!disabled !checked onChange) onChange(event, this); };它做了两件事当点击来自真实鼠标pageX/pageY非 0时先调用blur()移除焦点光环然后再在未禁用且未选中且有回调的前提下触发onChange(event, this)——注意回调的第二个参数是组件实例本身。聚焦/失焦代理。focus()与blur()通过ref挂载的inputNode代理到底层 input 元素从而让onFocus/onBlur能作用在真实的原生 input 上。渲染结构。render 输出如下 DOM 结构label>const factory (ripple) { const Radio ({ checked, onMouseDown, theme, ...other }) ( div >const ThemedRadio radioFactory(themedRippleFactory({ centered: true, spread: 2.6 })); const ThemedRadioButton themr(RADIO, theme)(radioButtonFactory(ThemedRadio)); const ThemedRadioGroup themr(RADIO, theme)(radioGroupFactory(ThemedRadioButton));radioFactory生成圆点 DOMthemedRippleFactory({ centered: true, spread: 2.6 })来自 components/ripple为圆点注入居中、扩散系数为 2.6 的波纹效果radioButtonFactory把圆点与原生 input、label 组装成完整按钮radioGroupFactory把多个按钮组装成互斥组最外层themr(RADIO, theme)react-css-themr 的注入函数把 components/radio/theme.module.css 的类名映射到themeprop。由此可知完整事件链路为用户点击 label → 原生 input 的 onClick 触发 handleClick → 若可选中则回调 onChange → RadioGroup 的 handleChange 把该按钮 value 上报给父级 → 父级 setState 更新 group 的 value → cloneElement 重新计算 checked 并触发重渲染。这也是它天然受控的原因。六、主题定制Theming 类名与 CSS 结构react-toolbox 采用 CSS Modules react-css-themr 实现主题化。通过给themeprop 传入类名映射即可替换任意内部样式。6.1 可注入的主题类来自原文档NameDescriptiondisabled单选按钮禁用时添加到根节点。field作为组件的根类使用。input用于 input 元素。radio用于单选圆点元素。radioChecked单选圆点处于选中状态时使用。ripple为波纹效果提供样式。text用于文本标签元素。对应 TypeScript 声明见 components/radio/RadioButton.d.tsRadioButtonTheme与 components/radio/base.d.tsRadioThemeradio、radioChecked、ripple。6.2 默认主题的视觉实现源码视角components/radio/theme.module.css 展示了单选圆点的绘制思路主题定制时可以此为参考.radio通过border: calc(0.2 * var(--unit)) solid var(--radio-text-color)与border-radius: 50%画出外圈内部圆点由::before伪元素实现默认transform: scale(0)不可见并通过transition: transform 0.2s var(--animation-curve-default)平滑过渡.radioCheckedcomposes: radio继承外圈样式同时border-color切换为主题色var(--radio-inner-color)::before通过transform: scale(0.65)显示内部实心圆点.ripple波纹颜色为主题色、透明度 0.3过渡时长 650ms.disabled文字、圆点边框、选中圆点内部均切换为禁用色var(--radio-disabled-color)且cursor: auto.input原生 input 被绝对定位、尺寸为 0、opacity: 0完全隐藏但保留了:focus ~ .radio/:focus ~ .radioChecked的兄弟选择器从而在键盘聚焦时用box-shadow绘制聚焦光环无障碍友好。6.3 可调样式变量主题变量集中在 components/radio/config.module.css定制尺寸与配色时可以直接覆盖这些 CSS 变量变量默认值含义--radio-field-margin-bottomcalc(1.5 * var(--unit))每个选项底边距--radio-button-sizecalc(2 * var(--unit))圆点直径--radio-inner-colorvar(--color-primary)选中圆点/内点主题色--radio-focus-colorcolor-mod(var(--color-black) a(10%))未选中聚焦光环色--radio-checked-focus-colorcolor-mod(var(--color-primary) a(26%))选中聚焦光环色--radio-text-colorvar(--color-black)标签文字颜色--radio-disabled-colorcolor-mod(var(--color-black) a(26%))禁用态颜色--radio-text-font-sizecalc(1.4 * var(--unit))标签文字字号七、TypeScript 支持组件附带了完整的类型声明components/radio/index.d.ts模块入口默认导出RadioButton并重新导出RadioGroup及相关类型components/radio/RadioButton.d.tsRadioButtonProps含checked、disabled、label、name、onBlur、onChange、onFocus、value、theme与RadioButtonThemecomponents/radio/RadioGroup.d.tsRadioGroupProps含children、disabled、name、onChange、value。在 TypeScript 项目中可以直接获得属性提示与类型校验spec/ts/radio.tsx 提供了可参考的 TS 用法示例。八、小结react-toolbox 的 RadioButton 是一组受控容器 独立选项的经典组合使用上牢记RadioGroup的value/onChange是状态中枢checked完全由组计算得出按钮自身的checked属性实际上由父级传递结构上按钮由隐藏的原生 input、CSS 绘制的圆点、文本标签与 ripple 波纹叠加而成天然具备键盘聚焦与无障碍支持主题上通过 react-css-themr 注入field、radio、radioChecked、ripple、disabled、text、input等类名即可深度定制配合 components/radio/config.module.css 的变量可实现尺寸与配色的一体化调整。对照 spec/components/radio.js 中的演示你可以直接在其基础上验证受控切换、禁用态与焦点事件的全部行为。赞分享前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载相关推荐Ant Design 按钮样式单选框RadioButton 与 RadioGroup 组合实战指南Ant Design 按钮样式单选框RadioButton 与 RadioGroup 组合实战指南 Ant Design 在标准圆形单选控件之外提供了按钮样UI组件前端设计系统PyPagekite深度解析Python实现的隧道反向代理工具PyPagekite深度解析Python实现的隧道反向代理工具 PyPagekite是一款基于Python实现的隧道反向代理工具能够轻松穿透NAT和防火墙限Material Components for Android 单选按钮RadioButton开发指南M3 属性、状态与主题定制Material Components for Android 单选按钮RadioButton开发指南M3 属性、状态与主题定制 Material ComUI组件移动开发设计系统上一篇ONNX GraphSurgeon 节点删除实战重连图结构并用 cleanup 完成清理下一篇企业级部署实践基于vLLM高效运行DeepSeek V2 Lite大模型全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考