Virtualized Select 虚拟化选择器 ​

TIP

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

TIP

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

背景 ​

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

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

基础用法 ​

最简单的单选用法

Please select

多选 ​

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

Please select

尺寸 ​

使用 size 调整组件尺寸,可选 large、small 等。

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

远程搜索 ​

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

将 filterable 与 remote 设为 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-tags、collapse-tags-tooltip、max-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 自定义 value、label 等字段键名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回车是否选中第一项匹配项;配合 filterable 或 remotebooleanfalse
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下拉失焦且 persistent 为 false 时是否销毁下拉 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-tags 与 collapse-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: relative 或 absolute;需要限制溢出时可加 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自定义标签;子参数包含 data、selectDisabled、deleteTagobject
loading自定义加载中内容—
label自定义标签文案;提供 indexobject

虚拟化选择器 方法 ​

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