Virtualized Select 虚拟化选择器 ​

基础用法 ​

适用广泛的基础选择器

请选择
请选择
请选择
请选择
请选择
请选择
请选择

多选 ​

最基础的多选选择器

请选择

隐藏多余标签的多选 ​

默认情况下选中值会以 Tag 的形式展现,你也可以设置collapse-tags属性将它们合并为一段文字。 您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

use collapse-tags

请选择

use collapse-tags-tooltip

请选择

use max-collapse-tags

请选择

可过滤的多选 ​

当选项太多时,你可以使用 filterable 选项来启用过滤功能来找到所需的选项。

请选择

面板内搜索 ​

开启 filterable-dropdown 后,搜索输入框放入下拉面板顶部,选择区只展示已选内容,点击选择框会展开面板并自动聚焦面板内搜索框。

需配合 filterable 使用,常用于 multiple 多选场景。与 remote 远程搜索同用时,点击选择框即展开面板(否则无法输入关键字),输入过程中面板保持展开、不随 loading / 防抖 / 无结果收起。

多选 + 面板内搜索

请选择

远程搜索 + 面板内搜索

请输入关键字

点击选择区触发 focus;选中项、按 Esc 或再点选择区收起面板不会触发 blur;点击组件外部才会触发 blur

禁用选择器本身或选项 ​

您可以选择禁用 Select 或者 Select 中的某个选项。

请选择
请选择

给选项进行分组 ​

只要数据格式满足特定要求,我们就可以按照自己的意愿为选项进行分组。

请选择

一键清除 ​

我们可以同时清除所有选定的选项。此设定也适用于单选。

请选择
请选择

自定义选项的渲染模板 ​

我们也可以通过自定义模板来渲染自己想要的选项内容。

请选择

自定义下拉菜单的头部 ​

您可以自定义下拉菜单的头部。

使用 slot 自定义内容

Select

自定义下拉菜单的底部 ​

您可以自定义下拉菜单的底部。

使用 slot 自定义内容

Select

创建临时选项 ​

创建并选中未包含在初始选项中的条目。

通过使用 allow-create 属性,用户可以通过输入框创建新项目。 为了使 allow-create 正常工作, filterable 的值必须为 true。

TIP

最好在使用 allow-create 属性的同时设置 :reserve-keyword="false"。

请选择
请选择

set reserve-keyword false

请选择

远程搜索 ​

输入关键字以从远程服务器中查找数据。

从服务器搜索数据,输入关键字进行查找。为了启用远程搜索,需要将filterable和remote设置为true,同时传入一个remote-method。 remote-method为一个Function,它会在输入值发生变化时调用,参数为当前输入值。

请输入关键字搜索

使用 value-key 键属性 ​

当 options.value 是一个对象时,您应该为它设置一个唯一的标识名称

TIP

在 之前,value-key既用作所选对象的唯一值,也用作options中表示值的对应 key。 现在 value-key 仅作为所选对象的唯一值使用,选项中值的 key 是 props.value.

自定义选项 ​

当您的 options 格式不同于默认格式 您可以通过 props 属性自定义 options

请选择

自定义标签 ​

您可以自定义标签。

将自定义的标签插入 w-select 的 slot 中即可。 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的值计算。 如果通过default slot自定义下拉框选项,选项中显示的文本可能与label的值不相等,从而导致计算错误。 在这种情况下,可以通过设置fit-input-width属性为一个数字来固定其宽度。

请选择
请选择
请选择

无障碍标记 aria-label ​

供自动化测试按原生节点定位:区域标记前缀取控件 aria-label 值 —— 选择区根节点为 <值>::选择区,下拉选项区 ul[role=listbox] 为 <值>::下拉选项区(未传 aria-label 时不输出区域标记);选项节点按 value 固定为 下拉选项::<value>,数据里的 'aria-label' 不生效。控件 aria-label 落到内部 input(自身值优先、form-item 回退),展开后仍唯一命中。必填统一用 aria-required(String),落在同一内部 input 上,"false" 原样保留。

选项按 value 固定渲染为 下拉选项::<value>;控件未写时回退 form-item。

过敏史
选择过敏史

控件自身的 aria-label 优先;必填用 aria-required 落到内部 input。

城市
选择城市

可视化用例见 自动化测试 · SelectV2。

API ​

Attributes ​

