Element UI el-switch 开关组件详解：用法、参数与实现原理

Element UI el-switch 开关组件详解：用法、参数与实现原理

【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element

el-switch是 Element UI（A Vue.js 2.0 UI Toolkit）中用于在两个相互对立的状态间切换的组件，多用于触发"开/关"语义的功能，例如功能开关、付费方式选择、状态启停等。本篇基于官方英文文档 switch.md 的全部内容展开，并结合 组件源码、样式实现 与 单元测试，完整讲解 Switch 的四种典型用法、全部 Attributes/Events/Methods 参数，以及其底层状态管理、表单联动与无障碍（a11y）设计，帮助读者既能直接使用组件，也能理解其内部机制以便二次定制。

一、组件定位：在两个对立状态间切换

官方文档对 Switch 的定义只有一句话："Switch is used for switching between two opposing states."（开关用于在两种相互对立的状态间切换）。它的核心交互模型是：

• 绑定值通过v-model双向同步，接受Boolean/String/Number三种类型；
• 点击组件（或按回车键）触发状态翻转，组件内部发出input与change两个事件；
• on/off两种状态可通过背景色、文字描述、图标类名进行差异化呈现。

组件入口在 packages/switch/index.js，它引入src/component并挂载install方法，使组件可以通过Vue.use(Switch)全局注册为el-switch，也可按需引入。

二、四种典型用法

1. 基本用法：v-model 与自定义背景色

将v-model绑定到一个Boolean类型变量即可；active-color与inactive-color属性决定开关在两种状态下的背景色。这是英文文档给出的官方示例：

<el-switch v-model="value1"> </el-switch> <el-switch v-model="value2" active-color="#13ce66" inactive-color="#ff4949"> </el-switch> <script> export default { data() { return { value1: true, value2: true } } }; </script>

从源码看，颜色并不是通过 CSS 类切换实现的，而是在mounted钩子中对.el-switch__core节点直接写入内联样式（见 component.vue）：

mounted() { this.coreWidth = this.width || 40; if (this.activeColor || this.inactiveColor) { this.setBackgroundColor(); } this.$refs.input.checked = this.checked; }

其中setBackgroundColor方法会同时设置 core 节点的borderColor与backgroundColor（component.vue），且每次checked变化时都会被watch重新调用。这意味着不传颜色属性时，背景色回退到主题 SCSS 中的默认值——#409EFF（on 状态，即$--switch-on-color）与#C0CCDA（off 状态，即$--switch-off-color），这正是文档参数表中标注的"默认值"的实际来源。

2. 文字描述：active-text / inactive-text

使用active-text与inactive-text属性可以分别为on/off状态添加文字描述，常用于把开关语义说清楚（例如"按月付费 / 按年付费"）：

<el-switch v-model="value1" active-text="Pay by month" inactive-text="Pay by year"> </el-switch> <el-switch style="display: block" v-model="value2" active-color="#13ce66" inactive-color="#ff4949" active-text="Pay by month" inactive-text="Pay by year"> </el-switch> <script> export default { data() { return { value1: true, value2: true } } }; </script>

模板实现上有两个值得注意的细节（component.vue）：

1. 左右两个el-switch__label分别通过v-if="inactiveIconClass || inactiveText"与v-if="activeIconClass || activeText"控制渲染——没配置文字或图标时对应标签节点根本不存在，不会产生多余占位；
2. 当前状态一侧的文字会加上is-active类并在样式中变为主题色（$--color-primary），同时通过:aria-hidden把已显示一侧的文字从无障碍树中隐藏，避免屏幕阅读器重复朗读。

3. 扩展的 value 类型：active-value / inactive-value

active-value与inactive-value可以让开关绑定值摆脱true/false，改为任意Boolean、String或Number。官方示例将值扩展为字符串'100'与'0'，并用el-tooltip展示当前值：

<el-tooltip :content="'Switch value: ' + value" placement="top"> <el-switch v-model="value" active-color="#13ce66" inactive-color="#ff4949" active-value="100" inactive-value="0"> </el-switch> </el-tooltip> <script> export default { data() { return { value: '100' } } }; </script>

判断"是否处于 on 状态"的判据是严格相等：

computed: { checked() { return this.value === this.activeValue; } }

