Virtualized Select 虚拟化选择器

TIP

本组件仍在验证阶段,若发现问题请在 GitHub 反馈。

TIP

下拉层与触发器之间的小三角(Popper 箭头)默认不显示;需要时设置 show-arrow

背景

在部分场景下,单个选择器可能加载数万行选项数据,将其全部渲染进 DOM 会给浏览器带来明显压力。

为改善性能与使用体验,我们提供了该虚拟化选择器组件。

基础用法

最简单的单选用法

Please select

多选

基础多选,以标签展示已选项。

Please select

尺寸

使用 size 调整组件尺寸,可选 largesmall 等。

Please select
Please select
Please select

选项过多时折叠标签

使用 collapse-tags 将标签折叠为文字;collapse-tags-tooltip 可在悬停时查看全部标签。

use collapse-tags

Please select

use collapse-tags-tooltip

Please select

use max-collapse-tags

Please select

可筛选的多选

选项极多时可开启 filterable 便于查找。

Please select

禁用选择器或选项

可禁用整个选择器,或禁用单个选项。

Please select
Please select

分组

只要数据结构满足约定,即可按分组展示。

Please select

可清空

可一键清空已选(单选、多选均适用)。

Please select
Please select

自定义选项渲染

可自定义下拉列表中每一项的展示模板。

Please select

下拉头部

可自定义下拉面板顶部内容。

使用插槽自定义内容。

Select

下拉底部

可自定义下拉面板底部内容。

使用插槽自定义内容。

Select

创建选项

允许创建并选择当前选项中不存在的条目。

使用 allow-create 后用户可在输入框中键入新项;需同时开启 filterable。本例还演示 default-first-option:为 true 时可直接回车选中列表第一项。

TIP

配合 allow-create 使用时,建议设置 :reserve-keyword="false"

Please select
Please select

set reserve-keyword false

Please select

远程搜索

输入关键字从服务端拉取数据。

filterableremote 设为 true,并传入 remote-method,在输入变化时以当前关键字为参数调用。

default

Please enter a keyword

use remote-show-suffix

Please enter a keyword

value-key

options 中值为对象时,需设置 value-key 指定唯一键字段。

TIP

value-key 仅表示选中对象的唯一标识,选项取值字段请用 props.value 配置。

自定义选项字段

options 数据结构与默认不一致时,可通过 props 配置字段别名。

Please select

自定义标签

可自定义多选标签展示。

u-select-v2 的标签插槽中自定义;此方式下 collapse-tagscollapse-tags-tooltipmax-collapse-tags 不生效。

自定义加载

覆盖加载中展示内容。

loading icon1

Please enter a keyword

loading icon2

Please enter a keyword

空值配置

若需将空字符串视为有效值,可将 empty-values 设为 [null, undefined]

若希望清空后绑定值为 null,将 value-on-clear 设为 null

自定义标签文案

可自定义选项标签展示。

: Option 1

自定义宽度

下拉宽度默认按 label 估算;若通过默认插槽自定义选项展示,实际文本可能与 label 不一致导致宽度不准,此时可将 fit-input-width 设为数字以固定宽度。

Please select
Please select
Please select

虚拟化选择器 API

虚拟化选择器 属性

