Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
AutoComplete 自动完成
输入时在下方弹出建议列表,选中后把建议的文字填进输入框。用于搜索框、地址、商品名这类“可以自由输入,也可以从候选里选”的场景。只能从选项里选时用 NsSelect。
引入
import { NsAutoComplete } from '@ns/ui'
基础用法
用 v-model 绑定输入的文字,用 fetch-suggestions 传一个按输入返回建议的函数。默认聚焦时就请求一次建议,之后每次输入停顿 300 毫秒再请求。用上下键选择、回车选中、Esc 关闭,也可以用鼠标点选。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
placeholder="请输入餐厅名称"
/>
</template>
建议可以是字符串,也可以是对象 { value, label?, disabled? }。选中后输入框里填的是 label,没有 label 时是 value(见“指定显示字段”)。
异步获取建议
函数可以返回 Promise,请求期间输入框右侧显示加载图标。连续输入时只采用最后一次请求的结果,先发后到的旧结果直接丢弃;输入框失焦后结果才回来时不再弹出下拉。
下面用 setTimeout 模拟一个 800 毫秒的接口,实际项目里换成请求接口即可:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions, AutoCompleteSuggestion } from '@ns/ui'
const value = ref('')
const shops = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶', '茶百道', '喜茶']
// 实际项目里:const res = await fetch(`/api/shops?keyword=${query}`); return res.json()
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
new Promise<AutoCompleteSuggestion[]>((resolve) => {
setTimeout(() => {
resolve(shops.filter((name) => name.includes(query)).map((name) => ({ value: name })))
}, 800)
})
</script>
<template>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
placeholder="输入“茶”试试"
style="width: 280px"
/>
</template>
回调写法
也可以拿到结果后调用第二个参数 callback,这时函数不用返回任何东西。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query, callback) => {
setTimeout(() => callback(restaurants.filter((name) => name.includes(query))), 300)
}
</script>
<template>
<NsAutoComplete v-model="value" :fetch-suggestions="fetchSuggestions" style="width: 280px" />
</template>
静态数据
suggestions 可以直接传数组。组件不会按输入过滤这个数组,输入什么都显示全部;需要过滤时传 computed,或者传函数(写法和 fetch-suggestions 相同)。suggestions 和 fetch-suggestions 同时传时以 suggestions 为准。
左边直接传数组,输入什么都显示全部;右边传 computed,按输入过滤:
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsAutoComplete, NsSpace } from '@ns/ui'
const raw = ref('')
const value = ref('')
const fruits = ['苹果', '香蕉', '橙子', '葡萄']
const filtered = computed(() => fruits.filter((item) => item.includes(value.value)))
</script>
<template>
<NsSpace wrap>
<NsAutoComplete
v-model="raw"
:suggestions="fruits"
placeholder="数组:不过滤"
style="width: 240px"
/>
<NsAutoComplete
v-model="value"
:suggestions="filtered"
placeholder="computed:按输入过滤"
style="width: 240px"
/>
</NsSpace>
</template>
指定显示字段
建议对象没有 label 时,value-key 指定用哪个字段作为显示和填入的文字,默认是 'value'。建议对象可以带任意业务字段,在 select 事件和 suggestion 插槽里都能拿到。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions, AutoCompleteSuggestion } from '@ns/ui'
const value = ref('')
const code = ref<unknown>()
const cities = [
{ value: 110000, name: '北京' },
{ value: 310000, name: '上海' }
]
const fetchCities: AutoCompleteFetchSuggestions = (query) =>
cities.filter((city) => city.name.includes(query))
const handleSelect = (item: AutoCompleteSuggestion) => {
code.value = item.value
}
</script>
<template>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchCities"
value-key="name"
style="width: 280px"
@select="handleSelect"
/>
<p style="margin-top: 12px">
输入框里:{{ value || '(空)' }};城市编码:{{ code ?? '(未选择)' }}
</p>
</template>
自定义建议项
用 suggestion 插槽自定义每一项的内容,作用域参数是 { suggestion, index }。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('')
const shops = [
{ value: '新旺角茶餐厅', address: '长宁区淞虹路 661 号' },
{ value: '港式小厨', address: '普陀区真北路 988 号' },
{ value: '胖仙女', address: '闵行区虹莘路 3388 号' },
{ value: '贡茶', address: '徐汇区漕溪北路 331 号' }
]
const fetchShops: AutoCompleteFetchSuggestions = (query) =>
shops.filter((shop) => shop.value.includes(query))
</script>
<template>
<NsAutoComplete v-model="value" :fetch-suggestions="fetchShops">
<template #suggestion="{ suggestion }">
<div>{{ suggestion.label }}</div>
<div class="address">{{ suggestion.address }}</div>
</template>
</NsAutoComplete>
</template>
<style scoped>
.address {
font-size: 12px;
color: var(--ns-text-color-secondary);
}
</style>
没有结果
写了 empty 插槽时,没有建议也会打开下拉,显示插槽内容;不写时没有建议就不弹出。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsAutoComplete v-model="value" :fetch-suggestions="fetchSuggestions">
<template #empty>
<div style="padding: 8px 12px">没有找到相关餐厅</div>
</template>
</NsAutoComplete>
</template>
禁用建议项
建议对象设 disabled: true 后显示成灰色,上下键会跳过它,点击和回车都选不中。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('')
const fetchSuggestions: AutoCompleteFetchSuggestions = () => [
{ value: '新旺角茶餐厅' },
{ value: '港式小厨', label: '港式小厨(已打烊)', disabled: true },
{ value: '胖仙女' }
]
</script>
<template>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
placeholder="聚焦后用上下键试试"
style="width: 280px"
/>
</template>
聚焦时不弹出
trigger-on-focus 默认是 true,聚焦时立即用当前内容(可能是空字符串)请求一次建议。设为 false 后,只有输入内容时才请求。点一下两个输入框对比:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsSpace } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('')
const other = ref('')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsSpace wrap>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
placeholder="聚焦就弹出(true)"
style="width: 240px"
/>
<NsAutoComplete
v-model="other"
:fetch-suggestions="fetchSuggestions"
:trigger-on-focus="false"
placeholder="输入后才弹出(false)"
style="width: 240px"
/>
</NsSpace>
</template>
防抖时间
debounce 是输入后等多少毫秒再请求建议,默认 300。聚焦时的请求不等待。下面快速输入几个字,对比请求次数:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsSpace } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const fast = ref('')
const slow = ref('')
const fastCount = ref(0)
const slowCount = ref(0)
const words = ['apple', 'apricot', 'banana', 'blueberry', 'cherry']
const fetchFast: AutoCompleteFetchSuggestions = (query) => {
fastCount.value += 1
return words.filter((word) => word.includes(query))
}
const fetchSlow: AutoCompleteFetchSuggestions = (query) => {
slowCount.value += 1
return words.filter((word) => word.includes(query))
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsAutoComplete
v-model="fast"
:fetch-suggestions="fetchFast"
:debounce="0"
:trigger-on-focus="false"
placeholder="debounce 0"
style="width: 200px"
/>
<span>已请求 {{ fastCount }} 次</span>
</NsSpace>
<NsSpace wrap>
<NsAutoComplete
v-model="slow"
:fetch-suggestions="fetchSlow"
:debounce="1000"
:trigger-on-focus="false"
placeholder="debounce 1000"
style="width: 200px"
/>
<span>已请求 {{ slowCount }} 次</span>
</NsSpace>
</NsSpace>
</template>
没有匹配时回车也选中
select-when-unmatched 为 true 时,没有高亮的建议(没有结果,或者没用上下键选)也能按回车触发 select,参数是 { value: 当前输入, label: 当前输入 }。适合“搜索框回车直接搜”的场景。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsMessage } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const keyword = ref('')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
const search = (text?: string) => {
NsMessage(`搜索“${text}”`)
}
</script>
<template>
<NsAutoComplete
v-model="keyword"
:fetch-suggestions="fetchSuggestions"
select-when-unmatched
@select="(item) => search(item.label)"
/>
</template>
可清空
clearable 为 true 且有内容时,右侧显示清空按钮(<button>,读屏读作“清空”,可以用 Tab 聚焦后按回车或空格)。点它会把值清成 '',依次触发 update:modelValue、input、change、clear,关闭下拉并让输入框重新获得焦点。和 NsInput 一致。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('港式小厨')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsAutoComplete v-model="value" :fetch-suggestions="fetchSuggestions" clearable />
</template>
前后缀图标
prefix-icon、suffix-icon 传图标名。加载中或显示清空图标时,后缀图标不显示:下面第三个输入框有内容时显示清空按钮,删光内容后才显示后缀图标。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsSpace } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const prefix = ref('')
const suffix = ref('')
const both = ref('港式小厨')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsSpace wrap>
<NsAutoComplete
v-model="prefix"
:fetch-suggestions="fetchSuggestions"
prefix-icon="search"
placeholder="前缀图标"
style="width: 200px"
/>
<NsAutoComplete
v-model="suffix"
:fetch-suggestions="fetchSuggestions"
suffix-icon="location"
placeholder="后缀图标"
style="width: 200px"
/>
<NsAutoComplete
v-model="both"
:fetch-suggestions="fetchSuggestions"
prefix-icon="search"
suffix-icon="location"
clearable
placeholder="前后缀和清空"
style="width: 200px"
/>
</NsSpace>
</template>
加载状态
不传 loading 时,组件在请求期间自动显示加载图标;传了 loading 就以它为准,由你自己控制。hide-loading 为 true 时始终不显示加载图标。
下面三个输入框的请求都要 1 秒:第一个自动显示加载图标;第二个用 loading 控制,勾选后一直显示;第三个加了 hide-loading,请求期间也不显示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsCheckbox, NsSpace } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const auto = ref('')
const manual = ref('')
const hidden = ref('')
const loading = ref(false)
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
// 模拟 1 秒的请求
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
new Promise<string[]>((resolve) => {
setTimeout(() => resolve(restaurants.filter((name) => name.includes(query))), 1000)
})
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsAutoComplete
v-model="auto"
:fetch-suggestions="fetchSuggestions"
placeholder="自动显示"
style="width: 200px"
/>
<NsAutoComplete
v-model="manual"
:fetch-suggestions="fetchSuggestions"
:loading="loading"
placeholder="由 loading 控制"
style="width: 200px"
/>
<NsAutoComplete
v-model="hidden"
:fetch-suggestions="fetchSuggestions"
hide-loading
placeholder="hide-loading"
style="width: 200px"
/>
</NsSpace>
<NsCheckbox v-model="loading">第二个显示加载中(loading)</NsCheckbox>
</NsSpace>
</template>
弹出位置
placement 指定下拉层的位置,默认 'bottom-start',共 12 个方向。放不下时自动翻到另一侧,下拉层宽度至少和输入框一样。点一下下面的输入框,看下拉层出现在哪:
<script setup lang="ts">
import { reactive } from 'vue'
import { NsAutoComplete, NsSpace } from '@ns/ui'
const values = reactive<Record<string, string>>({})
const suggestions = ['新旺角茶餐厅', '港式小厨', '贡茶']
</script>
<template>
<div class="placements">
<div class="placements__row placements__row--center">
<NsAutoComplete
v-for="item in ['top-start', 'top', 'top-end']"
:key="item"
v-model="values[item]"
:suggestions="suggestions"
:placement="item"
:placeholder="item"
style="width: 140px"
/>
</div>
<div class="placements__row placements__row--between">
<NsSpace direction="vertical" align="start">
<NsAutoComplete
v-for="item in ['left-start', 'left', 'left-end']"
:key="item"
v-model="values[item]"
:suggestions="suggestions"
:placement="item"
:placeholder="item"
style="width: 140px"
/>
</NsSpace>
<NsSpace direction="vertical" align="end">
<NsAutoComplete
v-for="item in ['right-start', 'right', 'right-end']"
:key="item"
v-model="values[item]"
:suggestions="suggestions"
:placement="item"
:placeholder="item"
style="width: 140px"
/>
</NsSpace>
</div>
<div class="placements__row placements__row--center">
<NsAutoComplete
v-for="item in ['bottom-start', 'bottom', 'bottom-end']"
:key="item"
v-model="values[item]"
:suggestions="suggestions"
:placement="item"
:placeholder="item"
style="width: 140px"
/>
</div>
</div>
</template>
<style scoped>
.placements {
max-width: 560px;
margin: 0 auto;
}
.placements__row {
display: flex;
gap: var(--ns-spacing-2);
}
.placements__row--center {
justify-content: center;
}
.placements__row--between {
justify-content: space-between;
margin: var(--ns-spacing-3) 0;
}
</style>
禁用和只读
disabled 禁用后不能输入;readonly 只读时可以聚焦、复制,但不能输入,聚焦时也不请求建议。两种状态下都不显示清空按钮。在 NsForm 里时跟随表单的禁用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsSpace } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const empty = ref('')
const value = ref('新旺角茶餐厅')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsAutoComplete v-model="empty" disabled placeholder="禁用" style="width: 200px" />
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
disabled
clearable
prefix-icon="search"
style="width: 200px"
/>
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsAutoComplete v-model="empty" readonly placeholder="只读" style="width: 200px" />
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
readonly
clearable
prefix-icon="search"
style="width: 200px"
/>
</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>
尺寸
size 可选 large、default、small:输入框高度分别是 40、32、24px,字号 16、14、12px,圆角 8、6、4px,图标 18、16、14px,和同尺寸的 NsInput 一致;下拉面板的选项跟着变,行高 40、36、28px,字号 16、14、12px,左右内边距 16、12、8px(和输入框里的文字左边对齐)。在 NsForm 里时跟随表单的尺寸。
每一行是一种尺寸,依次是带前缀图标和清空按钮的自动完成、同尺寸的输入框和按钮:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsButton, NsInput, NsSpace } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('新旺角茶餐厅')
const text = ref('')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
size="large"
prefix-icon="search"
clearable
style="width: 220px"
/>
<NsInput v-model="text" size="large" placeholder="输入框" style="width: 160px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
prefix-icon="search"
clearable
style="width: 220px"
/>
<NsInput v-model="text" placeholder="输入框" style="width: 160px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
size="small"
prefix-icon="search"
clearable
style="width: 220px"
/>
<NsInput v-model="text" size="small" placeholder="输入框" style="width: 160px" />
<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>
输入长度
maxlength 限制最多能输入几个字,选中建议填入的文字不受它限制;minlength 是原生属性,只在原生表单校验时起作用。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const value = ref('')
const codes = ['SH600000', 'SH600036', 'SZ000001', 'SZ000002']
const fetchCodes: AutoCompleteFetchSuggestions = (query) =>
codes.filter((code) => code.includes(query.toUpperCase()))
</script>
<template>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchCodes"
:maxlength="8"
placeholder="最多输入 8 个字符"
style="width: 240px"
/>
</template>
事件
输入时触发 input(和 update:modelValue 同时);选中建议时依次触发 input、change、select;点清空按钮时依次触发 input、change、clear;输入框获得、失去焦点时触发 focus、blur。最近的事件显示在下方:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsSpace } from '@ns/ui'
import type { AutoCompleteFetchSuggestions, AutoCompleteSuggestion } from '@ns/ui'
const value = ref('')
const logs = ref<string[]>([])
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
const log = (text: string) => {
logs.value = [text, ...logs.value].slice(0, 6)
}
const onInput = (val: string) => log(`input:${val}`)
const onChange = (val: string) => log(`change:${val}`)
const onSelect = (item: AutoCompleteSuggestion) => log(`select:${item.label}`)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsAutoComplete
v-model="value"
:fetch-suggestions="fetchSuggestions"
clearable
style="max-width: 320px"
@input="onInput"
@change="onChange"
@select="onSelect"
@clear="log('clear')"
@focus="log('focus')"
@blur="log('blur')"
/>
<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();inputRef 是内部的 <input> 元素,可以直接调用它的原生方法,例如 select() 选中全部文字。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAutoComplete, NsButton, NsSpace } from '@ns/ui'
import type { AutoCompleteExpose, AutoCompleteFetchSuggestions } from '@ns/ui'
const autoRef = ref<AutoCompleteExpose>()
const value = ref('港式小厨')
const restaurants = ['新旺角茶餐厅', '港式小厨', '胖仙女', '贡茶']
const fetchSuggestions: AutoCompleteFetchSuggestions = (query) =>
restaurants.filter((name) => name.includes(query))
</script>
<template>
<NsSpace wrap>
<NsAutoComplete
ref="autoRef"
v-model="value"
:fetch-suggestions="fetchSuggestions"
:trigger-on-focus="false"
style="width: 240px"
/>
<NsButton @click="autoRef?.focus()">聚焦(focus)</NsButton>
<NsButton @click="autoRef?.blur()">失焦(blur)</NsButton>
<NsButton @click="autoRef?.inputRef?.select()">选中文字(inputRef.select)</NsButton>
</NsSpace>
</template>
在表单里使用
放在 NsFormItem 里时,值变化(输入、选中建议、清空)触发 change 规则,输入框失焦触发 blur 规则;点建议时输入框不会失焦。表单项的 label 会通过 for 关联到输入框。不需要校验时设 :validate-event="false"。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsAutoComplete, NsForm, NsFormItem } from '@ns/ui'
import type { AutoCompleteFetchSuggestions } from '@ns/ui'
const model = reactive({ city: '' })
const cities = ['北京', '上海', '广州', '深圳', '杭州']
const fetchCities: AutoCompleteFetchSuggestions = (query) =>
cities.filter((city) => city.includes(query))
</script>
<template>
<NsForm
:model="model"
:rules="{ city: [{ required: true, message: '请填写城市', trigger: 'blur' }] }"
>
<NsFormItem label="城市" prop="city">
<NsAutoComplete v-model="model.city" :fetch-suggestions="fetchCities" />
</NsFormItem>
</NsForm>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | '' | 绑定值,支持 v-model |
| placeholder | string | '请输入' | 占位文字 |
| disabled | boolean | false | 是否禁用 |
| readonly | boolean | false | 是否只读。只读时聚焦不请求建议 |
| clearable | boolean | false | 有内容时是否显示清空图标 |
| size | 'large' | 'default' | 'small' | - | 尺寸。不传时跟随表单,不在表单里时是 'default' |
| fetchSuggestions | AutoCompleteFetchSuggestions | - | 获取建议的函数,可以返回数组、返回 Promise 或调用 callback |
| suggestions | AutoCompleteSuggestionsInput | - | 建议数据:数组、单个对象,或和 fetchSuggestions 一样的函数。优先于 fetchSuggestions |
| loading | boolean | undefined | 是否显示加载图标。不传时组件在请求期间自动显示 |
| valueKey | string | 'value' | 建议对象没有 label 时,用哪个字段作为显示和填入的文字 |
| placement | PopperPlacement | 'bottom-start' | 下拉层的位置,放不下时自动翻到另一侧 |
| debounce | number | 300 | 输入后等多少毫秒再请求建议。聚焦时的请求不等待 |
| triggerOnFocus | boolean | true | 聚焦时是否立即请求建议 |
| selectWhenUnmatched | boolean | false | 没有高亮的建议时,按回车是否也触发 select |
| hideLoading | boolean | false | 是否隐藏加载图标 |
| maxlength | number | - | 最大输入长度 |
| minlength | number | - | 最小输入长度(原生属性) |
| prefixIcon | string | - | 前缀图标名 |
| suffixIcon | string | - | 后缀图标名。加载中、显示清空图标时不显示 |
| validateEvent | boolean | true | 值变化和失焦时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string) | 输入、选中建议、清空时触发。输入法组合期间不触发,上屏后触发一次 |
| input | (value: string) | 和 update:modelValue 同时触发 |
| change | (value: string) | 选中建议、点清空按钮时触发;也是原生 change,内容有变化后失焦或按回车时触发 |
| focus | (event: FocusEvent) | 输入框获得焦点时触发 |
| blur | (event: FocusEvent) | 输入框失去焦点时触发。点建议、点下拉层不会让输入框失焦 |
| clear | - | 点清空按钮后触发 |
| select | (suggestion: AutoCompleteSuggestion) | 选中建议时触发,参数是整个建议对象(带上了 label);selectWhenUnmatched 时见上面的说明 |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| suggestion | { suggestion: AutoCompleteSuggestion; index: number } | 自定义每一项建议的内容,默认显示 suggestion.label |
| empty | - | 没有建议时显示的内容。写了它,没有结果时也会打开下拉 |
方法
| 名称 | 类型 | 说明 |
|---|---|---|
| focus | () => void | 让输入框获得焦点 |
| blur | () => void | 让输入框失去焦点 |
| inputRef | HTMLInputElement | 内部的 input 元素 |
类型
import type {
AutoCompleteProps,
AutoCompleteEmits,
AutoCompleteExpose,
AutoCompleteSize,
AutoCompleteSuggestion,
AutoCompleteFetchSuggestions,
AutoCompleteFetchSuggestionsResult,
AutoCompleteSuggestionsInput,
PopperPlacement
} from '@ns/ui'
type AutoCompleteSize = 'large' | 'default' | 'small'
interface AutoCompleteSuggestion {
value: string | number | object
/** 显示的文字;不写时显示 item[valueKey] */
label?: string
disabled?: boolean
/** 可以带任意业务字段 */
[key: string]: unknown
}
type AutoCompleteFetchSuggestionsResult =
| string[]
| AutoCompleteSuggestion[]
| Promise<string[] | AutoCompleteSuggestion[]>
/** 三种写法任选其一:直接返回数组、返回 Promise、调用 callback */
type AutoCompleteFetchSuggestions = (
query: string,
callback: (suggestions: string[] | AutoCompleteSuggestion[]) => void
) => AutoCompleteFetchSuggestionsResult | void
type AutoCompleteSuggestionsInput =
| string[]
| AutoCompleteSuggestion[]
| AutoCompleteSuggestion
| AutoCompleteFetchSuggestions
type PopperPlacement =
| 'top'
| 'top-start'
| 'top-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
| 'right'
| 'right-start'
| 'right-end'
interface AutoCompleteExpose {
focus: () => void
blur: () => void
inputRef: HTMLInputElement | undefined
}
AutoCompleteProps、AutoCompleteEmits 和上面 Props、Events 表一一对应。
注意事项
- 传静态数组时组件不过滤,需要按输入过滤时用
computed或函数自己过滤。 suggestions和fetchSuggestions同时传时以suggestions为准;传单个对象时当作只有一项的数组。- 选中建议后
v-model拿到的是建议的文字(label,或valueKey指定的字段),不是value;要拿value等其他字段,在select事件里取。 - 输入框被清空(手动删光)时不请求建议,直接关闭下拉。
- 获取建议的函数抛错或 Promise 被拒绝时,在控制台打印错误并关闭下拉。
- 输入框失焦约 200 毫秒后关闭下拉;点页面其他地方、按 Esc 也会关闭。
placement挂载后再修改也会生效,下次打开下拉层时按新的位置显示。- 组件上写的
class、style留在外层容器上,其余属性和监听都透传到内部的<input>:name、id、autofocus、tabindex、aria-label、data-*,以及@keydown、@paste等组件没有声明的事件,和NsInput一致。输入框固定带autocomplete="off",不会弹出浏览器自己的历史记录。 - 输入框带
role="combobox"、aria-expanded、aria-activedescendant,建议列表是listbox,每项是option。
优化点
- [ ] 支持分组建议
- [ ] 输入框旁增加下拉按钮,点击时用空字符串或当前内容请求建议
- [ ] 支持强制匹配:失焦时输入不在建议里就清空,保证绑定值总是建议之一
- [ ] 支持多选,绑定值为数组
- [ ] 支持浮动标签(不显示、浮在边框外、边框内、边框线上)
- [ ] 支持
fluid:宽度撑满父容器 - [ ] 支持
invalid状态,方便接入其他表单校验库