因此active-value="100"（字符串）与绑定值100（数字）会被判定为不匹配。源码在created钩子中还做了一层自纠正（component.vue）：如果初始value既不是activeValue也不是inactiveValue，会立即$emit('input', this.inactiveValue)，把绑定值拉回到inactiveValue，防止组件进入"两个值都不是"的中间态。这一点在对接后端返回的任意枚举值（如'1'/'0'、1/0）时尤其重要，务必保证类型与字面量一致。

4. 禁用状态：disabled

添加disabled属性即可禁用开关：

<el-switch v-model="value1" disabled> </el-switch> <el-switch v-model="value2" disabled> </el-switch> <script> export default { data() { return { value1: true, value2: false } } }; </script>

源码中禁用逻辑收敛在一个计算属性switchDisabled中（component.vue）：

switchDisabled() { return this.disabled || (this.elForm || {}).disabled; }

即只要父级el-form自身设置了disabled，内部所有开关会自动随之禁用——这是通过组件顶部的inject: { elForm: { default: '' } }注入父级表单实例实现的。点击处理入口switchValue也以此作为第一道闸门：

switchValue() { !this.switchDisabled && this.handleChange(); }

单元测试disabled switch should not respond to user click（switch.spec.js）验证了禁用状态下点击 core 区域不会改变绑定值。

三、完整 API 参考

以下参数表完整继承自官方文档（英文文档见 switch.md，中文对照版见 switch.md），默认值与 component.vue 的 props 定义一一对应。

Attributes

补充说明：

• width控制的是滑块轨道（.el-switch__core）宽度，单位为像素，默认 40，与mounted中this.coreWidth = this.width || 40的兜底一致；滑块圆点大小（16px）、轨道高度（20px）等由主题变量决定，见下文样式部分。
• active-icon-class/inactive-icon-class与文字属性互斥：源码模板中先渲染<i :class="[activeIconClass]">，文字<span>只在!activeIconClass时才出现，所以设置图标类名会覆盖文字。
• name透传到内部隐藏的<input type="checkbox">上，配合id（源码额外提供但未列入文档表）可用于表单提交与标签关联。
• validate-event为true时，开关状态变化会向上派发el.form.change事件以触发表单校验，见下文表单联动一节。

Events

Methods

focus方法并非组件自实现，而是来自通用混入 focus.js：ElSwitch通过mixins: [Focus('input'), ...]注入，调用时会把焦点转移到内部ref="input"的原生 checkbox 上，从而兼容键盘操作与无障碍聚焦。

四、源码级原理剖析

1. 模板结构与无障碍设计

根节点是一个带role="switch"的<div>，并同步维护aria-checked与aria-disabled（component.vue）：

<div class="el-switch" :class="{ 'is-disabled': switchDisabled, 'is-checked': checked }" role="switch" :aria-checked="checked" :aria-disabled="switchDisabled" @click.prevent="switchValue" > <input class="el-switch__input" type="checkbox" @change="handleChange" ref="input" :id="id" :name="name" :true-value="activeValue" :false-value="inactiveValue" :disabled="switchDisabled" @keydown.enter="switchValue" >

关键设计点：

• 真实<input type="checkbox">被样式置为position: absolute; width: 0; height: 0; opacity: 0（switch.scss），保留其表单语义与焦点能力，视觉呈现全部交给.el-switch__core轨道；
• 交互有两条入口：div 上的@click.prevent="switchValue"（鼠标点击轨道）与 input 上的@keydown.enter="switchValue"（键盘回车），两条入口最终都汇聚到同一个handleChange；
• :true-value/:false-value与activeValue/inactiveValue保持同步，使原生 checkbox 的布尔状态与业务值一一对应。

2. 值的变化流程与"单一数据源"

状态翻转的完整链路在handleChange中（component.vue）：

