Select 选择器

当选项过多时,使用下拉菜单展示并选择内容。

WARNING

如果你发现 v-model 绑定的值失效,请检查是否开启了兼容模式(compat)。在兼容模式下,需要将 v-model 改写为 v-model:model-value

TIP

目前 w-select 的默认宽度更改为 100% 当使用内联形式时,宽度将显示异常。 为了保持显示正常, 您需要手动配置 w-select 的宽度

基础用法

适用广泛的基础单选 v-model 的值为当前被选中的 w-option 的 value 属性值

基础用法
请选择
请选择
请选择
请选择
禁用状态:为 `w-select` 设置 `disabled`属性,则整个选择器不可用
请选择
禁用选项:在 w-option 中,设定 disabled 值为 true,即可禁用该选项
请选择
可清空:为 w-select 设置 clearable 属性,则可将选择器清空
请选择
🎉 轻量化:为 w-select 设置 plain 属性
请选择
请选择

Options 属性 1.1.1

w-option 基础用法. 你可以通过 options 属性自定义 w-option 的别名。

Select

不同状态 1.1.1

通过 status 属性可以设置选择器的不同状态。

请选择
校验通过文本提示
请选择
校验存在严重问题文本提示
请选择
校验存在严重问题文本提示
请选择
校验不通过文本提示

基础多选

多选选择器使用 tag 组件来展示已选中的选项。

w-select 设置 multiple 属性即可启用多选, 此时 v-model 的值为当前选中值所组成的数组。 默认情况下选中值会以 Tag 组件的形式展现, 你也可以设置 collapse-tags 属性将它们合并为一段文字。 您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

基础用法
请选择

Large

请选择

Small

请选择

mini

请选择

使用 collapse-tags

请选择

使用 collapse-tags-tooltip

请选择

使用 max-collapse-tags

请选择
禁用
请选择

筛选选项

可以利用筛选功能快速查找选项。

w-select添加filterable属性即可启用搜索功能。 默认情况下,Select 会找出所有 label 属性包含输入值的选项。 如果希望使用其他的搜索逻辑,可以通过传入一个 filter-method 来实现。 filter-method 为一个 Function,它会在输入值发生变化时调用,参数为当前输入值。

单选

请选择

多选

请选择

远程搜索

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

从服务器搜索数据,输入关键字进行查找。为了启用远程搜索,需要将filterableremote设置为true,同时传入一个remote-methodremote-method为一个Function,它会在输入值发生变化时调用,参数为当前输入值。 需要注意的是,如果 w-option 是通过 v-for 指令渲染出来的,此时需要为 w-option 添加 key 属性, 且其值需具有唯一性,比如这个例子中的 item.value

输入关键词

创建新的选项

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

通过使用 allow-create 属性,用户可以通过输入框创建新项目。 为了使 allow-create 正常工作, filterable 的值必须为 true。 本例还使用了 default-first-option 属性, 在该属性为 true 的情况下,按下回车就可以选中当前选项列表中的第一个选项,无需使用鼠标或键盘方向键进行定位。

输入关键词创建

使用值键 value-key 属性

如果 Select 的绑定值为对象类型,请务必指定 value-key 作为它的唯一性标识。

通过使用 value-key 属性,可以正确处理带有重复 label 的数据。 这样虽然label 是重复的,但任可通过 id 来确认唯一性。

请选择

selected option's description: no select

自定义模板

你可以自定义如何来渲染每一个选项。

将自定义的 HTML 模板插入 w-option 的 slot 中即可。

请选择

自定义下拉菜单的头部

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

使用 slot 自定义内容

请选择

自定义下拉菜单的底部

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

使用 slot 自定义内容

请选择

将选项进行分组

你可以为选项进行分组来区分不同的选项

使用 w-option-group 对备选项进行分组,它的 label 属性为分组名

请选择

自定义标签

您可以自定义标签。

将自定义的标签插入 w-select 的 slot 中即可。 collapse-tags, collapse-tags-tooltip, max-collapse-tags 在此模式下不生效.

自定义加载

修改加载区域内容

loading icon1

输入关键词

loading icon2

输入关键词

自定义标签

您可以自定义标签

: Option1

空值配置

若想配置如空字符串为有效值而不是空值,可以配置 empty-values[null, undefined].

如果您想要将清空值更改为 null, 请设置 value-on-clearnull

Select API

Attributes

