Switch 开关
在“开”和“关”两个状态之间切换,点击后立即生效的设置项用它。
引入
import { NsSwitch } from '@ns/ui'
基础用法
用 v-model 绑定一个布尔值。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSwitch } from '@ns/ui'
const value = ref(false)
</script>
<template>
<NsSwitch v-model="value" />
<p style="margin-top: 12px">绑定值:{{ value }}</p>
</template>
禁用
disabled 禁用后不能点击,也不能用 Tab 键聚焦。打开、关闭两种状态和带文字的开关都有对应的禁用样式。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch } from '@ns/ui'
const off = ref(false)
const on = ref(true)
</script>
<template>
<NsSpace wrap>
<NsSwitch v-model="off" disabled />
<NsSwitch v-model="on" disabled />
<NsSwitch v-model="on" shape="square" disabled />
<NsSwitch v-model="on" active-text="开启" inactive-text="关闭" disabled />
</NsSpace>
</template>
加载状态
loading 为 true 时圆钮上显示转圈,这期间点击和按键都不会切换。打开、关闭时都能加载。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch } from '@ns/ui'
const on = ref(true)
const off = ref(false)
</script>
<template>
<NsSpace wrap>
<NsSwitch v-model="on" loading />
<NsSwitch v-model="off" loading />
<NsSwitch v-model="on" shape="square" loading />
</NsSpace>
</template>
切换前先请求接口
组件没有“切换前拦截”的钩子。需要等接口成功再切换时,不用 v-model,改成 :model-value 加 @change:在 change 里发请求,成功后自己改值,请求期间用 loading 挡住重复点击。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMessage, NsSwitch } from '@ns/ui'
const value = ref(false)
const loading = ref(false)
// 这里用定时器代替真实的接口请求
const save = (next: boolean) =>
new Promise<void>((resolve) => {
window.setTimeout(() => {
NsMessage.success(next ? '已开启' : '已关闭')
resolve()
}, 800)
})
const handleChange = async (next: boolean | string | number) => {
loading.value = true
try {
await save(next as boolean)
value.value = next as boolean
} finally {
loading.value = false
}
}
</script>
<template>
<NsSwitch :model-value="value" :loading="loading" @change="handleChange" />
</template>
尺寸
size 有 large、default、small 三种,轨道分别是 44×22、36×18、28×14 像素。不写时跟随所在的 NsFormItem、NsForm、NsConfigProvider,都没有时是 default。
下面每一行是一种尺寸:关闭、打开、加载中、方形、带文字。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch } from '@ns/ui'
const off = ref(false)
const on = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsSwitch v-model="off" size="large" />
<NsSwitch v-model="on" size="large" />
<NsSwitch v-model="on" size="large" loading />
<NsSwitch v-model="on" size="large" shape="square" />
<NsSwitch v-model="on" size="large" active-text="开" inactive-text="关" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsSwitch v-model="off" />
<NsSwitch v-model="on" />
<NsSwitch v-model="on" loading />
<NsSwitch v-model="on" shape="square" />
<NsSwitch v-model="on" active-text="开" inactive-text="关" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsSwitch v-model="off" size="small" />
<NsSwitch v-model="on" size="small" />
<NsSwitch v-model="on" size="small" loading />
<NsSwitch v-model="on" size="small" shape="square" />
<NsSwitch v-model="on" size="small" active-text="开" inactive-text="关" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
形状
shape 默认是 round,轨道两端是半圆(胶囊形);square 是圆角长方形,轨道和圆钮都是小圆角。三种尺寸都能用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch } from '@ns/ui'
const off = ref(false)
const on = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">round</span>
<NsSwitch v-model="off" />
<NsSwitch v-model="on" size="large" />
<NsSwitch v-model="on" />
<NsSwitch v-model="on" size="small" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">square</span>
<NsSwitch v-model="off" shape="square" />
<NsSwitch v-model="on" shape="square" size="large" />
<NsSwitch v-model="on" shape="square" />
<NsSwitch v-model="on" shape="square" size="small" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
文字描述
inactive-text 显示在开关左边,active-text 显示在右边。两段文字一直都在:关闭时左边那段是正文色、右边变淡,打开时右边那段是主色、左边变淡。可以只写其中一个。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch } from '@ns/ui'
const value = ref(false)
const notify = ref(true)
const dark = ref(false)
</script>
<template>
<NsSpace wrap size="large">
<NsSwitch v-model="value" active-text="开启" inactive-text="关闭" />
<NsSwitch v-model="notify" active-text="接收通知" />
<NsSwitch v-model="dark" inactive-text="暗色主题" />
</NsSpace>
</template>
自定义值
用 active-value 和 inactive-value 指定打开、关闭时的值,可以是字符串或数字。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSpace, NsSwitch } from '@ns/ui'
const status = ref('on')
const flag = ref(0)
</script>
<template>
<NsSpace wrap>
<NsSwitch v-model="status" active-value="on" inactive-value="off" />
<NsSwitch v-model="flag" :active-value="1" :inactive-value="0" />
</NsSpace>
<p style="margin-top: 12px">status:'{{ status }}',flag:{{ flag }}</p>
</template>
事件
用户点击或按键切换时触发 change(和 update:modelValue 同时),参数是切换后的值。在代码里改绑定值不触发。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSpace, NsSwitch } from '@ns/ui'
const value = ref(false)
const logs = ref<string[]>([])
const onChange = (next: boolean | string | number) => {
logs.value = [`change:${next}`, ...logs.value].slice(0, 5)
}
</script>
<template>
<NsSpace wrap>
<NsSwitch v-model="value" @change="onChange" />
<NsButton size="small" @click="value = !value">在代码里切换(不触发)</NsButton>
</NsSpace>
<p style="margin-top: 12px">最近的事件(新的在前):{{ logs.join(',') || '还没有' }}</p>
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,开关通过 aria-labelledby 关联表单项的标签,不会随原生 <form> 提交。false 不算空值,required 拦不住没打开的开关,要写 validator 判断。不需要校验时设 :validate-event="false"。
校验不通过时表单项下面显示错误信息,开关本身的颜色不变。点“提交”看看:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsSwitch } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ agree: false })
const rules: Record<string, FormRule[]> = {
agree: [{ validator: (_rule, value) => value === true, message: '请先开启', trigger: 'change' }]
}
const submit = () => {
formRef.value?.validate()
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="120px" @submit.prevent>
<NsFormItem label="接收服务通知" prop="agree">
<NsSwitch v-model="model.agree" />
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="submit">提交</NsButton>
</NsFormItem>
</NsForm>
</template>
键盘操作
开关可以用 Tab 键聚焦,聚焦后按空格或回车切换。按住不放只切换一次。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | boolean | string | number | false | 绑定值,支持 v-model。等于 activeValue 时是打开,其他值都算关闭 |
| disabled | boolean | false | 是否禁用 |
| loading | boolean | false | 是否显示加载状态。加载中不能切换 |
| size | 'large' | 'default' | 'small' | - | 尺寸:轨道 44×22 / 36×18 / 28×14 像素。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 'default' |
| shape | 'round' | 'square' | 'round' | 形状:round 两端是半圆,square 是圆角长方形 |
| activeText | string | '' | 打开时对应的文字,显示在开关右边 |
| inactiveText | string | '' | 关闭时对应的文字,显示在开关左边 |
| activeValue | boolean | string | number | true | 打开时的值 |
| inactiveValue | boolean | string | number | false | 关闭时的值 |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: boolean | string | number) | 用户点击或按键切换时触发,v-model 用的就是它 |
| change | (value: boolean | string | number) | 用户点击或按键切换时触发,参数是切换后的值 |
类型
import type { SwitchSize, SwitchShape, SwitchProps } from '@ns/ui'
type SwitchSize = 'large' | 'default' | 'small'
type SwitchShape = 'round' | 'square'
interface SwitchProps {
modelValue?: boolean | string | number
disabled?: boolean
loading?: boolean
size?: SwitchSize
shape?: SwitchShape
activeText?: string
inactiveText?: string
activeValue?: boolean | string | number
inactiveValue?: boolean | string | number
/** 值变化时是否触发所在表单项的校验,默认 true */
validateEvent?: boolean
}
注意事项
- 组件是受控的,不保存自己的状态。只写
:model-value不处理update:modelValue或change时,点击后显示不会变。 - 绑定值既不等于
activeValue也不等于inactiveValue时显示为关闭,点击后变成activeValue。比较时区分类型,1和'1'不相等。 - 只有用户操作会触发事件,在代码里改绑定值不会触发
change。 - 禁用和加载中都不触发事件。加载中的开关仍然能用 Tab 键聚焦,禁用的不能。
- 组件没有插槽,也没有暴露方法。文字只能用
activeText、inactiveText传字符串。 - 根元素是
role="switch"的div,不是原生表单控件,不会随<form>提交。
优化点
- [ ] 支持自定义图标
- [ ] 支持内联文字(把文字放进轨道里)
- [ ] 支持自定义宽度
- [ ] 支持切换前拦截(
beforeChange),省掉手写:model-value+loading的样板代码 - [ ] 暴露
focus、blur方法