外观
Switch 开关选择器
约 1226 字大约 4 分钟
2025-10-31
基础使用
通过v-model绑定一个变量,控制开关的选中状态,true表示开,false表示关。
<template>
<un-switch v-model="value" @change="change"></un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
const change = (value: boolean) => {
console.log('change', value)
}
</script>加载中
设置loading属性,默认为true,可以让switch处于加载中的状态,这时switch是不可操作的,您可以通过:loading='loading'以动态设置加载状态
<template>
<un-switch v-model="value3" loading></un-switch>
<un-switch v-model="value4" loading></un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value3 = ref(false)
const value4 = ref(true)
</script>禁用switch
设置disabled属性,默认为true,即可禁用某个组件,让用户无法点击,禁用分为两种状态:
- 一是关闭情况下的禁用,这时只显示一个白色的区域。
- 二是打开后再禁用,这时会在原有的颜色上加一个
opacity透明度,但此时依然是不可操作的。
<template>
<un-switch v-model="value" disabled></un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
</script>自定义尺寸
设置size属性,可以让您自定义switch的尺寸,单位为px
<template>
<un-switch v-model="value3" size="28"></un-switch>
<un-switch v-model="value4" size="20"></un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value3 = ref(false)
const value4 = ref(true)
</script>自定义形状
设置shape属性,可以自定义开关的形状,可选值为round(默认)和square。
<template>
<un-switch v-model="value" shape="square"></un-switch>
<un-switch v-model="value" size="12" shape="square"></un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
</script>文字描述
设置activeText和inactiveText属性,可以在开关两侧显示文字描述。
<template>
<un-switch v-model="value" activeText="开启" inactiveText="关闭"></un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
</script>自定义图标
通过icon插槽可以自定义开关的图标内容。
<template>
<un-switch v-model="value">
<template #icon="{ checked }">
<un-icon name="checkmark" v-if="checked"></un-icon>
<un-icon name="close" v-else></un-icon>
</template>
</un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
</script>自定义文字
通过text插槽可以自定义开关的文字内容。
<template>
<un-switch v-model="value">
<template #text="{ checked }">
<text style="font-size:12px" v-if="checked">开</text>
<text style="font-size:12px;color:#333" v-else>关</text>
</template>
</un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
</script>自定义颜色
同时设置activeColor和inactiveColor属性,可以让您自定义switch的样式,同样支持多种设置方式
<template>
<un-switch
space="2" v-model="value11" activeColor="#f9ae3d"
inactiveColor="rgb(230, 230, 230)">
</un-switch>
<un-switch
space="2" v-model="value12" activeColor="#f9ae3d"
inactiveColor="rgb(230, 230, 230)">
</un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value11 = ref(false)
const value12 = ref(true)
</script>异步控制
异步控制场景,一般发生在用户打开或者关闭选择器时,需要本地或者向后端请求判断,是否允许用户打开或者关闭的场景。
同时您也可以组合使用,例如根据接口结果添加disabled,loading属性等
注意
请添加asyncChange属性来支持异步控制操作,否则您将先操作v-model绑定的值,并失去控制效果
<template>
<un-switch v-model="value13" asyncChange @change="asyncChange"></un-switch>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value13 = ref(true)
const asyncChange = (value: boolean) => {
uni.showModal({
content: value ? '确定要打开吗' : '确定要关闭吗',
success: (res) => {
if (res.confirm) {
value13.value = value
}
}
})
}
</script>API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| loading | 是否处于加载中 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| shape | 开关形状 | Enum | round |
| size | 开关尺寸,单位rpx | string | number | 25 |
| width | 设置固定宽度,文字描述超出自动省略 | string | number | 0 |
| activeColor | 打开时的背景色 | string | #2979ff |
| inactiveColor | 关闭时的背景色 | string | #ffffff |
| value | 通过v-model双向绑定的值 | boolean | string | number | false |
| activeValue | switch打开时的值 | boolean | string | number | true |
| inactiveValue | switch关闭时的值 | boolean | string | number | false |
| asyncChange | 是否开启异步变更,开启后需要手动控制输入值 | boolean | false |
| space | 圆点与外边框的距离 | string | number | 0 |
| textSpace | 文字描述与开关的间距 | string | number | 8 |
| activeText | 开启时的文字描述 | string | '' |
| inactiveText | 关闭时的文字描述 | string | '' |
Event
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 在switch打开或关闭时触发 | Function |
Scss 变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-switch-bg-color | $bg-color | 开关背景颜色 |
| $un-switch-checked-bg-color | $color-primary | 开关选中时背景颜色 |
| $un-switch-disabled-opacity | 0.5 | 开关禁用时透明度 |
| $un-switch-dot-bg-color | #ffffff | 开关圆点背景颜色 |
| $un-switch-dot-box-shadow | 0 2px 4px rgba(0, 0, 0, 0.1) | 开关圆点阴影 |
| $un-switch-text-color | #ffffff | 描述文字文字颜色 |
| $un-switch-text-font-size | 12px | 描述文字字体大小 |
提示
组件内部默认使用 scss 变量,如需修改,请查看 scss 变量使用 文档
