Taro Radio 与 RadioGroup 单选组件深度解析API、源码实现与跨端实践【免费下载链接】taro开放式跨端跨框架解决方案支持使用 React/Vue/Nerv 等框架来开发微信/京东/百度/支付宝/字节跳动/ QQ 小程序/H5/React Native 等应用。 https://taro.zone/项目地址: https://gitcode.com/NervJS/taro导读本文以 radio 组件文档 为核心系统讲解 Taro 内置单选组件Radiotaro-radio-core与RadioGrouptaro-radio-group-core的完整 API、事件模型、互斥选中原理及跨端行为差异。通过结合 radio.tsx、radio-group.tsx 源码、类型定义 与 端到端测试你将掌握如何正确使用单选组、理解change事件的detail.value语义并能在 React / Vue3 工程中写出可复制的表单单选场景。一、组件定位与使用场景Radio是 Taro 提供的“单项选择器”基础组件通常与RadioGroup搭配使用实现一组互斥的单选项。在 类型定义 中RadioGroup被标注为classification forms属于表单类组件支持 weapp、alipay、swan、tt、qq、jd、h5、rn、harmony、harmony_hybrid、ascf 等平台详见 Radio.d.ts 与 RadioGroup.d.ts 的supported注释。两个核心自定义元素由 index.ts 统一导出并最终在 components/index.ts 中汇聚随taro-components包分发。典型使用方式RadioGroup包裹一组Radio选中某一项后自动取消其他项并通过change事件把选中项的value传出。二、API 说明以 readme 为准结合类型定义校正原文档 readme.md 给出了两组 API 表下面完整继承并补充来源依据。2.1 radio 属性属性类型默认值说明valueStringradio/标识。当该radio/选中时radio-group/的 change 事件会携带该radio/的 valuecheckedBooleanfalse当前是否选中disabledBooleanfalse是否禁用colorColor#09BB07radio 的颜色同 css 的 colorbindchangeEventHandle选中项发生变化时触发 change 事件nameanyundefined组件名字用于表单提交获取数据h5、harmony、harmony_hybrid 支持见 RadioGroup.d.ts说明readme 表格中 value / color 的默认值写作false实为文档笔误。从源码看radio.tsx 中value 、checked false、disabled falsecolor的默认值#09BB07在 Radio.d.ts 中有明确标注。本文按源码与类型定义给出准确默认值。2.2 radio-group 属性属性类型默认值说明bindchangeEventHandleradio-group/中选中项发生改变时触发 change 事件detail { value: [选中的 radio 的 value 的数组] }namestring组件名字用于表单提交获取数据alipay、tt、harmony 支持在 React 工程中bindchange以onChange属性书写事件对象结构在 RadioGroup.d.ts 中定义为onChangeEventDetail { value: string[] }与文档描述一致。三、源码实现从 Web Components 到事件链路Taro 的 H5 / Harmony 侧 Radio 组件基于 StencilJS 的 Web Components 实现两个标签分别是taro-radio-core与taro-radio-group-core。下面逐层拆解。3.1 Radio原生 input 的封装radio.tsx 的渲染结果结构如下Host classweui-cells_checkbox onClick{this.handleClick} input typeradio name{name} value{value} classweui-check checked{checked} disabled{disabled} onChange{e e.stopPropagation()} {...nativeProps} / i classweui-icon-checked / slot / /Host关键点视觉样式基于 weui外容器使用weui-cells_checkbox选中图标由weui-icon-checked提供内部文本通过slot /透传因此Radio内可以直接书写文字或Label。点击逻辑handleClickradio.tsx先stopPropagation若disabled直接返回未选中时把checked置为true。受控同步checked是mutable reflect属性radio.tsx外部尤其 RadioGroup 互斥逻辑修改后能同步回 DOM。Watch(checked)radio.tsx在组件完成首次加载isWillLoadCalled后若变为选中就向外发射radiochange事件detail携带{ value }。表单语义nativeProps可把任意属性透传到内部原生inputRadio.d.ts 标注仅 h5、harmony_hybrid 支持。3.2 RadioGroup互斥选中的真正实现radio-group.tsx 承担了单选组的核心职责监听子项事件通过Listen(radiochange)radio-group.tsx接收子taro-radio-core的广播先stopPropagation并校验e.target.tagName TARO-RADIO-CORE防止误收。互斥算法目标项被选中后遍历组内所有taro-radio-core把除目标外的其余项checked全部置为false随后把选中值存入私有字段#value并对外发射change事件detail.value为选中的 value 字符串。name 自动下发componentDidLoad时radio-group.tsx若未显式提供name会使用Date.now().toString(36)生成唯一名统一设置到每个子input上保证同一组内的单选name一致、浏览器原生表单语义正确。value 属性注入通过Object.defineProperty(this.el, value, ...)为taro-radio-group-core元素定义了只读valuegetter首次访问时扫描子项中input.checked为真的值getValuesradio-group.tsx便于表单取值。这一“子项广播 → 组互斥 → 组再广播 change”的链路与 checkbox-group.tsx监听checkboxchange是同构设计理解 RadioGroup 后即可触类旁通。四、事件与表单集成细节4.1 change 事件的 value 语义原文档强调“detail value:[选中的 radio 的 value 的数组]”。需要说明的是H5 实现中实际发射的是单个字符串this.onChange.emit({ value: this.#value })radio-group.tsx其中#value是选中的单个value。类型层面RadioGroup.d.ts 的value: string[]保留了“数组”语义以对齐小程序端文档实际取值时建议以e.detail.value为准做兼容处理React 侧常见写法e.detail.value直接作为字符串使用。4.2 表单场景验证form.e2e.ts 展示了RadioGroup与form的配合为组设置namemy-radio-group后点击radio1对应项表单提交数据中即出现my-radio-group: radio1见 form.e2e.ts证明namevalue能正确参与表单序列化。这正是 RadioGroup.d.ts 中name属性“用于表单提交获取数据”的落地验证。五、React 与 Vue3 实战示例以下示例直接取自 Radio.d.ts 的example_react/example_vue注释可直接在 Taro 工程中使用。5.1 React 写法import { Component } from react import { View, Text, Radio, RadioGroup, Label } from tarojs/components export default class PageRadio extends Component { state { list: [ { value: 美国, text: 美国, checked: false }, { value: 中国, text: 中国, checked: true }, { value: 巴西, text: 巴西, checked: false } ] } render () { return ( View classNamecontainer View classNamepage-section Text默认样式/Text Radio value选中 checked选中/Radio Radio stylemargin-left: 20rpx value未选中未选中/Radio /View View classNamepage-section Text推荐展示样式/Text View classNameradio-list RadioGroup {this.state.list.map((item, i) ( Label classNameradio-list__label for{i} key{i} Radio classNameradio-list__radio value{item.value} checked{item.checked}{item.text}/Radio /Label ))} /RadioGroup /View /View /View ) } }5.2 Vue3 写法template view classcontainer radio value选中 :checkedtrue选中/radio radio stylemargin-left: 20rpx; value未选中未选中/radio radio-group changeonChange label v-foritem in list :keyitem.value classradio-list__label radio :valueitem.value :checkeditem.checked{{ item.text }}/radio /label /radio-group /view /template script export default { data () { return { list: [ { value: yuche, text: yuche, checked: false }, { value: 隔壁老李, text: 隔壁老李, checked: true } ] } }, methods: { onChange (e) { console.log(e.detail.value) } } } /script六、端到端测试行为契约的可验证证据radio.e2e.ts 用 Stencil 的 E2E 工具验证了上述全部行为是理解组件契约的最佳参照单选基础行为radio.e2e.tsvalue属性映射到组件与内部input初始checked为false点击后组件与input的checked同时变为true。组互斥与事件radio.e2e.ts初始“中国”为选中态el.getProperty(value)包含China点击最后一个选项后原选中项被取消、末项选中value变为French且change事件恰好触发一次firstEvent.detail.value与value一致。这意味着“点谁选谁、其余自动取消、事件只发一次”是组件对外承诺的可测试行为业务方可在 H5 侧依赖该契约。七、跨端与进阶提示平台差异color属性在 weapp、alipay、swan、tt、qq、jd、rn、harmony、ascf 支持但不支持 h5Radio.d.tsH5 端如需自定义颜色应通过 CSS 覆盖weui-icon-checked等样式类。事件命名映射文档中的bindchange在 React / Vue3 中分别映射为onChange/changeTaro 编译器会自动完成绑定转换。与 Checkbox 对照RadioGroup的互斥机制与checkbox-group的“多选收集”机制同源详见 checkbox-group.tsx区别在于单选组最终只保留一个value而多选组聚合为数组。受控时机Watch(checked)在componentWillLoad之前不会发射事件radio.tsx因此初始化时设置checked不会产生多余的change事件开发者可放心在state中预设默认选中项。八、小结Radio/RadioGroup是一组“小而美”的表单组件外层RadioGroup以监听子项radiochange广播的方式实现互斥并在change事件中回传选中值内层Radio基于原生input[typeradio]封装天然保留表单语义。配合name属性即可无缝参与form提交。本文所有结论均可回溯到 readme.md、radio.tsx、radio-group.tsx、Radio.d.ts 与 radio.e2e.ts开发者可依此在 Taro 多端工程中放心使用。【免费下载链接】taro开放式跨端跨框架解决方案支持使用 React/Vue/Nerv 等框架来开发微信/京东/百度/支付宝/字节跳动/ QQ 小程序/H5/React Native 等应用。 https://taro.zone/项目地址: https://gitcode.com/NervJS/taro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考