虚拟化选择器
提示
这个组件仍在测试中,如果你发现了任何bug或者问题,请在 GitHub 报告给我们修复。
背景
在某些场景下,一个选择器可能需要加载数万条数据。在 DOM 中渲染这么多数据可能会给浏览器带来负担,从而导致性能问题。为了获得更好的用户和开发体验,我们决定添加这个组件。
基础用法
最简单的选择器
多选
带标签的基本多选选择器
尺寸
添加 size
属性以更改 Select-V2 的大小。除了默认大小外,还有两个其他选项:large
、small
。
当选中项过多时隐藏多余标签
您可以使用 collapse-tags
属性将标签折叠成文本。您可以使用 collapse-tags-tooltip
属性在鼠标悬停在折叠文本上时查看它们。
可筛选多选
当选项过多时,您可以使用 filterable
选项启用筛选功能,以找出所需选项
禁用选择器和选择选项
您可以选择禁用选择器本身或选项。
选项分组
只要数据满足模式,我们就可以根据需要对选项进行分组。
可清除选择器
我们可以一次性清除所有选中的选项,也适用于单选。
自定义选项渲染器
我们可以定义自己的模板来渲染弹出窗口中的选项。
下拉菜单头部 2.5.2
您可以自定义下拉列表的页眉。
使用插槽来自定义内容。
下拉菜单底部 2.5.2
您可以自定义下拉列表的页脚。
使用插槽来自定义内容。
创建选项
创建并选择选择器选项中不包含的新项目
通过使用 allow-create
属性,用户可以通过在输入框中键入来创建新项目。请注意,要使 allow-create
起作用,filterable
必须为 true
。此示例还演示了 default-first-option
。当此属性设置为 true
时,您可以通过按回车键选择当前选项列表中的第一个选项,而无需使用鼠标或箭头键导航。
提示
当使用 allow-create
时,最好设置 :reserve-keyword="false"
远程搜索
输入关键字,并从服务器获取数据。
将 filterable
和 remote
的值设置为 true
以启用远程搜索,并且您应该传递 remote-method
。remote-method
是一个在输入值改变时调用的 Function
,其参数是当前的输入值。
使用 value-key 属性
当 options.value
是一个对象时,您应该为值设置一个唯一的标识键名
提示
在 2.4.0 之前,value-key
既用作所选对象的唯一值,也用作 options
中值的别名。现在 value-key
仅用作所选对象的唯一值,而 options 中值的别名是 props.value
。
自定义选项的别名 2.4.2
当您的 options
格式与默认格式不同时,您可以通过 props
属性自定义 options
的别名
自定义标签 2.5.0
您可以自定义标签。
将自定义标签插入到 el-select
的插槽中。 collapse-tags
、collapse-tags-tooltip
、max-collapse-tags
将不起作用。
自定义加载 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 | 绑定值 | 字符串 / 数字 / 布尔值 / 对象 / 数组 | — |
options | 选项的数据,value 和 label 的键可以通过 props 自定义 | array | — |
props 2.4.2 | 配置选项,请参见下表 | object | — |
multiple | 是否多选 | boolean | false |
disabled | 是否禁用 | boolean | false |
value-key | 作为 value 唯一标识的键名,绑定值为对象类型时必填 | string | value |
size | 组件大小 | 枚举 | '' |
可清空 | 是否可以清空选项 | boolean | false |
clear-icon | 自定义清除图标 | string / object | CircleClose |
collapse-tags | 多选时是否将选中值按文字的形式展示 | boolean | false |
multiple-limit | 当 multiple 为 true 时用户可以选择的最大选项数。设置为 0 时无限制 | number | 0 |
id | 原生输入框 id | string | — |
名称 | 选择器输入框的 name 属性 | string | — |
effect | tooltip 主题,内置主题:`dark` / `light` | enum / string | light |
自动补全 | 选择输入框的自动完成 | string | off |
占位符 | 占位符 | string | 请选择 |
filterable | 是否可筛选 | boolean | false |
allow-create | 是否允许用户创建新项目, 需配合 `filterable` 使用 | boolean | false |
filter-method | 自定义筛选方法,第一个参数是当前输入值。要使用此功能,filterable 必须为 true 方法 | Function | — |
加载中 | 是否正在从远程获取数据 | boolean | false |
loading-text | 远程加载时显示的文字,默认为 '加载中' | string | — |
reserve-keyword | 选择筛选选项后是否保留关键字。 | boolean | true |
default-first-option | 在输入框按下回车,选择第一个匹配项。需配合 `filterable` 或 `remote` 使用 | boolean | false |
no-match-text | 搜索条件无匹配时显示的文字,也可以使用 `empty` 插槽,默认为 '无匹配数据' | string | — |
no-data-text | 无选项时显示的文本,您也可以使用 slot empty | string | 无数据 |
popper-class | Select 下拉框的自定义类名 | string / object | '' |
popper-style 2.11.0 | 为 Select 的下拉列表自定义样式 | string / object | — |
teleported | 是否将下拉列表元素插入到 `append-to` 设置的元素中 | boolean | true |
append-to 2.8.8 | 下拉列表应该附加到哪个元素 | CSSSelector / HTMLElement | — |
persistent | 当下拉列表不活动且 `persistent` 为 `false` 时,下拉列表将被销毁 | boolean | true |
popper-options | popper.js 参数 | 对象 参考 popper.js 文档 | {} |
automatic-dropdown | 对于不可过滤的 Select 组件,此属性决定是否在输入框获得焦点后自动弹出选项菜单 | boolean | false |
fit-input-width 2.9.2 | 下拉框的宽度是否与输入框相同,如果值为 number ,则宽度是固定的 | 布尔值 / 数字 | true |
suffix-icon 2.9.8 | 自定义后缀图标组件 | string / object | ArrowDown |
高度 | 下拉面板的高度,每个项目 34px | number | 274 |
item-height | 下拉项的高度 | number | 34 |
scrollbar-always-on | 控制滚动条是否总是显示 | boolean | false |
remote | 是否从服务器搜索数据 | boolean | false |
remote-method | 当输入值改变时调用的函数。 它的参数是当前的输入值。 若要使用此属性,`filterable` 必须为 true | Function | — |
validate-event | 是否触发表单验证 | boolean | true |
offset 2.8.8 | 下拉列表的偏移量 | number | 12 |
show-arrow 2.8.8 | 下拉列表是否带有箭头 | boolean | true |
placement | 下拉框出现的位置 | 枚举 | 下左 |
fallback-placements 2.5.6 | 下拉框的可能位置列表 popper.js | array | ['bottom-start', 'top-start', 'right', 'left'] |
collapse-tags-tooltip 2.3.0 | 当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,`collapse-tags` 属性必须设定为 true | boolean | false |
max-collapse-tags 2.3.0 | 要显示的最大标签数。要使用此功能,collapse-tags 必须为 true | number | 1 |
tag-type 2.5.0 | 标签类型 | 枚举 | 信息 |
tag-effect 2.7.7 | 标签效果 | 枚举 | light |
aria-label a11y 2.5.0 | 与原生输入框的 `aria-label` 相同 | string | — |
empty-values 2.7.0 | 组件的空值,参见 config-provider | array | — |
value-on-clear 2.7.0 | 清除后的返回值,参见 config-provider | 字符串 / 数字 / 布尔值 / 函数 | — |
popper-append-to-body 已弃用 | 是否将 popper 菜单附加到 body。如果 popper 的定位错误,可以尝试将此属性设置为 false | boolean | false |
tabindex 2.9.0 | 输入框的 tabindex | string / number | — |
props
属性 | 描述 | 类型 | 默认值 |
---|---|---|---|
value | 指定节点对象的哪个键用作节点的值 | string | value |
label | 指定节点对象的哪个键用作节点的标签 | string | label |
options | 指定节点对象的哪个键用作节点的子节点 | string | options |
disabled | 指定节点对象的哪个键用作节点的禁用 | string | disabled |
事件
名称 | 描述 | 类型 |
---|---|---|
change | 当选中值改变时触发,参数是当前选中的值 | Function |
visible-change | 当下拉框出现/消失时触发,出现时参数为 true,否则为 false | Function |
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.0 | Select 标签内容,subTags 的 `data`、`selectDisabled` 和 `deleteTag` 在 2.10.3 中引入 | object |
loading 2.5.2 | Select 加载中的内容 | — |
label 2.7.4 | Select 标签内容 | — |
暴露
名称 | 描述 | 类型 |
---|---|---|
focus | 使输入框获取焦点 | Function |
blur | 使输入框失去焦点,并隐藏下拉框 | Function |
selectedLabel 2.8.5 | 获取当前选中的标签 | object |