Switch 开关

开关用于在两种相互对立的状态之间切换，通常用于即时生效的启用、关闭、显示、隐藏等设置项。

基础用法

使用 v-model 绑定开关值。默认情况下，打开时为 true，关闭时为 false。

<template>
  <el-switch v-model="value" />
  <el-switch
    v-model="colorValue"
    style="--el-switch-on-color: #13ce66; --el-switch-off-color: #ff4949"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(true)
const colorValue = ref(false)
</script>

禁用状态

设置 disabled 后，开关不可切换。禁用状态会保留当前值，仅阻止用户操作。

<template>
  <el-switch v-model="open" disabled />
  <el-switch v-model="closed" disabled />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const open = ref(true)
const closed = ref(false)
</script>

文字描述

使用 active-text 和 inactive-text 可以在开关两侧展示当前状态说明。

停用

启用

按年付费

按月付费

<template>
  <el-switch
    v-model="value"
    active-text="启用"
    inactive-text="停用"
  />
</template>

行内提示

设置 inline-prompt 后，文本或图标会显示在开关内部。文字提示只展示第一个字符，适合短状态。

开

<template>
  <el-switch
    v-model="value"
    inline-prompt
    active-text="开"
    inactive-text="关"
    width="56"
  />

  <el-switch
    v-model="iconValue"
    inline-prompt
    :active-icon="Check"
    :inactive-icon="Close"
    width="56"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Check, Close } from '@element-plus/icons-vue'

const value = ref(true)
const iconValue = ref(false)
</script>

显示图标

使用 active-icon 与 inactive-icon 可以在开关外侧展示状态图标。图标会优先于对应的文字内容。

<template>
  <el-switch
    v-model="value"
    :active-icon="Check"
    :inactive-icon="Close"
    active-text="启用"
    inactive-text="停用"
  />
</template>

自定义动作区

active-action-icon 和 inactive-action-icon 可以替换圆形滑块内的图标，也可以使用 active-action、inactive-action 插槽完全自定义动作区内容。

关

<template>
  <el-switch
    v-model="value"
    :active-action-icon="Check"
    :inactive-action-icon="Close"
  />

  <el-switch v-model="slotValue" width="56">
    <template #active-action>
      <span>开</span>
    </template>
    <template #inactive-action>
      <span>关</span>
    </template>
  </el-switch>
</template>

扩展值

通过 active-value 和 inactive-value 可以把开关值从布尔值扩展为字符串或数字。v-model 的值必须与其中一个值匹配。

停用

启用

enabled

<template>
  <el-switch
    v-model="value"
    active-value="enabled"
    inactive-value="disabled"
    active-text="启用"
    inactive-text="停用"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('enabled')
</script>

加载状态

设置 loading 后，开关会显示加载状态并临时禁用交互，适合等待远程保存结果的场景。

保存中

保存中

<template>
  <el-switch v-model="value" loading />
  <el-switch
    v-model="textValue"
    loading
    active-text="保存中"
    inactive-text="保存中"
  />
</template>

阻止切换

before-change 会在状态切换前执行。返回 false 或返回一个最终 rejected / false 的 Promise 时，会阻止本次切换。

可控开关

可控开关

<template>
  <el-switch
    v-model="value"
    :before-change="beforeChange"
    active-text="可控开关"
    inactive-text="可控开关"
  />

  <el-button size="small" @click="allowChange = !allowChange">
    {{ allowChange ? '当前允许切换' : '当前阻止切换' }}
  </el-button>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(false)
const allowChange = ref(true)

const beforeChange = () => allowChange.value
</script>

不同尺寸

size 支持 large、default、small 三种尺寸，用于适配不同密度的表单或设置面板。

Large

Default

Small

<template>
  <el-switch v-model="large" size="large" />
  <el-switch v-model="defaultValue" />
  <el-switch v-model="small" size="small" />
</template>

API

Switch 属性

属性名	说明	类型	默认值
model-value / v-model	绑定值，需等于 active-value 或 inactive-value	boolean | string | number	false
disabled	是否禁用	boolean	false
loading	是否显示加载状态	boolean	false
size	开关尺寸	large | default | small	default
width	开关宽度	string | number	''
inline-prompt	图标或文字是否显示在点内，文字只渲染第一个字符	boolean	false
active-icon	打开时显示的图标组件，会覆盖 active-text	string | component	-
inactive-icon	关闭时显示的图标组件，会覆盖 inactive-text	string | component	-
active-action-icon	打开时动作区显示的图标组件	string | component	-
inactive-action-icon	关闭时动作区显示的图标组件	string | component	-
active-text	打开时显示的文字	string	''
inactive-text	关闭时显示的文字	string	''
active-value	打开时的值	boolean | string | number	true
inactive-value	关闭时的值	boolean | string | number	false
name	原生 input 的 name 属性	string	''
validate-event	是否触发表单校验	boolean	true
before-change	开关状态切换前的钩子，返回 false 或 rejected Promise 时阻止切换	Function	-
id	原生 input 的 id 属性	string	-
tabindex	原生 input 的 tabindex 属性	string | number	-
aria-label	原生 input 的 aria-label 属性	string	-

Switch 事件

事件名	说明	类型
change	绑定值变化时触发	Function
update:modelValue	绑定值更新时触发	Function
input	输入值变化时触发	Function

Switch 插槽

插槽名	说明
active	自定义打开状态的显示内容
inactive	自定义关闭状态的显示内容
active-action	自定义打开状态的动作区内容
inactive-action	自定义关闭状态的动作区内容

Switch 暴露

名称	说明	类型
focus	使开关获得焦点	Function
checked	当前是否处于打开状态	boolean