名称说明类型默认值
model-value / v-model绑定值string / number / boolean / object / array
options选项数据,可通过 props 自定义 valuelabel 等字段键名array
props选项字段映射,见下表object
multiple是否多选booleanfalse
disabled是否禁用booleanfalse
value-key绑定值为对象时的唯一键字段名stringvalue
size组件尺寸enum''
clearable是否可清空booleanfalse
clear-icon自定义清空图标string / objectCircleClose
collapse-tags多选时是否折叠标签为文字booleanfalse
multiple-limit多选最多可选数量,0 表示不限制number0
id原生 input 的 idstring
name原生 input 的 namestring
effectTooltip 主题,内置 dark / lightenum / stringlight
autocomplete原生 input 的 autocompletestringoff
placeholder占位符,默认「Please select」stringPlease select
filterable是否可筛选booleanfalse
allow-create是否允许创建条目;需开启 filterablebooleanfalse
filter-method自定义筛选函数,参数为当前输入;需开启 filterableFunction
loading是否远程加载中booleanfalse
loading-text加载中文案,默认「Loading」string
reserve-keyword选中筛选项后是否保留输入关键字booleantrue
default-first-option回车是否选中第一项匹配项;配合 filterableremotebooleanfalse
no-match-text无匹配结果文案,可用 empty 插槽覆盖string
no-data-text无选项时文案,可用 empty 插槽覆盖stringNo Data
popper-class下拉与标签 Tooltip 的自定义 classstring / object''
popper-style下拉与标签 Tooltip 的自定义 stylestring / object
teleported下拉是否传送到 append-to 指定位置booleantrue
append-to下拉挂载目标元素CSSSelector / HTMLElement
persistent下拉失焦且 persistentfalse 时是否销毁下拉 DOMbooleantrue
popper-optionspopper.js 参数objectrefer to popper.js doc{}
automatic-dropdown不可筛选时聚焦是否自动展开菜单booleanfalse
fit-input-width下拉宽度是否与输入框一致;为数字时固定该宽度像素boolean / numbertrue
suffix-icon自定义后缀图标string / objectArrowDown
height下拉面板高度(约每行 34px)number274
item-height单个选项行高number34
estimated-option-height虚拟列表预估行高;未设置时使用固定 item-height;设置后启用动态行高并以该值为初始估计number
scrollbar-always-on是否始终显示滚动条booleanfalse
remote是否远程搜索booleanfalse
debounce远程搜索防抖毫秒数number300
remote-method远程搜索函数,参数为当前输入;需开启 filterableFunction
remote-show-suffix远程搜索时是否显示后缀图标booleanfalse
validate-event是否触发表单校验booleantrue
offset下拉偏移量number12
show-arrow下拉是否显示箭头booleanfalse
placement下拉出现位置enumbottom-start
fallback-placements下拉备选方位,见 popper.jsarray['bottom-start', 'top-start', 'right', 'left']
collapse-tags-tooltip折叠标签悬停是否展示全部;需开启 collapse-tagsbooleanfalse
tag-tooltip折叠标签 Tooltip 配置;需同时开启 collapse-tagscollapse-tags-tooltipobject{}
max-collapse-tags折叠时最多展示标签数;需开启 collapse-tagsnumber1
tag-type标签类型enuminfo
tag-effect标签效果enumlight
aria-label a11y原生 aria-labelstring
empty-values视为空的取值,见 config-providerarray
value-on-clear清空后的绑定值,见 config-providerstring / number / boolean / Function
tabindex原生 input 的 tabindexstring / number

props

属性说明类型默认值
value选项对象中作为取值的字段名stringvalue
label选项对象中作为展示文案的字段名stringlabel
options选项对象中表示子级的字段名stringoptions
disabled选项对象中表示禁用态的字段名stringdisabled

tag-tooltip

回退机制

tag-tooltip 内各属性优先级:

  1. tag-tooltip 对象内显式字段;
  2. u-select-v2 继承的共用属性(如 effect、popper-class、popper-style、teleported、append-to、popper-options);
  3. 底层 u-tooltip 的默认值。

自定义挂载容器

通过 append-to 挂到自定义容器时,建议容器设置 position: relativeabsolute;需要限制溢出时可加 overflow: hidden

属性说明类型默认值
append-toTooltip 内容挂载元素CSSSelector / HTMLElement
placementTooltip 方位enumbottom
fallback-placementsTooltip 备选方位array['bottom', 'top', 'right', 'left']
effectTooltip 主题enum / string
popper-classTooltip 浮层 classstring
popper-styleTooltip 浮层 stylestring / object
transition动画名string
teleported是否传送 Tooltip 内容到 append-toboolean
popper-optionspopper.js 参数objectrefer to popper.js doc
show-after显示延迟(毫秒)number
hide-after隐藏延迟(毫秒)number
auto-close自动关闭延时(毫秒)number
offsetTooltip 偏移number

虚拟化选择器 事件

事件名说明类型
change选中值变化,参数为当前值Function
visible-change下拉显隐变化,true 为展开Function
remove-tag多选移除标签,参数为被移除项值Function
clear点击清空时触发Function
blur输入框失焦Function
focus输入框聚焦Function

虚拟化选择器 插槽

名称说明类型
default选项渲染器
header下拉顶部内容
footer下拉底部内容
empty无选项时内容
prefix输入框前缀内容
tag自定义标签;子参数包含 dataselectDisableddeleteTagobject
loading自定义加载中内容
label自定义标签文案;提供 indexobject

虚拟化选择器 方法

名称说明类型
focus聚焦输入框Function
blur失焦并关闭下拉Function
selectedLabel当前选中项展示文案object