handleChange(event) { const val = this.checked ? this.inactiveValue : this.activeValue; this.$emit('input', val); this.$emit('change', val); this.$nextTick(() => { // set input's checked property // in case parent refuses to change component's value if (this.$refs.input) { this.$refs.input.checked = this.checked; } }); }

可以推断出三层设计意图：

1. 组件不直接修改value，而是发出input事件，由父组件决定是否更新——value是唯一数据源（single source of truth）；
2. $emit('change', val)的回调参数即"变化后的新值"，与文档 Events 表的描述一致，可被 switch.spec.js 中的change event用例验证；
3. $nextTick里回写input.checked是为了处理父组件拒绝更新绑定值的场景：即使v-model未同步变化，内部 checkbox 状态也会被拉回与checked一致。测试用例value is the single source of truth（switch.spec.js）专门验证了这一点——只传只读:value="true"时，点击轨道后组件内部checked、is-checked类与 input 的checked属性始终保持一致，不会视觉错位。

watch中对checked的监听（component.vue）则负责外部改值时的视图同步：绑定值变化后，checkbox 状态、背景色与表单校验事件都会随之刷新。sets checkbox value测试用例（switch.spec.js）验证了vm.value从false改到true时原生 input 的checked能正确联动。

3. 表单联动：validate-event 与 el-form

组件通过inject拿到父级表单（elForm），并在checked的 watcher 中条件性派发事件：

if (this.validateEvent) { this.dispatch('ElFormItem', 'el.form.change', [this.value]); }

dispatch来自 emitter.js，会沿$parent链向上查找componentName === 'ElFormItem'的祖先并$emit('el.form.change', [value])。因此当el-switch置于el-form/el-form-item结构内时，状态变化会自动触发所在表单项的change校验；若不想让开关参与表单校验（例如仅作为展示型开关），可将validate-event设为false关闭该行为。

4. 从 1.x 迁移：属性重命名提示

Element UI 2.x 对 1.x 的属性命名做了统一（on-*→active-*、off-*→inactive-*）。组件通过Migrating混入在控制台中给出告警提示，映射关系定义在getMigratingConfig中（component.vue）：

从 1.x 代码升级时，可按此表逐项替换。

五、样式层：SCSS 变量与主题定制

Switch 的全部视觉尺寸与配色集中在 theme-chalk/src/common/var.scss：

$--switch-on-color: $--color-primary !default; // on 状态背景色，即 #409EFF $--switch-off-color: $--border-color-base !default; // off 状态背景色，即 #C0CCDA $--switch-font-size: $--font-size-base !default; // 标签文字字号 $--switch-core-border-radius: 10px !default; // 轨道圆角 $--switch-width: 40px !default; // 轨道宽度（与 width 默认值一致） $--switch-height: 20px !default; // 轨道高度 $--switch-button-size: 16px !default; // 白色滑块圆点尺寸

switch.scss 中与之对应的渲染逻辑：

• 轨道.el-switch__core默认使用$--switch-off-color作为边框色与背景色，transition: border-color .3s, background-color .3s提供状态切换动画；
• is-checked状态下轨道切换为$--switch-on-color，白色圆点（::after伪元素）通过left: 100%; margin-left: -($--switch-button-size + 1px)滑到右侧；
• is-disabled状态下整体opacity: 0.6，且 core 与 label 的cursor变为not-allowed。

因此定制主题时，修改上述$--switch-*变量即可统一调整全局开关样式；而单实例的颜色定制则走active-color/inactive-color内联样式（优先级更高）。组件的演示页边距样式见 demo-styles/switch.scss。

六、TypeScript 类型支持

项目内置的类型声明文件 types/switch.d.ts 为ElSwitch提供了完整 prop 类型，其中activeValue/inactiveValue声明为string | boolean | number，与运行时 props 的[Boolean, String, Number]类型约束一致，可直接用于 Vue 2 + TypeScript 项目的模板与属性推断。

七、单元测试覆盖的行为契约

test/unit/specs/switch.spec.js 完整覆盖了组件对外承诺的行为，可作为集成使用时的验收清单：

八、使用建议小结

1. 默认场景：v-model绑定Boolean变量即可，颜色走主题默认值，无需额外属性；
2. 需要业务语义值：优先使用active-value/inactive-value（如'100'/'0'、1/0），并注意checked的判定是严格相等，类型必须与绑定值完全一致；组件在created阶段会自动把非法初始值纠正为inactiveValue；
3. 需要说明语义：短文案用active-text/inactive-text，纯图形界面用*-icon-class且两者互斥；
4. 放在表单中：父级el-form disabled会级联禁用内部开关；若开关不需要触发校验，设置validate-event="false"；
5. 需要键盘聚焦：通过模板引用调用组件的focus()方法，焦点会落在内部隐藏的 checkbox 上。

以上用法与原理均以当前仓库（Element UI，Vue 2 版本）的实际源码为准，涉及版本迁移时请以本仓库对应的 CHANGELOG 与文档为准。

【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element