Switch 开关

17:06

说明

用于二选一的开关切换，点击在 active-value / inactive-value 之间切换并通过 v-model 同步。轨道为 50:28 胶囊、无描边，白色滑块四周内缩且恒垂直居中；size 只描述轨道高度，轨道宽、内缩与滑块直径按比例推导。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持（vibrate-short 轻微震动仅此端生效）

示例

基础用法

使用 v-model 绑定开关状态，默认 true/false。

查看源码

<template>
    <ux-switch v-model="value" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

自定义值

通过 active-value 和 inactive-value 自定义开关的值。

查看源码

<template>
    <ux-switch v-model="value" :active-value="100" :inactive-value="1" />
    <text>当前值: {{ value }}</text>
</template>

<script setup lang="uts">
const value = ref<number>(1);
</script>

颜色配置 active-color

通过 active-color 设置打开时的背景色。

查看源码

<template>
    <ux-switch v-model="value" active-color="#19be6b" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

尺寸配置 size

支持 small(22px)、default(28px)、large(34px) 预设和自定义数值（指轨道高度）。

查看源码

<template>
    <ux-switch v-model="value" size="large" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

加载中 loading

loading=true 时显示加载动画，开关不可操作。

查看源码

<template>
    <ux-switch v-model="value" :loading="true" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

禁用 disabled

disabled=true 时开关不可操作，半透明显示。

查看源码

<template>
    <ux-switch v-model="value" :disabled="true" />
</template>

<script setup lang="uts">
const value = ref<boolean>(true);
</script>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
loading	是否显示加载中状态	boolean	false	-
disabled	是否禁用	boolean	false	-
size	开关尺寸（轨道高），small-22px，default-28px，large-34px，或自定义数值（单位px）	string | number	''	-
activeColor	打开时的颜色	string	''	-
inactiveColor	关闭时的颜色	string	''	-
modelValue	v-model 绑定值，开关状态值	boolean | number | string	false	-
vibrateShort	是否开启轻微震动反馈	boolean	false	-
activeValue	打开时的值	boolean | number | string	true	-
inactiveValue	关闭时的值	boolean | number | string	false	-
validateState	是否处于校验错误状态	boolean	false	-

Events

事件名	说明	回调参数	版本
change	在switch打开或关闭时触发	value: boolean | number | string	-

Slots

ux-switch 无插槽。

注意事项

• vibrate-short 的轻微震动仅微信小程序生效，App（HBuilderX 2.6.8）与 H5 无效。
• 开关状态由 model-value === active-value 判定；active-value / inactive-value 支持布尔、数字、字符串，需与绑定值类型一致。
• loading 或 disabled 时点击被拦截，不触发 change；change 在 nextTick 中发出（等待父组件状态同步）。
• 非预设的 size 作为自定义轨道高度（px）：轨道宽按 50:28、内缩按 3:28 等比推导，滑块直径 = 轨道高 − 2×内缩。
• disabled 时整体 opacity: 0.6；validate-state 或表单校验失败时在轨道上补 1px 红色描边。
• 组件可注入 ux-form-item 上下文，切换后触发其校验。