虚拟化选择器

提示

此组件仍在测试中,如果您发现任何错误或问题,请在 GitHub 报告,以便我们修复。

背景

在某些场景下,一个选择器可能需要加载成千上万条数据。在 DOM 中渲染如此多的数据可能会给浏览器带来负担,从而导致性能问题。为了更好的用户和开发者体验,我们决定添加这个组件。

基础用法

最简单的选择器

多选

带标签的基础多选选择器

尺寸

当选中项过多时隐藏多余标签

您可以使用 collapse-tags 属性将标签折叠为一段文字。您可以使用 collapse-tags-tooltip 属性,在鼠标悬停于折叠文字上时查看它们。

可筛选的多选

当选项数量非常多时,您可以使用 filterable 选项来启用筛选功能,以便找出所需的选项。

禁用选择器和选择项

您可以选择禁用选择器本身或某个选项。

选项分组

只要数据满足特定模式,我们就可以按需对选项进行分组。

可清空的选择器

我们可以一次性清空所有已选中的选项,也适用于单选。

自定义选项渲染器

我们可以定义自己的模板来渲染弹出框中的选项。

下拉框的页眉 2.5.2

您可以自定义下拉列表的页眉。

您可以自定义下拉列表的页脚。

创建选项

创建并选择选择器选项中不包含的新项目

通过使用 allow-create 属性,用户可以通过在输入框中输入来创建新项目。请注意,要使 allow-create 生效,filterable 必须为 true。此示例还演示了 default-first-option。当此属性设置为 true 时,您可以通过按回车键选择当前选项列表中的第一个选项,而无需使用鼠标或箭头键导航。

提示

在使用 allow-create 时,最好设置 :reserve-keyword="false"

输入关键字,并从服务器获取数据。

使用 value-key 属性

options.value 是一个对象时,您应该为值设置一个唯一的标识键名。

提示

2.4.0 之前,value-key 既用作所选对象的唯一值,也用作 options 中值的别名。现在 value-key 仅用作所选对象的唯一值,而 options 中值的别名是 props.value

自定义选项的别名 2.4.2

当您的 options 格式与默认格式不同时,您可以通过 props 属性自定义 options 的别名。

自定义标签 2.5.0

您可以自定义标签。

自定义加载 2.5.2

覆盖加载内容。

空值 2.7.0

如果您想支持空字符串,请将 empty-values 设置为 [null, undefined]

如果要将清除值更改为 null,请将 value-on-clear 设置为 null

自定义标签 2.7.4

您可以自定义标签。

自定义宽度 2.9.2

下拉框的宽度默认是根据 label 的值计算的。如果您通过 default slot 自定义下拉框选项,很可能选项中显示的文本不等于 label 的值,导致计算错误。在这种情况下,您可以将 fit-input-width 属性设置为一个数字来固定其宽度。

API

属性

