Virtualized Select 虚拟化选择器
TIP
本组件仍在验证阶段,若发现问题请在 GitHub 反馈。
TIP
下拉层与触发器之间的小三角(Popper 箭头)默认不显示;需要时设置 show-arrow。
背景
在部分场景下,单个选择器可能加载数万行选项数据,将其全部渲染进 DOM 会给浏览器带来明显压力。
为改善性能与使用体验,我们提供了该虚拟化选择器组件。
基础用法
最简单的单选用法
多选
基础多选,以标签展示已选项。
尺寸
使用 size 调整组件尺寸,可选 large、small 等。
选项过多时折叠标签
使用 collapse-tags 将标签折叠为文字;collapse-tags-tooltip 可在悬停时查看全部标签。
use collapse-tags
use collapse-tags-tooltip
use max-collapse-tags
可筛选的多选
选项极多时可开启 filterable 便于查找。
禁用选择器或选项
可禁用整个选择器,或禁用单个选项。
分组
只要数据结构满足约定,即可按分组展示。
可清空
可一键清空已选(单选、多选均适用)。
自定义选项渲染
可自定义下拉列表中每一项的展示模板。
下拉头部
可自定义下拉面板顶部内容。
使用插槽自定义内容。
下拉底部
可自定义下拉面板底部内容。
使用插槽自定义内容。
创建选项
允许创建并选择当前选项中不存在的条目。
使用 allow-create 后用户可在输入框中键入新项;需同时开启 filterable。本例还演示 default-first-option:为 true 时可直接回车选中列表第一项。
TIP
配合 allow-create 使用时,建议设置 :reserve-keyword="false"。
set reserve-keyword false
远程搜索
输入关键字从服务端拉取数据。
将 filterable 与 remote 设为 true,并传入 remote-method,在输入变化时以当前关键字为参数调用。
default
use remote-show-suffix
value-key
当 options 中值为对象时,需设置 value-key 指定唯一键字段。
TIP
value-key 仅表示选中对象的唯一标识,选项取值字段请用 props.value 配置。
自定义选项字段
当 options 数据结构与默认不一致时,可通过 props 配置字段别名。
自定义标签
可自定义多选标签展示。
在 u-select-v2 的标签插槽中自定义;此方式下 collapse-tags、collapse-tags-tooltip、max-collapse-tags 不生效。
自定义加载
覆盖加载中展示内容。
loading icon1
loading icon2
空值配置
若需将空字符串视为有效值,可将 empty-values 设为 [null, undefined]。
若希望清空后绑定值为 null,将 value-on-clear 设为 null。
自定义标签文案
可自定义选项标签展示。
自定义宽度
下拉宽度默认按 label 估算;若通过默认插槽自定义选项展示,实际文本可能与 label 不一致导致宽度不准,此时可将 fit-input-width 设为数字以固定宽度。
虚拟化选择器 API
虚拟化选择器 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string / number / boolean / object / array | — |
| options | 选项数据,可通过 props 自定义 value、label 等字段键名 | array | — |
| props | 选项字段映射,见下表 | object | — |
| multiple | 是否多选 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| value-key | 绑定值为对象时的唯一键字段名 | string | value |
| size | 组件尺寸 | enum | '' |
| clearable | 是否可清空 | boolean | false |
| clear-icon | 自定义清空图标 | string / object | CircleClose |
| collapse-tags | 多选时是否折叠标签为文字 | boolean | false |
| multiple-limit | 多选最多可选数量,0 表示不限制 | number | 0 |
| id | 原生 input 的 id | string | — |
| name | 原生 input 的 name | string | — |
| effect | Tooltip 主题,内置 dark / light | enum / string | light |
| autocomplete | 原生 input 的 autocomplete | string | off |
| placeholder | 占位符,默认「Please select」 | string | Please select |
| filterable | 是否可筛选 | boolean | false |
| allow-create | 是否允许创建条目;需开启 filterable | boolean | false |
| filter-method | 自定义筛选函数,参数为当前输入;需开启 filterable | Function | — |
| loading | 是否远程加载中 | boolean | false |
| loading-text | 加载中文案,默认「Loading」 | string | — |
| reserve-keyword | 选中筛选项后是否保留输入关键字 | boolean | true |
| default-first-option | 回车是否选中第一项匹配项;配合 filterable 或 remote | boolean | false |
| no-match-text | 无匹配结果文案,可用 empty 插槽覆盖 | string | — |
| no-data-text | 无选项时文案,可用 empty 插槽覆盖 | string | No Data |
| popper-class | 下拉与标签 Tooltip 的自定义 class | string / object | '' |
| popper-style | 下拉与标签 Tooltip 的自定义 style | string / object | — |
| teleported | 下拉是否传送到 append-to 指定位置 | boolean | true |
| append-to | 下拉挂载目标元素 | CSSSelector / HTMLElement | — |
| persistent | 下拉失焦且 persistent 为 false 时是否销毁下拉 DOM | boolean | true |
| popper-options | popper.js 参数 | objectrefer to popper.js doc | {} |
| automatic-dropdown | 不可筛选时聚焦是否自动展开菜单 | boolean | false |
| fit-input-width | 下拉宽度是否与输入框一致;为数字时固定该宽度像素 | boolean / number | true |
| suffix-icon | 自定义后缀图标 | string / object | ArrowDown |
| height | 下拉面板高度(约每行 34px) | number | 274 |
| item-height | 单个选项行高 | number | 34 |
| estimated-option-height | 虚拟列表预估行高;未设置时使用固定 item-height;设置后启用动态行高并以该值为初始估计 | number | — |
| scrollbar-always-on | 是否始终显示滚动条 | boolean | false |
| remote | 是否远程搜索 | boolean | false |
| debounce | 远程搜索防抖毫秒数 | number | 300 |
| remote-method | 远程搜索函数,参数为当前输入;需开启 filterable | Function | — |
| remote-show-suffix | 远程搜索时是否显示后缀图标 | boolean | false |
| validate-event | 是否触发表单校验 | boolean | true |
| offset | 下拉偏移量 | number | 12 |
| show-arrow | 下拉是否显示箭头 | boolean | false |
| placement | 下拉出现位置 | enum | bottom-start |
| fallback-placements | 下拉备选方位,见 popper.js | array | ['bottom-start', 'top-start', 'right', 'left'] |
| collapse-tags-tooltip | 折叠标签悬停是否展示全部;需开启 collapse-tags | boolean | false |
| tag-tooltip | 折叠标签 Tooltip 配置;需同时开启 collapse-tags 与 collapse-tags-tooltip | object | {} |
| max-collapse-tags | 折叠时最多展示标签数;需开启 collapse-tags | number | 1 |
| tag-type | 标签类型 | enum | info |
| tag-effect | 标签效果 | enum | light |
| aria-label a11y | 原生 aria-label | string | — |
| empty-values | 视为空的取值,见 config-provider | array | — |
| value-on-clear | 清空后的绑定值,见 config-provider | string / number / boolean / Function | — |
| tabindex | 原生 input 的 tabindex | string / number | — |
props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 选项对象中作为取值的字段名 | string | value |
| label | 选项对象中作为展示文案的字段名 | string | label |
| options | 选项对象中表示子级的字段名 | string | options |
| disabled | 选项对象中表示禁用态的字段名 | string | disabled |
tag-tooltip
回退机制
tag-tooltip 内各属性优先级:
tag-tooltip对象内显式字段;- 从
u-select-v2继承的共用属性(如 effect、popper-class、popper-style、teleported、append-to、popper-options); - 底层
u-tooltip的默认值。
自定义挂载容器
通过 append-to 挂到自定义容器时,建议容器设置 position: relative 或 absolute;需要限制溢出时可加 overflow: hidden。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| append-to | Tooltip 内容挂载元素 | CSSSelector / HTMLElement | — |
| placement | Tooltip 方位 | enum | bottom |
| fallback-placements | Tooltip 备选方位 | array | ['bottom', 'top', 'right', 'left'] |
| effect | Tooltip 主题 | enum / string | — |
| popper-class | Tooltip 浮层 class | string | — |
| popper-style | Tooltip 浮层 style | string / object | — |
| transition | 动画名 | string | — |
| teleported | 是否传送 Tooltip 内容到 append-to | boolean | — |
| popper-options | popper.js 参数 | objectrefer to popper.js doc | — |
| show-after | 显示延迟(毫秒) | number | — |
| hide-after | 隐藏延迟(毫秒) | number | — |
| auto-close | 自动关闭延时(毫秒) | number | — |
| offset | Tooltip 偏移 | number | — |
虚拟化选择器 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 选中值变化,参数为当前值 | Function |
| visible-change | 下拉显隐变化,true 为展开 | Function |
| remove-tag | 多选移除标签,参数为被移除项值 | Function |
| clear | 点击清空时触发 | Function |
| blur | 输入框失焦 | Function |
| focus | 输入框聚焦 | Function |
虚拟化选择器 插槽
| 名称 | 说明 | 类型 |
|---|---|---|
| default | 选项渲染器 | — |
| header | 下拉顶部内容 | — |
| footer | 下拉底部内容 | — |
| empty | 无选项时内容 | — |
| prefix | 输入框前缀内容 | — |
| tag | 自定义标签;子参数包含 data、selectDisabled、deleteTag | object |
| loading | 自定义加载中内容 | — |
| label | 自定义标签文案;提供 index | object |
虚拟化选择器 方法
| 名称 | 说明 | 类型 |
|---|---|---|
| focus | 聚焦输入框 | Function |
| blur | 失焦并关闭下拉 | Function |
| selectedLabel | 当前选中项展示文案 | object |