Segmented 分段控制器
把几个互斥的选项排成一行,选中项下面有一块会滑动的底色。适合选项少(一般 2 到 5 个)、需要频繁切换的场景,例如切换视图、切换时间范围。
引入
import { NsSegmented } from '@ns/ui'
基础用法
options 传字符串数组,v-model 绑定当前选中的那一项。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSegmented } from '@ns/ui'
const value = ref('每日')
const options = ['每日', '每周', '每月', '每年']
</script>
<template>
<NsSegmented v-model="value" :options="options" />
<p style="margin-top: 12px">绑定值:'{{ value }}'</p>
</template>
对象选项
显示的文字和绑定的值不一样时,options 传对象数组:value 是值,label 是文字(不写时显示 value),title 是鼠标停在选项上时浏览器显示的提示。payload 可以放自己的附加数据,组件不读取。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSegmented } from '@ns/ui'
import type { SegmentedOption } from '@ns/ui'
const value = ref('list')
const options: SegmentedOption[] = [
{ value: 'list', label: '列表视图', title: '按列表显示' },
{ value: 'grid', label: '网格视图', title: '按网格显示' },
{ value: 'table', label: '表格视图', title: '按表格显示' }
]
</script>
<template>
<NsSegmented v-model="value" :options="options" />
<p style="margin-top: 12px">绑定值:'{{ value }}'</p>
</template>
数字选项
options 也可以是数字数组,这时绑定值是数字。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSegmented } from '@ns/ui'
const pageSize = ref(20)
const options = [10, 20, 50, 100]
</script>
<template>
<NsSegmented v-model="pageSize" :options="options" />
<p style="margin-top: 12px">绑定值:{{ pageSize }}({{ typeof pageSize }})</p>
</template>
带图标
选项的 icon 写图标名(和 NsIcon 的 name 一样),图标显示在文字前面。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSegmented } from '@ns/ui'
import type { SegmentedOption } from '@ns/ui'
const value = ref('list')
const options: SegmentedOption[] = [
{ value: 'list', label: '列表', icon: 'menu' },
{ value: 'grid', label: '网格', icon: 'apps' },
{ value: 'table', label: '表格', icon: 'table' }
]
</script>
<template>
<NsSegmented v-model="value" :options="options" />
</template>
尺寸
size 有 small、default、large 三种,高度分别是 24、32、40px,和同尺寸的按钮、输入框一样高;文字是 12、14、16px,圆角跟着尺寸变(外框 4、6、8px)。
不写 size 时依次跟随所在的 NsFormItem、NsForm、NsConfigProvider 的 size,都没有时是 default。下面每一行最后放一个同尺寸的按钮对比高度:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSegmented, NsSpace } from '@ns/ui'
import type { SegmentedOption } from '@ns/ui'
const value = ref('day')
const options: SegmentedOption[] = [
{ value: 'day', label: '每日', icon: 'calendar' },
{ value: 'week', label: '每周' },
{ value: 'month', label: '每月' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsSegmented v-model="value" :options="options" size="large" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsSegmented v-model="value" :options="options" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsSegmented v-model="value" :options="options" size="small" />
<NsButton size="small">按钮</NsButton>
</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>
撑满宽度
加上 block 以后组件占满父容器的宽度,各个选项平分宽度。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSegmented } from '@ns/ui'
const value = ref('每日')
const options = ['每日', '每周', '每月']
</script>
<template>
<NsSegmented v-model="value" :options="options" block />
</template>
禁用
disabled 禁用整个组件。只禁用某一项时,在这一项上写 disabled: true,方向键也会跳过它。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSegmented, NsSpace } from '@ns/ui'
import type { SegmentedOption } from '@ns/ui'
const a = ref('每日')
const b = ref('day')
const options = ['每日', '每周', '每月']
const partlyDisabled: SegmentedOption[] = [
{ value: 'day', label: '每日' },
{ value: 'week', label: '每周', disabled: true },
{ value: 'month', label: '每月' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">整个禁用</span>
<NsSegmented v-model="a" :options="options" disabled />
</NsSpace>
<NsSpace wrap>
<span class="row-label">禁用一项</span>
<NsSegmented v-model="b" :options="partlyDisabled" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
事件
用户换了选中项时触发 change(和 update:modelValue 同时),参数是新选中项的 value;点已经选中的项不触发。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMessage, NsSegmented } from '@ns/ui'
const value = ref('chart')
const options = [
{ value: 'chart', label: '图表' },
{ value: 'table', label: '表格' }
]
const onChange = (next: string | number) => {
NsMessage.info(`切换到:${next}`)
}
</script>
<template>
<NsSegmented v-model="value" :options="options" @change="onChange" />
</template>
选项动态变化
options 可以随时换。选项增减、文字变长、容器宽度变化以后,底色块会跟着选中项重新定位。绑定值在新选项里找不到时,没有选中项,底色块不显示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSegmented, NsSpace } from '@ns/ui'
import type { SegmentedOption } from '@ns/ui'
const value = ref('b')
const options = ref<SegmentedOption[]>([
{ value: 'a', label: '选项A' },
{ value: 'b', label: '选项B' },
{ value: 'c', label: '选项C' }
])
let seed = 0
const prepend = () => {
seed += 1
options.value = [{ value: `new-${seed}`, label: `新选项${seed}` }, ...options.value]
}
const removeSelected = () => {
options.value = options.value.filter((opt) => opt.value !== value.value)
}
</script>
<template>
<NsSpace wrap>
<NsSegmented v-model="value" :options="options" />
<NsButton size="small" @click="prepend">在前面加一项</NsButton>
<NsButton size="small" @click="removeSelected">删掉选中项</NsButton>
</NsSpace>
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,组件通过 aria-labelledby 关联表单项的标签,尺寸跟随表单项和表单。不需要校验时设 :validate-event="false"。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsForm, NsFormItem, NsSegmented } from '@ns/ui'
const model = reactive({ period: '按周', view: '列表' })
</script>
<template>
<NsForm :model="model" size="small" @submit.prevent>
<NsFormItem label="统计周期">
<NsSegmented v-model="model.period" :options="['按日', '按周', '按月']" />
</NsFormItem>
<NsFormItem label="显示方式">
<NsSegmented v-model="model.view" :options="['列表', '网格']" />
</NsFormItem>
</NsForm>
</template>
键盘操作
用 Tab 键进入组件时焦点落在选中项上,整个组件只占一个 Tab 停靠点。
| 按键 | 作用 |
|---|---|
→ ↓ | 选中下一项,到最后一项后回到第一项 |
← ↑ | 选中上一项,到第一项后回到最后一项 |
Enter 空格 | 选中当前聚焦的项 |
方向键会跳过禁用的选项。
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | number | - | 绑定值,支持 v-model,等于选中项的 value。没传时第一项显示为选中 |
| options | SegmentedOption[] | string[] | number[] | [] | 选项。字符串、数字数组里每一项既是值也是文字 |
| size | 'small' | 'default' | 'large' | - | 尺寸,高度 24 / 32 / 40px。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 'default' |
| disabled | boolean | false | 是否禁用整个组件 |
| block | boolean | false | 是否占满父容器宽度 |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验 |
SegmentedOption
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | string | number | - | 选项的值,必填,同一组里不能重复 |
| label | string | - | 显示的文字。不写时显示 value |
| disabled | boolean | false | 是否禁用这一项 |
| icon | string | - | 图标名,显示在文字前面 |
| title | string | - | 原生 title 属性,鼠标停留时由浏览器显示 |
| payload | any | - | 使用方自己带的附加数据,组件不读取 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string | number) | 用户换了选中项时触发,v-model 用的就是它 |
| change | (value: string | number) | 用户换了选中项时触发,参数是新选中项的 value。点已经选中的项不触发 |
类型
import type { SegmentedOption, SegmentedProps } from '@ns/ui'
interface SegmentedOption {
value: string | number
label?: string
disabled?: boolean
icon?: string
title?: string
payload?: any
}
interface SegmentedProps {
modelValue?: string | number
options?: SegmentedOption[] | string[] | number[]
size?: 'small' | 'default' | 'large'
disabled?: boolean
block?: boolean
/** 值变化时是否触发所在表单项的校验,默认 true */
validateEvent?: boolean
}
注意事项
- 组件是受控的,不保存自己的选中项。只写
:model-value不处理update:modelValue时,点击后选中项不会变。 - 没传绑定值(
undefined)时,第一项只是显示成选中,组件不会主动发事件把值补上。这时点第一项会触发update:modelValue和change。需要一开始就有值时,自己给绑定值赋初始值。 - 选项的
value用作列表的 key,同一组里不能重复。比较时区分类型,1和'1'是两个不同的值。 options是一个数组,不能字符串、数字、对象混着写(类型上不允许)。- 组件没有插槽,选项内容只能是图标加文字;也没有暴露方法。
- 选项多到一行放不下时不会换行,也不会出现滚动条,会超出容器。选项多的时候改用 Select 或 Tabs。
- 底色块的位置是按选中项的实际位置量出来的。组件一开始在
display: none的容器里时量不到,等容器显示出来、宽度变化以后会自动重新定位。
优化点
- [ ] 支持用插槽自定义选项内容
- [ ] 支持竖向排列
- [ ] 选中项的文字会加粗,宽度比未选中时略大,切换时旁边的选项会有很小的位移
- [ ] 选项一行放不下时的处理(滚动或换行)