名称描述类型默认值
model-value / v-model绑定值string / number / boolean / object / array
options选项的数据,valuelabel 的键名可以通过 props 自定义array
props 2.4.2配置选项,请参见下表object
multiple是否多选booleanfalse
disabled是否禁用booleanfalse
value-key作为 value 唯一标识的键名,绑定值为对象类型时必填stringvalue
size组件尺寸枚举''
可清空是否可以清空选项booleanfalse
clear-icon自定义清除图标string / objectCircleClose
collapse-tags多选时是否将选中值按文字的形式展示booleanfalse
multiple-limit当 multiple 为 true 时,用户最多能选择的选项数。设置为 0 则无限制number0
id原生输入框 idstring
名称选择器输入框的 name 属性string
effecttooltip 主题,内置主题:`dark` / `light`enum / stringlight
自动补全选择器输入框的自动补全stringoff
占位符占位符string请选择
filterable是否可筛选booleanfalse
allow-create是否允许用户创建新项目, 需配合 `filterable` 使用booleanfalse
filter-method自定义筛选方法,第一个参数是当前输入值。要使用此方法,filterable 必须为 trueFunction
加载中是否正在从远程获取数据booleanfalse
loading-text远程加载时显示的文字,默认为 '加载中'string
reserve-keyword选择筛选选项后是否保留关键词。booleantrue
default-first-option在输入框按下回车,选择第一个匹配项。需配合 `filterable` 或 `remote` 使用booleanfalse
no-match-text搜索条件无匹配时显示的文字,也可以使用 `empty` 插槽,默认为 '无匹配数据'string
no-data-text当无选项时显示的文本,您也可以使用插槽 emptystring无数据
popper-class选择器下拉框和标签工具提示的自定义类名string / object''
popper-style 2.11.0选择器下拉框和标签工具提示的自定义样式string / object
teleported是否将下拉列表元素插入到 `append-to` 设置的元素中booleantrue
append-to 2.8.8下拉列表应该附加到哪个元素CSSSelector / HTMLElement
persistent当下拉列表不活动且 `persistent` 为 `false` 时,下拉列表将被销毁booleantrue
popper-optionspopper.js 参数object请参考 popper.js 文档{}
automatic-dropdown对于不可过滤的 Select 组件,此属性决定是否在输入框获得焦点后自动弹出选项菜单booleanfalse
fit-input-width 2.9.2下拉框的宽度是否与输入框相同,如果值为 number,则宽度是固定的boolean / numbertrue
suffix-icon 2.9.8自定义后缀图标组件string / objectArrowDown
高度下拉面板的高度,每个项目为 34pxnumber274
item-height下拉项的高度number34
scrollbar-always-on控制滚动条是否总是显示booleanfalse
remote是否从服务器搜索数据booleanfalse
debounce 2.11.7远程搜索时的防抖延迟,单位为毫秒number300
remote-method当输入值改变时调用的函数。 它的参数是当前的输入值。 若要使用此属性,`filterable` 必须为 trueFunction
remote-show-suffix 2.11.9远程搜索时显示后缀图标booleanfalse
validate-event是否触发表单验证booleantrue
offset 2.8.8下拉列表的偏移量number12
show-arrow 2.8.8下拉列表是否带有箭头booleantrue
placement下拉框出现的位置枚举下左
fallback-placements 2.5.6下拉框的可能位置列表 popper.jsarray['bottom-start', 'top-start', 'right', 'left']
collapse-tags-tooltip 2.3.0当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,`collapse-tags` 属性必须设定为 truebooleanfalse
max-collapse-tags 2.3.0最多显示的标签数量。要使用此属性,collapse-tags 必须为 truenumber1
tag-type 2.5.0标签类型枚举信息
tag-effect 2.7.7标签效果枚举light
aria-label 无障碍 2.5.0与原生输入框的 `aria-label` 相同string
empty-values 2.7.0组件的空值,参见 config-providerarray
value-on-clear 2.7.0清除返回值,参见 config-providerstring / number / boolean / Function
popper-append-to-body 已弃用是否将 popper 菜单附加到 body。如果 popper 的定位错误,可以尝试将此属性设置为 falsebooleanfalse
tabindex 2.9.0输入框的 tabindexstring / number

props

属性描述类型默认值
value指定节点对象的哪个键用作节点的值stringvalue
label指定节点对象的哪个键用作节点的标签stringlabel
options指定节点对象的哪个键用作节点的子节点stringoptions
disabled指定节点对象的哪个键用作节点的禁用stringdisabled

事件

名称描述类型
change当选中值改变时触发,参数为当前选中值Function
visible-change当下拉框出现/消失时触发,出现时参数为 true,反之为 falseFunction
remove-tag在多选模式下移除标签时触发,参数为移除的标签值Function
clear在可清空的 Select 组件上点击清除图标时触发Function
blur在 Input 失去焦点时触发Function
focus在 Input 获得焦点时触发Function

插槽

名称描述类型
default选项渲染器
header 2.5.2下拉列表顶部的内容
footer 2.5.2下拉列表底部的内容
empty当选项为空时的内容
prefix输入框的前缀内容
tag 2.5.0Select 标签内容,subTags 的 `data`、`selectDisabled` 和 `deleteTag` 在 2.10.3 中引入object
loading 2.5.2Select 加载中的内容
label 2.7.4作为选择器标签的内容。index2.11.2 中引入object

暴露

名称描述类型
focus使输入框获取焦点Function
blur使输入框失去焦点,并隐藏下拉框Function
selectedLabel 2.8.5获取当前选中的标签object

来源

组件样式文档

贡献者