参数说明类型默认值
model-value / v-model选中项绑定值string / number / boolean / object / array—
options选项的数据源, value 的 key 和 label 可以通过 props自定义.array—
props配置选项,具体看下表object—
multiple是否多选booleanfalse
disabled是否禁用booleanfalse
value-key作为 value 唯一标识的键名,绑定值为对象类型时必填stringvalue
size组件大小enum''
clearable是否可以清空选项booleanfalse
clear-icon自定义清除图标string / objectCircleCloseFilled
collapse-tags多选时是否将选中值按文字的形式展示booleanfalse
multiple-limit多选时可被选择的最大数目。 当被设置为 0 时,可被选择的数目不设限。number0
name选择器的原生 name 属性string—
effecttooltip 主题,内置了 dark / light 两种enum / stringlighter
autocomplete自动完成选择输入stringoff
placeholder占位文字stringPlease select
filterable是否可筛选booleanfalse
filterable-dropdown是否把搜索输入框放入下拉面板中,需配合 filterable。开启后点击选择框直接展开面板并聚焦面板内搜索框;与 remote 远程搜索同用时,输入关键字过程中面板保持展开booleanfalse
filter-fields本地筛选时额外参与匹配的字段名,始终同时匹配 label;需配合 filterable。如 ['code', 'pinyin', 'alias', 'keyword']array—
allow-create是否允许创建新条目, 当使用该属性时,filterable必须设置为truebooleanfalse
filter-method自定义筛选方法Function—
loading是否从远程加载数据booleanfalse
loading-text从服务器加载数据时显示的文本,默认为“Loading”string—
reserve-keyword筛选时,是否在选择选项后保留关键字booleantrue
no-match-text搜索条件无匹配时显示的文字,也可以使用 empty 插槽设置,默认是 “No matching data'”string—
no-data-text当在没有数据时显示的文字,你同时可以使用 empty 插槽进行设置。stringNo Data
popper-class选择器下拉菜单的自定义类名string''
teleported是否使用 teleport。设置成 true则会被追加到 append-to 的位置booleantrue
append-to下拉框挂载到哪个 DOM 元素string—
persistent当下拉选择器未被激活并且persistent设置为false,选择器会被删除。booleantrue
popper-optionspopper.js parametersobjectrefer to popper.js doc{}
automatic-dropdown对于不可搜索的 Select,是否在输入框获得焦点后自动弹出选项菜单booleanfalse
fit-input-width无论下拉框的宽度是否与输入框相同,如果值为number,则宽度是固定的。boolean / numbertrue
show-overflow-tooltip单选时,选中的文本超出宽度出现省略号后,鼠标悬浮输入框是否以 tooltip 显示完整文本(多选不生效)booleantrue
height下拉菜单的高度,每一个选项为 34pxnumber274
item-height下拉项的高度number34
scrollbar-always-on是否总是展示滚动条booleanfalse
remote是否从服务器获取数据booleanfalse
remote-method当输入值发生变化时触发的函数。 它的参数就是当前的输入值。 当filterable设置为 true 时才会生效Function—
validate-event是否触发表单验证booleantrue
offset下拉面板偏移量number12
show-arrow下拉菜单的内容是否有箭头booleantrue
placement下拉框出现的位置enumbottom-start
fallback-placementsdropdown 可用的 positions 请查看popper.js 文档array['bottom-start', 'top-start', 'right', 'left']
collapse-tags-tooltip当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 只有当 collapse-tags 设置为 true 时才会生效。booleantrue
max-collapse-tags需要显示的 Tag 的最大数量。 只有当 collapse-tags 设置为 true 时才会生效。number1
tag-type标签类型enuminfo
tag-effect标签效果enumlight
aria-label a11y等价于原生 input aria-label 属性string—
aria-required a11y等价于原生 input aria-required 属性(String 声明,"false" 原样保留;未传时回退 form-item 必填状态)string—
empty-values组件的空值配置 参考 config-providerarray—
value-on-clear清空选项的值 参考 config-providerstring / number / boolean / Function—
tabindexinput 的 tabindexstring / number—
plain朴素的 Selectbooleanfalse

props ​

Attribute说明TypeDefault
value指定选项的值为选项对象的某个属性值stringvalue
label指定节点标签为节点对象的某个属性值stringlabel
options指定选项的子选项为选项对象的某个属性值stringoptions
disabled指定选项的禁用为选项对象的某个属性值stringdisabled

事件 ​

名称说明类型
change当所选值更改时触发,参数是当前选中的值Function
visible-change当下拉菜单出现/消失时触发器, 当它出现时, 参数将是 true, 否则将是 falseFunction
remove-tag当一个标签在多个模式下被移除时触发,参数将被移除标签值Function
clear可清空的单选模式下用户点击清空按钮时触发Function
blur当选择器的输入框失去焦点时触发Function
focus当选择器的输入框获得焦点时触发Function

Slots ​

名称详情
default自定义 Option 模板
header下拉列表顶部的内容
footer下拉列表底部的内容
empty自定义当选项为空时的内容
prefix输入框的前缀
tagselect 组件自定义标签内容
loadingselect 组件自定义 loading 内容
labelselect 组件自定义标签内容

Exposes ​

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

Copyright 2025 Winning Health 版权所有