ElementVue 2 UI ToolkitRadio 单选框组件完全指南基础用法、分组、按钮样式与源码剖析【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element本指南以examples/docs/es/radio.md文档为核心系统讲解 ElementA Vue.js 2.0 UI Toolkit for Web中el-radio单选框组件的基础用法、禁用状态、单选框组、按钮样式与带边框形态并结合packages/radio、packages/radio-group、packages/radio-button等源码与test/unit/specs/radio.spec.js测试用例深入剖析其 v-model 双向绑定机制、组件间通信与键盘导航实现。读完本文你将掌握 Radio 组件的全部属性、事件与实战写法并能理解其在表单校验中的联动原理。一、组件概览与适用场景Radio单选框用于在一组备选项中进行单选。Element 文档明确给出了一条重要的使用边界由于选项默认可见选项数量不宜过多若选项过多建议改用 Select 选择器。因此在决定使用el-radio前应先评估选项规模——少量互斥选项如性别、状态、城市枚举适合单选框而长列表则更适合 Select 选择器。组件由三个可组合的构件组成el-radio基础单选项支持独立使用或放入组内el-radio-group单选框组容器负责统一管理选中值、禁用状态、尺寸与键盘导航el-radio-button按钮风格的单选项必须配合el-radio-group使用。三者通过 packages/radio/index.js、packages/radio-group/index.js、packages/radio-button/index.js 注册为全局组件组件名分别为ElRadio、ElRadioGroup、ElRadioButton可直接在模板中以el-radio形式使用。二、基础用法v-model 与 label 的绑定关系要使用 Radio 组件只需设置v-model绑定变量。选中某选项意味着变量的值等于该 Radiolabel属性的值label可以是String、Number或Boolean任意一种类型template el-radio v-modelradio label1备选项 A/el-radio el-radio v-modelradio label2备选项 B/el-radio /template script export default { data () { return { radio: 1 }; } } /script初始radio: 1与第一个选项的label1相等因此页面渲染时第一个单选框处于选中状态。源码视角model 的计算与分发在 packages/radio/src/radio.vue 中选中状态通过一个model计算属性完成读写第 93-105 行model: { get() { return this.isGroup ? this._radioGroup.value : this.value; }, set(val) { if (this.isGroup) { this.dispatch(ElRadioGroup, input, [val]); } else { this.$emit(input, val); } this.$refs.radio (this.$refs.radio.checked this.model this.label); } }模板中v-modelmodel绑定在原生input typeradio上用户点击时原生 input 的 change 事件会触发model的 setter独立使用时setter 直接$emit(input, val)把新值回写给外层v-model组内使用时则通过dispatch向上找到ElRadioGroup并触发其input事件见 src/mixins/emitter.js 的向上冒泡实现最终更新组级绑定值。isGroup的判定第 81-92 行是沿$parent链向上查找componentName ElRadioGroup的祖先组件因此即使el-radio嵌套在多层自定义容器中也能正确识别所属分组。三、禁用状态设置disabled属性即可禁用单选框它接受一个Booleantrue为禁用。已选中的选项在禁用后仍然保持选中态template el-radio disabled v-modelradio label禁用备选项/el-radio el-radio disabled v-modelradio label选中且禁用备选项/el-radio /template script export default { data () { return { radio: 选中且禁用 }; } } /script源码中disabled为 Boolean 类型 propradio.vue。其计算属性isDisabled第 115-119 行体现了三层禁用叠加逻辑isDisabled() { return this.isGroup ? this._radioGroup.disabled || this.disabled || (this.elForm || {}).disabled : this.disabled || (this.elForm || {}).disabled; }即单个选项的disabled、所属组的disabled、以及外层el-form的全局disabled任一为真该选项即进入禁用态。这也是为什么在el-form上设置disabled可以一次性禁用整个表单内所有单选框。对应地test/unit/specs/radio.spec.js 中的disabled用例验证了禁用后点击不会改变绑定值且 DOM 上会挂载is-disabled类。四、单选框组el-radio-group当存在多个互斥选项时推荐使用el-radio-group组合el-radio。在el-radio-group上绑定v-model在每个el-radio上设置label即可无需再给每个el-radio单独绑定变量template el-radio-group v-modelradio el-radio :label3备选项 A/el-radio el-radio :label6备选项 B/el-radio el-radio :label9备选项 C/el-radio /el-radio-group /template script export default { data () { return { radio: 3 }; } } /script注意此例中:label3使用了v-bind绑定数字字面量因此选中后radio的值为数字3若写label3则值为字符串3。这也是文档强调label可为String、Number或Boolean的实战意义所在。组级还提供change事件响应变化回调参数为当前选中的label值el-radio-group v-modelradio changehandleChange el-radio :label3备选项 A/el-radio el-radio :label6备选项 B/el-radio /el-radio-group源码视角组内通信与键盘导航在 packages/radio/src/radio-group.vue 中事件转发第 55-59 行created钩子里监听来自子选项的handleChange内部事件再对外$emit(change, value)保证组级change只携带最新选中的值与表单联动第 106-110 行watch: value在绑定值变化时向ElFormItem派发el.form.change这是el-radio-group能无缝接入el-form校验的关键键盘导航第 69-104 行handleKeydown监听组内按键按左/上方向键回退到上一个选项首项回绕到末项按右/下方向键前进到下一个选项末项回绕到首项并同步click()与focus()实现仅靠键盘即可在组内切换——这一行为在 radio.spec.js 的keyboard event用例中被验证模拟按 37 号左键后选中值从 6 变为 3。此外组容器通过_elTag计算属性第 45-49 行动态决定渲染的标签名默认渲染为div并带有roleradiogroup无障碍语义。五、按钮样式el-radio-button把el-radio换成el-radio-button即可得到按钮风格的单选组合。Element 还提供了size属性控制按钮尺寸可选值medium/small/minitemplate div el-radio-group v-modelradio1 el-radio-button labelNew York/el-radio-button el-radio-button labelWashington/el-radio-button el-radio-button labelLos Angeles/el-radio-button el-radio-button labelChicago/el-radio-button /el-radio-group /div div stylemargin-top: 20px el-radio-group v-modelradio2 sizemedium el-radio-button labelNew York/el-radio-button el-radio-button labelWashington/el-radio-button el-radio-button labelLos Angeles/el-radio-button el-radio-button labelChicago/el-radio-button /el-radio-group /div div stylemargin-top: 20px el-radio-group v-modelradio3 sizesmall el-radio-button labelNew York/el-radio-button el-radio-button labelWashington disabled/el-radio-button el-radio-button labelLos Angeles/el-radio-button el-radio-button labelChicago/el-radio-button /el-radio-group /div div stylemargin-top: 20px el-radio-group v-modelradio4 disabled sizemini el-radio-button labelNew York/el-radio-button el-radio-button labelWashington/el-radio-button el-radio-button labelLos Angeles/el-radio-button el-radio-button labelChicago/el-radio-button /el-radio-group /div /template script export default { data () { return { radio1: New York, radio2: New York, radio3: New York, radio4: New York }; } } /script示例展示了四种典型组合默认尺寸、sizemedium、sizesmall含单个disabled选项、以及整组disabledsizemini。源码视角按钮激活配色如何工作packages/radio/src/radio-button.vue 中激活态的配色来自activeStyle计算属性第 85-92 行activeStyle() { return { backgroundColor: this._radioGroup.fill || , borderColor: this._radioGroup.fill || , boxShadow: this._radioGroup.fill ? -1px 0 0 0 ${this._radioGroup.fill} : , color: this._radioGroup.textColor || }; }即激活按钮的背景色、边框色由组的fill属性决定文本颜色由组的text-color属性决定默认#409EFF填充、#ffffff文字且相邻按钮间的分隔阴影也用fill色绘制。而按钮尺寸由size()计算属性第 96-98 行解析优先级为组的size 外层el-form-item的尺寸 $ELEMENT.size全局配置。底层样式见 packages/theme-chalk/src/radio-button.scss首个按钮左边框与圆角特殊处理形成连续的按钮组视觉。六、带边框的 Radio设置border属性可以渲染为带边框的单选框。border形态下size属性才生效medium/small/mini控制整个选项框的尺寸template div el-radio v-modelradio1 label1 border备选项1/el-radio el-radio v-modelradio1 label2 border备选项2/el-radio /div div stylemargin-top: 20px el-radio v-modelradio2 label1 border sizemedium备选项1/el-radio el-radio v-modelradio2 label2 border sizemedium备选项2/el-radio /div div stylemargin-top: 20px el-radio-group v-modelradio3 sizesmall el-radio label1 border备选项1/el-radio el-radio label2 border disabled备选项2/el-radio /el-radio-group /div div stylemargin-top: 20px el-radio-group v-modelradio4 sizemini disabled el-radio label1 border备选项1/el-radio el-radio label2 border备选项2/el-radio /el-radio-group /div /template script export default { data () { return { radio1: 1, radio2: 1, radio3: 1, radio4: 1 }; } } /script组内同样可以通过组的size统一控制每个带边框 Radio 的尺寸。源码中el-radio的根元素类名会根据border radioSize拼接出el-radio--medium/el-radio--small/el-radio--miniradio.vue样式表 packages/theme-chalk/src/radio.scss 为这些修饰类分别定义了内边距、圆角、高度与圆形指示点大小选中时边框变为主题色$--color-primary禁用时显示not-allowed光标。对应测试 radio.spec.js 的border用例断言根元素存在is-bordered类。七、API 参考属性与事件以下三张属性表与两张事件表完整继承自 examples/docs/es/radio.md 并补充了源码级说明。Radio Attributes参数说明类型可选值默认值value / v-model绑定值string / number / boolean——labelRadio 的 value选中后绑定值变为该值string / number / boolean——disabled是否禁用boolean—falseborder是否显示边框boolean—falsesizeRadio 的尺寸仅在border为真时有效stringmedium / small / mini—name原生name属性string——说明size的计算同时兼容外层el-form-item的尺寸与$ELEMENT.size全局配置见 radio.vuename会透传给内部原生input typeradio用于表单提交等原生场景。Radio-button Attributes参数说明类型可选值默认值labelRadio 的 valuestring / number——disabled是否禁用boolean—falsename原生name属性string——Radio-group Attributes参数说明类型可选值默认值value / v-model绑定值string / number / boolean——size单选框组尺寸仅对按钮形式的 Radio 或带边框的 Radio 有效stringmedium / small / mini—disabled是否禁用整组boolean—falsetext-color按钮形式的 Radio 激活时的文本颜色string—#fffffffill按钮形式的 Radio 激活时的填充色和边框色string—#409EFFRadio Events 与 Radio-group Events事件名称说明回调参数change绑定值变化用户交互触发时触发选中的 Radio label 值input绑定值变化时触发v-model 内部机制选中的 Radio label 值需要注意区分两个事件input是v-model的底层事件只要绑定值变化就会触发——包括代码中直接修改绑定变量的情况change则只在用户交互点击或键盘操作时触发程序化地给v-model赋值不会触发change。这一行为在 radio.spec.js 的两个用例中得到验证change event only triggers on user input实践中有需要监听用户真实操作的场景如埋点、即时保存应使用change。八、无障碍与细节行为从源码与测试中可以确认几个容易被忽略的细节空格键选中el-radio与el-radio-button的根label上都绑定了keydown.space禁用时不响应radio.vueTab 焦点管理tabIndex计算属性让当前选中项可获得 Tab 焦点、其余项不可且当组内没有任何默认选中项时mounted后第一个选项会被赋予tabIndex 0radio-group.vueARIA 语义根元素带roleradio、aria-checked、aria-disabled组容器带roleradiogroup原生 input 使用aria-hiddentrue隐藏以避免屏幕阅读器重复朗读原生 input 隐藏el-radio__original/el-radio-button__orig-radio均被opacity: 0与z-index: -1隐藏视觉层完全由样式化的el-radio__inner圆形指示点承担见 radio.scss。九、实战建议小结选项不超过 5~7 个时优先使用 Radio 组更多选项改用 Select注意label的类型一致性label1字符串与:label1数字会得到不同类型的绑定值初始化数据时务必与之一致整组禁用优先在el-radio-group上设置disabled免去逐个配置需要监听用户主动选择时使用change需要响应一切值变化时使用input/v-model接入表单校验无需额外处理el-radio-group已在值变化时自动向el-form-item派发el.form.change配合 Form 表单 的校验规则即可实现选中即校验。相关源码与测试路径组件实现见 packages/radio/src/radio.vue、packages/radio/src/radio-group.vue、packages/radio/src/radio-button.vue样式见 packages/theme-chalk/src/radio.scss 与 packages/theme-chalk/src/radio-button.scss行为验证见 test/unit/specs/radio.spec.js。【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考