参数说明类型默认值Version
model-value / v-model选中项绑定值string / number / boolean / object / array
multiple是否多选booleanfalse
disabled是否禁用booleanfalse
value-key作为 value 唯一标识的键名,绑定值为对象类型时必填stringvalue
size输入框尺寸enum
clearable是否可以清空选项booleanfalse
collapse-tags多选时是否将选中值按文字的形式展示booleanfalse
collapse-tags-tooltip当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,collapse-tags属性必须设定为 truebooleantrue
multiple-limitmultiple 属性设置为 true 时,代表多选场景下用户最多可以选择的项目数, 为 0 则不限制number0
nameSelect 输入框的原生 name 属性string
effecttooltip 主题,内置了 dark / light 两种enum / stringlighter
autocompleteSelect 输入框的原生 autocomplete 属性stringoff
placeholder占位符,默认为“Select”string
filterableSelect 组件是否可筛选booleanfalse
allow-create是否允许用户创建新条目, 只有当 filterable 设置为 true 时才会生效。booleanfalse
filter-method自定义筛选方法Function
remote其中的选项是否从服务器远程加载booleanfalse
remote-method自定义远程搜索方法Function
loading是否正在从远程获取数据booleanfalse
loading-text从服务器加载数据时显示的文本,默认为“Loading”string
no-match-text搜索条件无匹配时显示的文字,也可以使用 empty 插槽设置,默认是 “No matching data'”string
no-data-text无选项时显示的文字,也可以使用 empty 插槽设置自定义内容,默认是 “暂无数据”string
popper-class选择器下拉菜单的自定义类名string''
popper-style 1.1.1为 Select 下拉菜单和标签提示设置自定义样式string / object
reserve-keywordmultiplefilterable被设置为 true 时,是否在选中一个选项后保留当前的搜索关键词booleantrue
default-first-option是否在输入框按下回车时,选择第一个匹配项。 需配合 filterableremote 使用booleanfalse
teleported是否使用 teleport。设置成 true则会被追加到 append-to 的位置booleantrue
append-to下拉框挂载到哪个 DOM 元素string
persistent当下拉选择器未被激活并且persistent设置为false,选择器会被删除。booleantrue
automatic-dropdown对于不可搜索的 Select,是否在输入框获得焦点后自动弹出选项菜单booleanfalse
clear-icon自定义清除图标string / objectCircleCloseFilled
fit-input-width下拉框的宽度是否与输入框相同booleanfalse
suffix-icon自定义后缀图标组件string / object
suffix-icon-rotate自定义后缀图标组件是否旋转booleantrue
tag-type标签类型enuminfo
tag-effect标签效果enumlight
validate-event是否触发表单验证booleantrue
offset下拉面板偏移量number12
show-arrow下拉菜单的内容是否有箭头booleanfalse
placement下拉框出现的位置enumbottom-start
fallback-placementsdropdown 可用的 positions 请查看popper.js 文档array['bottom-start', 'top-start', 'right', 'left']
max-collapse-tags需要显示的 Tag 的最大数量 只有当 collapse-tags 设置为 true 时才会生效。number1
popper-optionspopper.js 参数objectrefer to popper.js doc{}
aria-label a11y等价于原生 input aria-label 属性string
empty-values组件的空值配置 参考 config-providerarray
value-on-clear清空选项的值 参考 config-providerstring / number / boolean / Function
tabindexinput 的 tabindexstring / number
plain朴素的 SelectbooleanfalseV0.0.8
options 1.1.1选项的数据源 value and label and disabled 可以通过 props自定义array
props 1.1.1配置 optionsobject
debounce 1.1.1远程搜索时的防抖延迟(以毫秒为单位)number300

props

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

Events

事件名说明Type
change选中值发生变化时触发Function
visible-change下拉框出现/隐藏时触发Function
remove-tag多选模式下移除 tag 时触发Function
clear可清空的单选模式下用户点击清空按钮时触发Function
blur当 input 失去焦点时触发Function
focus当 input 获得焦点时触发Function
popup-scroll下拉滚动时触发Function

Slots

插槽名说明子标签
defaultoption 组件列表Option Group / Option
header下拉列表顶部的内容
footer下拉列表底部的内容
prefixSelect 组件头部内容
empty无选项时的列表
tagselect 组件自定义标签内容
loadingselect 组件自定义 loading 内容
labelselect 组件自定义标签内容

Exposes

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

Option Group API

Attributes

属性名说明TypeDefault
label分组的名称string
disabled是否将该分组下所有选项置为禁用booleanfalse

Slots

属性名说明Subtags
default自定义默认内容Option

Option API

Attributes

名称详情类型默认
value选项的值string / number / boolean / object
label选项的标签,若不设置则默认与value相同string / number
disabled是否禁用该选项booleanfalse

Slots

名称说明
default默认插槽内容

Copyright 2025 Winning Health 版权所有