Select 选择器
从下拉列表里选一项或多项。选项比较多、不适合用单选框或多选框平铺时使用。
引入
import { NsSelect, NsSelectOption } from '@ns/ui'
基础用法
用 options 传选项,v-model 绑定选中项的 value。没有选中时值是 undefined,显示 placeholder(默认“请选择”)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const value = ref<string>()
const city = ref<string>()
const options: SelectOption[] = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsSelect v-model="value" :options="options" style="width: 240px" />
<NsSelect
v-model="city"
:options="options"
placeholder="请选择所在城市"
style="width: 240px"
/>
</NsSpace>
<span>选中的值:{{ value ?? 'undefined' }}</span>
</NsSpace>
</template>
用插槽写选项
不传 options 时,可以在默认插槽里写 NsSelectOption。两种写法选一种,不要同时用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSelectOption } from '@ns/ui'
const value = ref<number>(2)
</script>
<template>
<NsSelect v-model="value" style="width: 240px">
<NsSelectOption label="选项一" :value="1" />
<NsSelectOption label="选项二" :value="2" />
<NsSelectOption label="选项三" :value="3" />
</NsSelect>
</template>
自定义选项内容
NsSelectOption 的默认插槽可以自定义选项的显示内容。选中后输入框里显示的仍然是 label。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSelectOption } from '@ns/ui'
const value = ref<string>()
const cities = [
{ label: '北京', value: 'beijing', code: '010' },
{ label: '上海', value: 'shanghai', code: '021' },
{ label: '广州', value: 'guangzhou', code: '020' }
]
</script>
<template>
<NsSelect v-model="value" style="width: 240px">
<NsSelectOption
v-for="city in cities"
:key="city.value"
:label="city.label"
:value="city.value"
>
<span>{{ city.label }}</span>
<span style="margin-left: 8px; font-size: 12px">区号 {{ city.code }}</span>
</NsSelectOption>
</NsSelect>
</template>
禁用
disabled 禁用整个选择器:不能展开,有值时也不显示清除按钮,多选的标签上没有叉。选项上的 disabled 只禁用这一项,点击和键盘都选不到它;多选时已经选中的禁用项可以通过标签上的叉移除。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const empty = ref<string>()
const single = ref<string>('beijing')
const multi = ref<string[]>(['beijing', 'shanghai'])
const value = ref<string>()
const values = ref<string[]>(['shanghai'])
const options: SelectOption[] = [
{ label: '北京', value: 'beijing' },
{ label: '上海(禁用)', value: 'shanghai', disabled: true },
{ label: '广州', value: 'guangzhou' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">整体禁用</span>
<NsSelect v-model="empty" :options="options" disabled style="width: 200px" />
<NsSelect v-model="single" :options="options" disabled clearable style="width: 200px" />
<NsSelect v-model="multi" :options="options" multiple disabled style="width: 260px" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">选项禁用</span>
<NsSelect v-model="value" :options="options" style="width: 200px" />
<NsSelect v-model="values" :options="options" multiple style="width: 260px" />
</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>
可清空
加上 clearable 后,有值时右侧显示清除按钮(没值或禁用时不显示)。点击后单选的值变成 undefined,多选的值变成 []。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
const value = ref<string | undefined>('shanghai')
const values = ref<string[]>(['beijing', 'shanghai'])
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' }
]
</script>
<template>
<NsSpace wrap>
<NsSelect v-model="value" clearable :options="options" style="width: 240px" />
<NsSelect v-model="values" multiple clearable :options="options" style="width: 300px" />
</NsSpace>
<p style="margin-top: 12px">
单选:{{ value ?? 'undefined' }};多选:{{ JSON.stringify(values) }}
</p>
</template>
多选
加上 multiple 后绑定值是数组,选中的项显示成标签。点选项不会关闭下拉层,点标签上的叉可以移除这一项。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect } from '@ns/ui'
const value = ref<string[]>(['beijing', 'shanghai'])
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' },
{ label: '深圳', value: 'shenzhen' }
]
</script>
<template>
<NsSelect v-model="value" multiple clearable :options="options" style="width: 360px" />
</template>
折叠标签
多选时默认最多显示 3 个标签,其余的折叠成 +N。max-collapse-tags 改显示的个数;:collapse-tags="false" 关闭折叠,标签全部显示,放不下时换行。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
const value = ref<string[]>(['beijing', 'shanghai', 'guangzhou', 'shenzhen', 'hangzhou'])
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' },
{ label: '深圳', value: 'shenzhen' },
{ label: '杭州', value: 'hangzhou' },
{ label: '成都', value: 'chengdu' }
]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSelect v-model="value" multiple :options="options" />
<NsSelect v-model="value" multiple :max-collapse-tags="1" :options="options" />
<NsSelect v-model="value" multiple :collapse-tags="false" :options="options" />
</NsSpace>
</template>
tag-type 设置标签的类型,可选值和 NsTag 的 type 相同,共 6 种:primary(默认)、success、warning、danger、info、help。折叠出来的 +N 标签也用这个类型。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
const value = ref<string[]>(['beijing', 'shanghai', 'guangzhou', 'shenzhen'])
const types = ['primary', 'success', 'warning', 'danger', 'info', 'help'] as const
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' },
{ label: '深圳', value: 'shenzhen' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace v-for="type in types" :key="type" wrap>
<span class="row-label">{{ type }}</span>
<NsSelect
v-model="value"
multiple
:max-collapse-tags="2"
:tag-type="type"
:options="options"
style="width: 320px"
/>
</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>
最多可选数
多选时用 max 限制最多选几项。选满后,其余没选中的选项变成禁用状态。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect } from '@ns/ui'
const value = ref<string[]>([])
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' },
{ label: '深圳', value: 'shenzhen' }
]
</script>
<template>
<NsSelect v-model="value" multiple :max="2" :options="options" placeholder="最多选 2 项" />
</template>
全选和清空
多选时加上 select-all,下拉层顶部会出现“全选”和“清空”两个按钮。全选只选没禁用的选项;已有选中项时保留它们,再按顺序补上没选的;同时设置了 max 时最多补到 max 项,并在按钮右边显示“已选数 / max”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
const value = ref<string[]>([])
const limited = ref<string[]>(['shanghai'])
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' },
{ label: '深圳', value: 'shenzhen' },
{ label: '杭州(禁用)', value: 'hangzhou', disabled: true }
]
</script>
<template>
<NsSpace wrap>
<NsSelect v-model="value" multiple select-all :options="options" style="width: 320px" />
<NsSelect
v-model="limited"
multiple
select-all
:max="3"
:options="options"
placeholder="全选最多补到 3 项"
style="width: 320px"
/>
</NsSpace>
</template>
可搜索
加上 filterable 后,展开时输入框可以打字,只显示文字包含关键词的选项(不区分大小写)。输入后直接按回车选中第一个匹配项;没有匹配项时显示“暂无数据”。单选已有值时,搜索框的占位文字是当前选中项的文字。多选时选中一项后搜索词清空,可以接着搜下一项。用插槽写的选项同样会被过滤。
下面依次是单选、多选、用插槽写选项:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSelectOption, NsSpace } from '@ns/ui'
const value = ref<string>('banana')
const values = ref<string[]>([])
const slotValue = ref<string>()
const options = [
{ label: '苹果 Apple', value: 'apple' },
{ label: '香蕉 Banana', value: 'banana' },
{ label: '水蜜桃 Peach', value: 'peach' },
{ label: '菠萝 Pineapple', value: 'pineapple' }
]
</script>
<template>
<NsSpace wrap>
<NsSelect
v-model="value"
filterable
:options="options"
placeholder="输入文字搜索"
style="width: 200px"
/>
<NsSelect
v-model="values"
filterable
multiple
:options="options"
placeholder="可以输入 apple"
style="width: 280px"
/>
<NsSelect v-model="slotValue" filterable placeholder="插槽选项也能搜" style="width: 200px">
<NsSelectOption
v-for="item in options"
:key="item.value"
:label="item.label"
:value="item.value"
/>
</NsSelect>
</NsSpace>
</template>
尺寸
size 有 large、default、small 三种,和同尺寸的 NsInput、NsButton 一致:高度 40 / 32 / 24px,字号 16 / 14 / 12px,圆角 8 / 6 / 4px。下拉面板也跟着变,选项行高 40 / 约 36 / 28px,字号 16 / 14 / 12px,左右内边距 16 / 12 / 8px,选项文字和输入框里的文字左边齐平。不写 size 时依次跟随所在的 NsFormItem、NsForm、NsConfigProvider 的 size,都没有时是 default。
每一行是一种尺寸,依次是单选(可清空)、多选、同尺寸的按钮。多选标签在 large 时用 default 尺寸的标签,其余用 small 尺寸的标签。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const value = ref<string>('beijing')
const values = ref<string[]>(['beijing', 'shanghai'])
const options: SelectOption[] = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsSelect v-model="value" size="large" clearable :options="options" style="width: 180px" />
<NsSelect v-model="values" size="large" multiple :options="options" style="width: 260px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsSelect v-model="value" clearable :options="options" style="width: 180px" />
<NsSelect v-model="values" multiple :options="options" style="width: 260px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsSelect v-model="value" size="small" clearable :options="options" style="width: 180px" />
<NsSelect v-model="values" size="small" multiple :options="options" style="width: 260px" />
<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>
空数据提示
没有选项时,下拉层显示 empty-text(默认“暂无数据”);输入了搜索词、但没有匹配项时显示 no-match-text,不传时也用 empty-text。要放图标、链接等复杂内容时用 empty 插槽,写了插槽就以插槽为准。
第一行用属性改文字:左边没有选项,右边搜一个不存在的词(例如“西瓜”)看看;第二行用插槽:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
const value = ref<string>()
const fruit = ref<string>()
const value2 = ref<string>()
const fruit2 = ref<string>()
const options = [
{ label: '苹果', value: 'apple' },
{ label: '香蕉', value: 'banana' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsSelect v-model="value" :options="[]" empty-text="还没有添加分类" style="width: 240px" />
<NsSelect
v-model="fruit"
filterable
:options="options"
no-match-text="没有找到这种水果"
placeholder="输入“西瓜”试试"
style="width: 240px"
/>
</NsSpace>
<NsSpace wrap>
<NsSelect v-model="value2" :options="[]" style="width: 240px">
<template #empty>还没有可选的内容</template>
</NsSelect>
<NsSelect
v-model="fruit2"
filterable
:options="options"
placeholder="插槽:输入“西瓜”试试"
style="width: 240px"
>
<template #empty>没有找到这种水果,换个词试试</template>
</NsSelect>
</NsSpace>
</NsSpace>
</template>
展开时加载选项
选项要从接口取、又不想页面一打开就请求时,可以在 visible-change 里第一次展开时再加载。加载期间把 loading 设为 true,下拉层显示转圈和 loading-text(默认“加载中”),不显示选项。下面用 setTimeout 模拟 1 秒的请求,左边用默认文字,右边把文字改成“正在获取部门...”:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const departments: SelectOption[] = [
{ label: '研发部', value: 'dev' },
{ label: '产品部', value: 'product' },
{ label: '运营部', value: 'ops' }
]
const value = ref<string>()
const options = ref<SelectOption[]>([])
const loading = ref(false)
const value2 = ref<string>()
const options2 = ref<SelectOption[]>([])
const loading2 = ref(false)
const handleVisibleChange = (visible: boolean) => {
if (!visible || loading.value || options.value.length > 0) return
loading.value = true
setTimeout(() => {
options.value = departments
loading.value = false
}, 1000)
}
const handleVisibleChange2 = (visible: boolean) => {
if (!visible || loading2.value || options2.value.length > 0) return
loading2.value = true
setTimeout(() => {
options2.value = departments
loading2.value = false
}, 1000)
}
</script>
<template>
<NsSpace wrap>
<NsSelect
v-model="value"
:options="options"
:loading="loading"
placeholder="展开后加载部门"
style="width: 240px"
@visible-change="handleVisibleChange"
/>
<NsSelect
v-model="value2"
:options="options2"
:loading="loading2"
loading-text="正在获取部门..."
placeholder="自定义加载文字"
style="width: 240px"
@visible-change="handleVisibleChange2"
/>
</NsSpace>
</template>
远程搜索
选项太多、只能按关键词去接口查时,加上 remote 并传 remote-method。展开后直接就能输入(不用再写 filterable),输入停止 debounce 毫秒(默认 300)后调用 remote-method(query);删光搜索词时也会调用,参数是空字符串,可以在这时清空选项或恢复默认列表。组件不再按 label 本地过滤,下拉层里显示的就是你给的选项。
remote-method 有两种写法:
- 自己更新选项:函数里请求接口,结果写进
options,请求期间把loading设为true。下面就是这种写法,用setTimeout模拟 600 毫秒的接口。还没输入时显示empty-text,搜不到时显示no-match-text。 - 返回结果:函数直接返回选项数组,或者返回
Promise,组件用它的结果当选项。返回Promise时组件自己显示加载中,并且只采用最后一次搜索的结果,先发出、后返回的旧结果会被丢弃,见下一个示例。
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const cities = ['北京', '北海', '北戴河', '上海', '上饶', '广州', '广元', '深圳', '杭州', '南京']
const value = ref<string>()
const options = ref<SelectOption[]>([])
const loading = ref(false)
const remoteMethod = (query: string) => {
if (!query) {
options.value = []
return
}
loading.value = true
// 用 setTimeout 模拟接口:返回名字里包含关键词的城市
setTimeout(() => {
options.value = cities
.filter((city) => city.includes(query))
.map((city) => ({ label: city, value: city }))
loading.value = false
}, 600)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSelect
v-model="value"
remote
:remote-method="remoteMethod"
:options="options"
:loading="loading"
clearable
placeholder="输入“北”或“上”"
empty-text="输入城市名搜索"
no-match-text="没有找到相关城市"
style="width: 240px"
/>
<span>选中的值:{{ value ?? 'undefined' }}</span>
</NsSpace>
</template>
多选时选中一项后保留搜索词和这次的结果,可以接着选同一批里的其他项(本地搜索是清空搜索词)。选中过的项会记住它的文字,换了一批搜索结果、已选项不在新结果里时,标签仍然显示原来的文字,不会变成值。
下面的 remote-method 返回 Promise,没有自己维护 options 和 loading;debounce 改成 500 毫秒,loading-text 改成“正在搜索...”。先搜“研发”选两个人,再搜“产品”,前面选的标签不变:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const staff: SelectOption[] = [
{ label: '研发 - 张三', value: 1 },
{ label: '研发 - 李四', value: 2 },
{ label: '研发 - 王五', value: 3 },
{ label: '产品 - 赵六', value: 4 },
{ label: '产品 - 钱七', value: 5 },
{ label: '运营 - 孙八', value: 6 }
]
const values = ref<number[]>([])
// 返回 Promise:组件自己显示加载中,结果当作选项。用 setTimeout 模拟 800 毫秒的接口
const searchStaff = (query: string) =>
new Promise<SelectOption[]>((resolve) => {
setTimeout(() => {
resolve(query ? staff.filter((item) => item.label.includes(query)) : [])
}, 800)
})
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSelect
v-model="values"
multiple
remote
:remote-method="searchStaff"
:debounce="500"
loading-text="正在搜索..."
placeholder="输入“研发”“产品”或姓名"
empty-text="输入关键词搜索人员"
style="max-width: 360px"
/>
<span>选中的值:{{ JSON.stringify(values) }}</span>
</NsSpace>
</template>
虚拟滚动
选项有几千、上万个时,加上 virtual,下拉层只渲染看得见的十几项,滚动时再换成新的,展开和滚动都不卡。键盘上下移动时会自动滚到停留的选项;单选展开时滚到当前选中的项。可以和可搜索、多选、全选、max、远程搜索一起用。
虚拟滚动只对 options 属性生效,默认插槽里写的 NsSelectOption 不支持(写了插槽时照常全部渲染,开发环境下会提示)。每个选项的高度是固定的(large 40px、default 36px、small 28px),下拉层宽度和选择器一样宽,文字太长时省略。
下面用脚本生成一万个选项,每 7 个里有一个禁用:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const options: SelectOption[] = Array.from({ length: 10000 }, (_, index) => ({
label: `选项 ${index + 1}`,
value: index + 1,
disabled: (index + 1) % 7 === 0
}))
const value = ref<number>(5000)
const values = ref<number[]>([1, 2, 3])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsSelect
v-model="value"
virtual
filterable
clearable
:options="options"
style="width: 240px"
/>
<NsSelect
v-model="values"
virtual
multiple
filterable
select-all
:options="options"
placeholder="可以全选一万项"
style="width: 320px"
/>
</NsSpace>
<span>单选:{{ value ?? 'undefined' }};多选已选 {{ values.length }} 项</span>
</NsSpace>
</template>
远程搜索返回的结果很多时,也可以加上 virtual。下面输入任意文字,模拟的接口返回 5000 条结果:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const value = ref<string>()
// 用 setTimeout 模拟接口:不管搜什么都返回 5000 条
const search = (query: string) =>
new Promise<SelectOption[]>((resolve) => {
setTimeout(() => {
resolve(
query
? Array.from({ length: 5000 }, (_, index) => ({
label: `${query} - 结果 ${index + 1}`,
value: `${query}-${index + 1}`
}))
: []
)
}, 500)
})
</script>
<template>
<NsSelect
v-model="value"
virtual
remote
:remote-method="search"
placeholder="输入任意文字搜索"
empty-text="输入文字后返回 5000 条结果"
style="width: 280px"
/>
</template>
事件
change 只在用户操作导致值变化时触发;visible-change 在下拉层展开、收起时触发;remove-tag 在点标签上的叉时触发;select-all、clear 分别在点“全选”、点清除按钮或“清空”时触发。操作下面的选择器,最近的事件显示在下方:
<script setup lang="ts">
import { ref } from 'vue'
import { NsSelect, NsSpace } from '@ns/ui'
const value = ref<string[]>(['beijing'])
const logs = ref<string[]>([])
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' },
{ label: '深圳', value: 'shenzhen' }
]
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onChange = (val: unknown) => log(`change:${JSON.stringify(val)}`)
const onVisibleChange = (visible: boolean) => log(`visible-change:${visible}`)
const onRemoveTag = (val: string | number) => log(`remove-tag:${val}`)
const onSelectAll = (vals: (string | number)[]) => log(`select-all:${JSON.stringify(vals)}`)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSelect
v-model="value"
multiple
clearable
select-all
:options="options"
style="max-width: 360px"
@change="onChange"
@visible-change="onVisibleChange"
@remove-tag="onRemoveTag"
@select-all="onSelectAll"
@clear="log('clear')"
/>
<div class="logs">
<div v-if="logs.length === 0">还没有触发事件</div>
<div v-for="(item, index) in logs" :key="index">{{ item }}</div>
</div>
</NsSpace>
</template>
<style scoped>
.logs {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
调用方法
通过 ref 调用 focus()、blur()。可搜索并且已展开时,focus() 聚焦到搜索框。ref 上的 filteredOptions 是 options 按当前搜索词过滤后的结果(远程搜索时不过滤),下面展开后输入文字看看:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsSelect, NsSpace } from '@ns/ui'
const selectRef = ref<InstanceType<typeof NsSelect>>()
const value = ref<string>()
const options = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' },
{ label: '深圳', value: 'shenzhen' }
]
</script>
<template>
<NsSpace wrap>
<NsSelect ref="selectRef" v-model="value" filterable :options="options" style="width: 240px" />
<NsButton @click="selectRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="selectRef?.blur()">失焦(blur)</NsButton>
</NsSpace>
<p style="margin-top: 12px">
filteredOptions:{{ selectRef?.filteredOptions.map((item) => item.label).join('、') }}
</p>
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,收起下拉层触发 blur 规则;不写 size、disabled 时跟随表单。下面的城市展开后不选直接收起,就会提示必填:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsMessage, NsSelect, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive<{ city?: string; tags: string[] }>({ city: undefined, tags: [] })
const rules: Record<string, FormRule[]> = {
city: [{ required: true, message: '请选择城市', trigger: ['change', 'blur'] }],
tags: [{ required: true, message: '至少选一个标签', trigger: 'change' }]
}
const cities = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' }
]
const tags = [
{ label: '前端', value: 'fe' },
{ label: '后端', value: 'be' },
{ label: '测试', value: 'qa' }
]
const submit = async () => {
const result = await formRef.value?.validate()
if (result?.valid) NsMessage.success('校验通过')
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" label-width="80px" style="max-width: 420px">
<NsFormItem label="城市" prop="city">
<NsSelect v-model="model.city" :options="cities" clearable />
</NsFormItem>
<NsFormItem label="标签" prop="tags">
<NsSelect v-model="model.tags" :options="tags" multiple clearable />
</NsFormItem>
<NsFormItem>
<NsSpace>
<NsButton type="primary" @click="submit">提交</NsButton>
<NsButton @click="formRef?.resetFields()">重置</NsButton>
</NsSpace>
</NsFormItem>
</NsForm>
</template>
键盘操作
选择器可以用 Tab 聚焦,聚焦后:
| 按键 | 作用 |
|---|---|
| Enter、空格 | 没展开时展开;展开后选中当前停留的选项,没有停留项时收起 |
| ↓、↑ | 没展开时展开;展开后在选项之间移动,跳过禁用项,到头后循环 |
| Esc | 收起下拉层,焦点回到选择器 |
| Tab | 收起下拉层,焦点移到下一个元素 |
可搜索、远程搜索时,空格用来在搜索框里输入,不会选中选项。输入后停留在第一个匹配的选项上,直接按回车就能选中;远程搜索的结果回来后也停在第一项。加载中(loading)不能上下移动,按回车也不收起,等结果出来再选。虚拟滚动时,停留的选项不在可见区域里会自动滚过去。
NsSelect Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | number | (string | number)[] | - | 绑定值,支持 v-model。单选是选项的 value,多选是 value 数组 |
| options | SelectOption[] | [] | 选项数据。不传时用默认插槽里的 NsSelectOption |
| multiple | boolean | false | 是否多选 |
| disabled | boolean | false | 是否禁用 |
| clearable | boolean | false | 有值时是否显示清除按钮 |
| filterable | boolean | false | 是否可搜索,按选项文字过滤 |
| placeholder | string | '请选择' | 占位文本 |
| size | 'large' | 'default' | 'small' | 'default' | 尺寸 |
| collapseTags | boolean | true | 多选时是否把超出的标签折叠成 +N |
| maxCollapseTags | number | 3 | 折叠前最多显示几个标签 |
| max | number | - | 多选时最多可选几项,不传不限制 |
| selectAll | boolean | false | 多选时是否在下拉层顶部显示“全选”“清空”按钮 |
| tagType | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help' | 'primary' | 多选标签的类型 |
| validateEvent | boolean | true | 值变化和收起下拉层时是否触发所在表单项的校验 |
| remote | boolean | false | 是否远程搜索:展开后能输入,输入后调用 remoteMethod,不本地过滤 |
| remoteMethod | SelectRemoteMethod | - | 远程搜索函数,参数是搜索词。可以返回选项数组或 Promise |
| debounce | number | 300 | 远程搜索的防抖时间(毫秒),输入停止这么久后才调用 remoteMethod |
| loading | boolean | false | 是否加载中:下拉层显示转圈和 loadingText,不显示选项 |
| loadingText | string | '加载中' | 加载中显示的文字 |
| emptyText | string | '暂无数据' | 没有选项时显示的文字。写了 empty 插槽时以插槽为准 |
| noMatchText | string | - | 输入了搜索词、但没有匹配项时显示的文字,不传时用 emptyText |
| virtual | boolean | false | 是否虚拟滚动,只渲染看得见的选项。只对 options 生效 |
NsSelectOption Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label | string | - | 选项文字,必填。选中后显示在输入框里,搜索时也按它过滤 |
| value | string | number | - | 选项的值,必填 |
| disabled | boolean | false | 是否禁用这一项 |
| selected | boolean | - | 强制指定是否显示为选中。一般不用传,默认按 NsSelect 的绑定值判断 |
NsSelect Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string | number | (string | number)[] | undefined) | 值变化时触发,v-model 用 |
| change | (value: string | number | (string | number)[] | undefined) | 用户操作导致值变化时触发(选中、移除标签、全选、清空) |
| clear | - | 点清除按钮或下拉层里的“清空”按钮时触发 |
| visibleChange | (visible: boolean) | 下拉层展开或收起时触发 |
| removeTag | (value: string | number) | 多选时点标签上的叉移除一项时触发,参数是被移除项的 value |
| selectAll | (values: (string | number)[]) | 点“全选”按钮时触发,参数是全选后的值 |
NsSelect Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsSelectOption。不写时按 options 渲染 |
| empty | - | 没有可显示的选项时的提示,默认显示 emptyText 或 noMatchText |
NsSelectOption Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 选项的显示内容,不写时显示 label |
方法
通过 NsSelect 的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| focus | - | void | 让选择器获得焦点;可搜索并且已展开时聚焦到搜索框 |
| blur | - | void | 让选择器失去焦点 |
ref 上还有一个只读属性 filteredOptions,是 options 按当前搜索词过滤后的结果;远程搜索时不过滤,remoteMethod 返回了选项时是返回的选项。
类型
import type { SelectOption, SelectProps, SelectRemoteMethod, SelectSize } from '@ns/ui'
interface SelectOption {
label: string
value: string | number
disabled?: boolean
}
type SelectSize = 'large' | 'default' | 'small'
/**
* 远程搜索函数,参数是搜索词(删光搜索词时是空字符串)。
* 不返回时由你自己更新 options 和 loading;返回选项数组或 Promise 时,组件直接用返回的选项,
* Promise 没有结束前自动显示加载中,先发后到的旧结果会被丢弃
*/
type SelectRemoteMethod = (query: string) => void | SelectOption[] | Promise<SelectOption[] | void>
注意事项
- 选择器默认宽度是 100%,占满父容器。需要固定宽度时用
style或class设置。 - 没有选中项时用
undefined(多选用[])。单选绑定空字符串''时也按没选处理,显示占位文字;只有选项里确实有value为''的项(例如“全部”)时,''才算选中了它。清空之后值是undefined,不是''。 - 值在选项里找不到对应项时,先用选中过时记下的文字(远程搜索换了一批结果、异步加载换了选项时,已选项仍显示原来的文字);从来没在选项里出现过的值,直接显示这个值本身。远程搜索时绑定了初始值,要把这几项放进
options的初始值里,才能显示文字。 options和默认插槽同时写时只有插槽生效,但选中项的文字、全选会优先按options计算,所以两种写法不要混用。- 下拉层通过
Teleport渲染到body下,位置跟随选择器;下方放不下时改为向上弹出。给下拉层写样式时不要依赖选择器的父级选择器。 NsSelectOption只能放在NsSelect里,单独使用会抛错。filterable只在本地按label过滤;要按关键词请求接口时用remote和remoteMethod。remoteMethod返回过选项以后就一直用它返回的选项,options属性不再生效。- 远程搜索在输入时才调用,展开下拉层、收起时清空搜索词都不调用;收起时还在等防抖的那次调用会取消。要在展开时就显示一批默认选项,把它们放进
options,或者在visible-change里加载。 - 虚拟滚动只对
options生效,默认插槽里写的NsSelectOption照常全部渲染。虚拟滚动时每个选项的高度固定(large 40px、default 36px、small 28px),选项文字不换行,太长时省略;下拉层和选择器一样宽,不再随选项文字变宽。
优化点
- [x] 支持键盘上下键选择选项
- [ ] 支持选项分组(目前没有
NsSelectOptionGroup) - [x] 支持远程搜索和加载中状态
- [x] 支持虚拟滚动优化大数据渲染(
options属性) - [ ] 虚拟滚动支持默认插槽里写的选项、自定义选项内容
- [ ] 支持自定义选项的值字段名、文字字段名
- [ ] 支持自定义标签内容、输入框前缀
- [ ] 支持多选拖拽排序
- [ ] 支持选项描述信息展示
- [ ] 折叠的
+N标签支持悬停查看被折叠的项