Switch 开关

在两个互斥状态之间即时切换，常用于「开 / 关」型设置项。底层是原生 checkbox，因此保留了表单提交、键盘操作与屏幕阅读器语义；默认带居中涟漪反馈。

代码演示

基础用法

v-model 绑定布尔值，默认插槽渲染轨道右侧的标签文本。

启用通知接收周报通知状态：关闭

不传默认插槽时不渲染标签容器，只有一枚开关。

switch/basic.vue

源码

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

const notify = ref(false)
const weekly = ref(true)
</script>

<template>
  <div class="m-row-demo--col">
    <MSwitch v-model="notify">启用通知</MSwitch>
    <MSwitch v-model="weekly">接收周报</MSwitch>
    <span>通知状态：{{ notify ? '开启' : '关闭' }}</span>
  </div>
</template>

尺寸

small / default / large 三档，轨道与拇指同步缩放。

小默认大

switch/sizes.vue

源码

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

const small = ref(true)
const normal = ref(true)
const large = ref(true)
</script>

<template>
  <div class="m-row-demo">
    <MSwitch v-model="small" size="small">小</MSwitch>
    <MSwitch v-model="normal" size="default">默认</MSwitch>
    <MSwitch v-model="large" size="large">大</MSwitch>
  </div>
</template>

语义色

六种语义色对应选中态的轨道颜色，与全局 --m-* 令牌联动。

primarysecondarysuccesswarningerrorinfo

switch/colors.vue

源码

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

const colors = ['primary', 'secondary', 'success', 'warning', 'error', 'info'] as const

const on = reactive({
  primary: true,
  secondary: true,
  success: true,
  warning: true,
  error: true,
  info: true,
})
</script>

<template>
  <div class="m-row-demo">
    <MSwitch v-for="color in colors" :key="color" v-model="on[color]" :color="color">
      {{ color }}
    </MSwitch>
  </div>
</template>

禁用与加载

disabled 与 loading 都不可交互；loading 会在拇指内显示旋转指示器，适合状态尚未落库的过渡。

禁用 · 开禁用 · 关加载 · 开加载 · 关

switch/states.vue

源码

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

const disabledOn = ref(true)
const disabledOff = ref(false)
const loadingOn = ref(true)
const loadingOff = ref(false)
</script>

<template>
  <div class="m-row-demo">
    <MSwitch v-model="disabledOn" disabled>禁用 · 开</MSwitch>
    <MSwitch v-model="disabledOff" disabled>禁用 · 关</MSwitch>
    <MSwitch v-model="loadingOn" loading>加载 · 开</MSwitch>
    <MSwitch v-model="loadingOff" loading>加载 · 关</MSwitch>
  </div>
</template>

API

Props

属性	类型	默认值	说明
modelValue	boolean	undefined（内部按 !! 处理）	开关状态（v-model）
color	'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'	'primary'	选中态轨道颜色
size	'small' | 'default' | 'large'	'default'	尺寸
disabled	boolean	false	是否禁用
loading	boolean	false	加载态：不可交互，拇指内显示旋转指示器
name	string	undefined	原生 input name（表单提交）

Events

事件	参数	说明
update:modelValue	value: boolean	开关状态变化
change	value: boolean	开关状态变化

Slots

插槽	参数	说明
default	无	开关右侧标签文本（存在时才渲染 label 容器）

使用建议

提交表单时补上 name

组件底层是原生 checkbox，传入 name 后即可随 <form> 一起提交。未选中时原生 checkbox 不会带上该字段，取值时需要按「缺省即 false」处理。

即时生效 vs 确认后生效

开关默认「拨动即生效」。若切换背后是异步请求，建议在请求期间把 loading 置为 true，避免用户重复拨动造成状态错乱。

loading 会连带禁用原生 input

loading 为真时内部 input 处于 disabled（即 disabled || loading），点击不会切换状态，同时涟漪反馈也被关闭。

modelValue 会被强制布尔化

传入 0、''、undefined 都会被当作 false。不要用开关去承载三态（如 null）语义。

相关组件

• Checkbox 复选框：需要勾选样式、或需要一次选中多项时使用。
• Radio 单选框：多于两个互斥状态时应改用单选组。