开关

开关用于在两个相反状态之间切换。

开关默认保留较大的触控面积,建议搭配简短文案或图标使用。

基本用法

v-model 绑定到 Boolean 类型变量。需要定制状态色时,优先使用 Element Plus 的颜色变量,例如 --el-color-success--el-color-danger

系统通知使用默认主题色切换状态

默认尺寸已经保留足够的触控面积,不需要额外包裹额外样式。

营销提醒通过 Element Plus 颜色变量定制状态色

需要定制状态色时,优先使用 `--el-color-*` 变量以兼容深色模式。

尺寸

三档尺寸都会保留足够的触控面积;default 仍然是最推荐的表单默认值。

large适合关键设置项或老年模式
开启
default推荐作为表单的默认尺寸
开启
small在紧凑信息区中使用,但仍保留足够的触控面积
开启

文字描述

您可以通过 active-textinactive-text 显示状态说明。开启 inline-prompt 后,开关内部只适合放非常短的提示词。

推荐把较长说明放在开关两侧,把开关内部保留给单字或短词提示。

外侧文字将状态含义放在开关两侧,更适合较长文案
按月订阅

当需要完整描述状态时,优先把文字放在开关外侧,避免挤压主体。

行内提示开关内部仅保留简短提示词

`inline-prompt` 适合一到两个字的简短状态,不建议塞入完整句子。

自定义宽度需要更宽触控目标时可自定义宽度

自定义宽度适合无障碍或高频操作场景,但文案仍应保持简短。

显示自定义图标

TIP

使用 active-iconinactive-icon 属性添加图标。您可以传递组件名称字符串(提前注册)或组件本身(SVG Vue 组件)。 Element Plus提供了一组图标,您可以在图标中找到

图标通常比长文本更容易识别,尤其适合可见性、权限和状态型场景。

外侧图标在开关两侧展示更完整的状态图标
行内图标在开关内部放入图标,适合更紧凑的列表

扩展值类型

您可以设置 active-valueinactive-value,让开关直接映射到业务字段,而不必局限于布尔值。

字符串值切换时直接输出业务值

当前绑定值:100

禁用

添加 disabled 属性会禁用开关,常用于只读信息或权限受限的设置项。

只读设置已开启但暂不可修改
可编辑设置仍可在当前步骤中修改

加载中

loading 属性设置为 true 可以避免用户连续点击导致重复提交。

开启中等待远端保存结果
关闭中禁用重复操作直到请求完成

防止切换

设置 before-change 后,可以在真正改变状态前执行校验或异步确认。

校验通过满足条件后再真正切换
校验失败返回 false 或拒绝 Promise 会阻止切换

自定义操作图标 2.3.9

您可以添加 active-action-iconinactive-action-icon 属性来显示图标。

动作图标根据状态切换操作图标

圆点内的图标会跟随状态同步变化,适合用来表达可见性或权限。

自定义操作槽 2.4.4

您可以使用 active-actioninactive-action 插槽来自定义操作。

插槽内容在圆点里放入自定义字符

插槽内容建议保持为一个字或一个图标,避免圆点内挤压变形。

API

属性

名称说明类型默认值
model-value / v-model绑定值,默认与 active-value / inactive-value 对应boolean / string / numberfalse
disabled是否禁用开关booleanfalse
loading是否处于加载状态booleanfalse
size开关尺寸'' | 'large' | 'default' | 'small'''
width自定义开关宽度string / number''
inline-prompt是否在开关内部显示提示词或图标booleanfalse
active-iconon 状态时显示的图标,优先级高于 active-textstring / Component
inactive-iconoff 状态时显示的图标,优先级高于 inactive-textstring / Component
active-action-icon 2.3.9on 状态时圆点内部显示的图标string / Component
inactive-action-icon 2.3.9off 状态时圆点内部显示的图标string / Component
active-texton 状态时的说明文字string''
inactive-textoff 状态时的说明文字string''
active-valueon 状态对应的值boolean / string / numbertrue
inactive-valueoff 状态对应的值boolean / string / numberfalse
name原生 inputnamestring''
validate-event是否触发表单校验booleantrue
before-change切换前钩子,返回 false 或 rejected Promise 会阻止切换() => boolean | Promise<boolean>
id原生 inputidstring
tabindex原生 inputtabindexstring / number
aria-label a11y 2.7.2原生 inputaria-labelstring
active-color deprecatedon 状态背景色,建议改用 --el-switch-on-colorstring''
inactive-color deprecatedoff 状态背景色,建议改用 --el-switch-off-colorstring''
border-color deprecated开关边框色,建议改用 --el-switch-border-colorstring''
label a11y deprecated与原生 inputaria-label 等价string

事件

名称说明类型
update:modelValue当绑定值更新时触发(value: boolean | string | number) => void
change当用户完成一次状态切换时触发(value: boolean | string | number) => void
inputchange 同步触发,用于兼容旧用法(value: boolean | string | number) => void

切换插槽

名称说明
active-action 2.4.4自定义 on 状态下圆点内部内容
inactive-action 2.4.4自定义 off 状态下圆点内部内容
active 2.13.0自定义 on 状态文本或图标区域
inactive 2.13.0自定义 off 状态文本或图标区域

暴露

名称说明类型
focus手动聚焦开关() => void
checked当前是否处于选中状态Ref<boolean>