Select 选择器
当选项过多时,使用下拉菜单展示并选择内容。
WARNING
如果你发现 v-model 绑定的值失效,请检查是否开启了兼容模式(compat)。在兼容模式下,需要将 v-model 改写为 v-model:model-value。
TIP
目前 w-select 的默认宽度更改为 100% 当使用内联形式时,宽度将显示异常。 为了保持显示正常, 您需要手动配置 w-select 的宽度
基础用法
基础单选
适用广泛的基础单选 v-model 的值为当前被选中的 w-option 的 value 属性值
Options 数据源 1.1.1
w-option 基础用法. 你可以通过 options 属性自定义 w-option 的别名。
不同状态 1.1.1
通过 status 属性可以设置选择器的不同状态。
基础多选
多选选择器使用 tag 组件来展示已选中的选项。
为 w-select 设置 multiple 属性即可启用多选, 此时 v-model 的值为当前选中值所组成的数组。 默认情况下选中值会以 Tag 组件的形式展现, 你也可以设置 collapse-tags 属性将它们合并为一段文字。 您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。
使用 collapse-tags
使用 collapse-tags-tooltip
使用 max-collapse-tags
选项分组
你可以为选项进行分组来区分不同的选项
使用 w-option-group 对备选项进行分组,它的 label 属性为分组名
数据绑定
使用值键 value-key
如果 Select 的绑定值为对象类型,请务必指定 value-key 作为它的唯一性标识。
通过使用 value-key 属性,可以正确处理带有重复 label 的数据。 这样虽然label 是重复的,但任可通过 id 来确认唯一性。
选中患者信息:未选择
空值配置
若想配置如空字符串为有效值而不是空值,可以配置 empty-values 为 [null, undefined].
如果您想要将清空值更改为 null, 请设置 value-on-clear 为 null
筛选与搜索
筛选选项
可以利用筛选功能快速查找选项。
为w-select添加filterable属性即可启用搜索功能。 默认情况下,Select 会找出所有 label 属性包含输入值的选项。 如果希望使用其他的搜索逻辑,可以通过传入一个 filter-method 来实现。 filter-method 为一个 Function,它会在输入值发生变化时调用,参数为当前输入值。
单选
多选
自定义字段筛选
在本地 filterable 模式下,可通过 filter-fields 指定额外参与匹配的字段(如编码、拼音、别名、关键字)。选项可通过 w-option 的 data 传入对应字段,也可直接在 w-option 上绑定同名属性。
下面的示例支持用 code / pinyin / alias / keyword 搜索,同时仍会匹配 label。
面板内搜索 1.3.4
开启 filterable-dropdown 后,搜索输入框放入下拉面板顶部,选择区只展示已选内容,点击选择框会展开面板并自动聚焦面板内搜索框。
需配合 filterable 使用,常用于 multiple 多选场景。与 remote 远程搜索同用时,点击选择框即展开面板(否则无法输入关键字),输入过程中面板保持展开、不随 loading / 防抖 / 无结果收起。
多选 + 面板内搜索
远程搜索 + 面板内搜索
点击选择区触发 focus;选中项、按 Esc 或再点选择区收起面板不会触发 blur;点击组件外部才会触发 blur
远程搜索
输入关键字以从远程服务器中查找数据。
从服务器搜索数据,输入关键字进行查找。为了启用远程搜索,需要将filterable和remote设置为true,同时传入一个remote-method。 remote-method为一个Function,它会在输入值发生变化时调用,参数为当前输入值。 需要注意的是,如果 w-option 是通过 v-for 指令渲染出来的,此时需要为 w-option 添加 key 属性, 且其值需具有唯一性,比如这个例子中的 item.value。
WARNING
开启 remote + filterable 后,下拉保持打开时连续输入、清空、再输入,visible-change 会跟随 loading / 防抖 / 选项清空等派生可见性反复触发。若只关心真实开合(例如「打开时初始化请求」),请使用 open-change。
功能
创建新的选项 1.3.4
创建并选中未包含在初始选项中的条目,可通过 before-create-option 1.3.4 在创建前拦截校验。
通过使用 allow-create 属性,用户可以通过输入框创建新项目。 为了使 allow-create 正常工作, filterable 的值必须为 true。 本例还使用了 default-first-option 属性, 在该属性为 true 的情况下,按下回车就可以选中当前选项列表中的第一个选项,无需使用鼠标或键盘方向键进行定位。
再通过 before-create-option 1.3.4 在创建前拦截校验:回车选中「新建」项时会先调用该回调,参数为 (option, value);返回 false(或 Promise resolve 为 false)时该条目不会被创建,绑定值不变,返回 true 时正常创建并写入。
空格选中/反选 1.3.1
为 w-select 设置 select-on-press-space 属性后,选中/反选只由空格键触发:空格选中当前悬浮的选项(多选时为反选,且下拉保持展开以便继续操作)。回车键不再执行选中,下拉展开时仅收起下拉框;未展开时按键将放行给外部处理(如表格的键盘导航)。
使用上下方向键移动悬浮项,空格选中/反选,回车收起下拉。
复选框与全选 1.3.4
多选模式下在选项前渲染复选框,并在面板顶部提供「全选」。
需配合 multiple 使用,设置 show-checkbox 属性。面板顶部出现「全选」复选框,手动勾选/取消时触发 select-all 事件,回调为全部未禁用项的 value 数组(取消时为空数组);部分选中时「全选」呈半选态。紧凑版下此属性不生效(两者互斥)。
拖拽排序选项标签 1.3.4
多选且不合并 tag 时,可拖拽调整已选 tag 顺序。
设置 draggable-tag 属性(需配合 multiple 且不设置 collapse-tags),按住已选 tag 拖动换位,松手后绑定值与 tag 顺序同步变化,并依次派发 change 与 tag-drag-end 事件。本例监听了 tag-drag-start / tag-drag-move / tag-drag-end 并展示回调参数,tag-drag-end 回调的第二个参数为排序后的完整绑定值。
拖拽已选标签调整用药顺序,事件将在此显示
紧凑版布局 1.3.4
紧凑版等分网格面板,适合「单位/用法」这类短文本一屏可选完的场景。
设置 tight 属性启用紧凑版,面板固定为 tight-width(默认 320)像素宽、每行等分 tight-column(默认 7)列,选项文字居中、右下虚线分隔;上/下/左/右方向键按网格跳格。注意:紧凑版与 filterable 同用时紧凑版整体失效,面板退回普通纵向列表。
选项置顶 1.3.4
您可以将部分选项置顶到下拉列表最上方,置顶区上方会显示「常用选项」标题,下方以分隔线与普通选项隔开。
通过 :slot="item.top ? 'top' : 'default'" 标记置顶的 w-option,用法与 Vue2 完全一致
单选
多选
置顶项是真实的 w-option 实例,选中、键盘导航、过滤、多选、禁用等行为与普通选项完全一致。置顶区位于滚动列表内部(随列表滚动),与 header 插槽(面板顶部固定区)语义不同。
自定义内容
自定义选项模板
你可以自定义如何来渲染每一个选项。
将自定义的 HTML 模板插入 w-option 的 slot 中即可。
自定义下拉菜单的头部
您可以自定义下拉菜单的头部。
使用 slot 自定义内容
自定义下拉菜单的底部
您可以自定义下拉菜单的底部。
使用 slot 自定义内容
自定义标签
您可以自定义标签。
将自定义的标签插入 w-select 的 tag 插槽中即可。 collapse-tags, collapse-tags-tooltip, max-collapse-tags 在此模式下不生效.
自定义选中项文本
您可以自定义选中项的文本内容。
通过 label 插槽自定义选中项在输入框中的展示,插槽参数为 { index, label, value }。
自定义加载
修改加载区域内容
loading icon1
loading icon2
无障碍标记 aria-label
供自动化测试按原生节点定位:区域标记前缀取控件 aria-label 值 —— 选择区根节点为 <值>::选择区,下拉选项区 ul[role=listbox] 为 <值>::下拉选项区(未传 aria-label 时不输出区域标记);选项节点按 value 固定为 下拉选项::<value>,数据里的 'aria-label' 与 <w-option aria-label> 均不生效。控件 aria-label 落到内部 input(自身值优先、form-item 回退),展开后仍唯一命中。必填统一用 aria-required(String),落在同一内部 input 上,"false" 原样保留。
可视化用例见 自动化测试 · Select。
Select API
Select 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 选中项绑定值 | string / number / boolean / object / array | — |
| multiple | 是否多选 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| value-key | 作为 value 唯一标识的键名,绑定值为对象类型时必填 | string | value |
| size | 输入框尺寸 | enum | — |
| clearable | 是否可以清空选项 | boolean | false |
| collapse-tags | 多选时是否将选中值按文字的形式展示 | boolean | false |
| collapse-tags-tooltip | 当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,collapse-tags属性必须设定为 true | boolean | true |
| tag-tooltip 1.3.4 | 折叠标签 tooltip 的配置对象,可单独覆盖 tooltip 的位置、主题等。需配合 collapse-tags 和 collapse-tags-tooltip 使用,详见 Tag Tooltip 属性 | object | {} |
| multiple-limit | multiple 属性设置为 true 时,代表多选场景下用户最多可以选择的项目数, 为 0 则不限制 | number | 0 |
| name | Select 输入框的原生 name 属性 | string | — |
| effect | tooltip 主题,内置了 dark / light 两种 | enum / string | lighter |
| autocomplete | Select 输入框的原生 autocomplete 属性 | string | off |
| placeholder | 占位符,默认为“Select” | string | — |
| filterable | Select 组件是否可筛选 | boolean | false |
| filterable-dropdown 1.3.4 | 是否把搜索输入框放入下拉面板中,需配合 filterable。开启后点击选择框直接展开面板并聚焦面板内搜索框;与 remote 远程搜索同用时,输入关键字过程中面板保持展开 | boolean | false |
| filter-fields | 本地筛选时额外参与匹配的字段名,始终同时匹配 label;需配合 filterable。如 ['code', 'pinyin', 'alias', 'keyword'] | array | — |
| allow-create | 是否允许用户创建新条目, 只有当 filterable 设置为 true 时才会生效。 | boolean | false |
| filter-method | 自定义筛选方法 | Function | — |
| remote | 其中的选项是否从服务器远程加载 | boolean | false |
| remote-method | 自定义远程搜索方法 | Function | — |
| loading | 是否正在从远程获取数据 | boolean | false |
| 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-keyword | 当 multiple 和 filterable被设置为 true 时,是否在选中一个选项后保留当前的搜索关键词 | boolean | true |
| default-first-option | 是否在输入框按下回车时,选择第一个匹配项。 需配合 filterable 或 remote 使用 | boolean | false |
| select-on-press-space 1.3.1 | 是否通过空格键选中/反选当前悬浮的选项;开启后选中/反选只由空格触发(下拉保持展开),回车不选中、展开时仅收起下拉框 | boolean | false |
| teleported | 是否使用 teleport。设置成 true则会被追加到 append-to 的位置 | boolean | true |
| append-to | 下拉框挂载到哪个 DOM 元素 | string | — |
| persistent | 当下拉选择器未被激活并且persistent设置为false,选择器会被删除。 | boolean | true |
| automatic-dropdown | 对于不可搜索的 Select,是否在输入框获得焦点后自动弹出选项菜单 | boolean | false |
| clear-icon | 自定义清除图标 | string / object | CircleCloseFilled |
| fit-input-width | 下拉框的宽度是否与输入框相同 | boolean | false |
| show-overflow-tooltip | 单选时,选中的文本超出宽度出现省略号后,鼠标悬浮输入框是否以 tooltip 显示完整文本(多选不生效) | boolean | true |
| suffix-icon | 自定义后缀图标组件 | string / object | |
| suffix-icon-rotate | 自定义后缀图标组件是否旋转 | boolean | true |
| tag-type | 标签类型 | enum | info |
| tag-effect | 标签效果 | enum | light |
| validate-event | 是否触发表单验证 | boolean | true |
| offset | 下拉面板偏移量 | number | 12 |
| show-arrow | 下拉菜单的内容是否有箭头 | boolean | false |
| placement | 下拉框出现的位置 | enum | bottom-start |
| fallback-placements | dropdown 可用的 positions 请查看popper.js 文档 | array | ['bottom-start', 'top-start', 'right', 'left'] |
| max-collapse-tags | 需要显示的 Tag 的最大数量 只有当 collapse-tags 设置为 true 时才会生效。 | number | 1 |
| popper-options | popper.js 参数 | objectrefer to popper.js doc | {} |
| aria-label a11y | 等价于原生 input aria-label 属性 | string | — |
| empty-values | 组件的空值配置 参考 config-provider | array | — |
| value-on-clear | 清空选项的值 参考 config-provider | string / number / boolean / Function | — |
| tabindex | input 的 tabindex | string / number | — |
| plain | 朴素的 Select | boolean | false |
| options 1.1.1 | 选项的数据源 value and label and disabled 可以通过 props自定义 | array | — |
| props 1.1.1 | 配置 options | object | — |
| debounce 1.1.1 | 远程搜索时的防抖延迟(以毫秒为单位) | number | 300 |
| tight 1.3.4 | 是否使用紧凑版(等分网格面板)。与 filterable 同用时紧凑版整体失效 | boolean | false |
| tight-column 1.3.4 | 紧凑版布局每行显示列数,需配合 tight | number | 7 |
| tight-width 1.3.4 | 紧凑版布局下面板固定宽度(px),需配合 tight | number | 320 |
| show-checkbox 1.3.4 | 多选模式下配置复选框和全选功能,需配合 multiple。与 tight 互斥 | boolean | false |
| draggable-tag 1.3.4 | 开启 multiple 且不合并 tag 情况下可拖拽已选 tag 顺序 | boolean | false |
| before-create-option 1.3.4 | 创建新条目前置校验,需配合 allow-create。支持异步(返回 Promise),返回 false 则中止创建 | Function | — |
Select Props
| Attribute | Description | Type | Default |
|---|---|---|---|
| value | 指定选项的值为选项对象的某个属性值 | string | value |
| label | 指定节点标签为节点对象的某个属性值 | string | label |
| options | 指定选项的子选项为选项对象的某个属性值 | string | options |
| disabled | 指定选项的禁用为选项对象的某个属性值 | string | disabled |
Tag Tooltip 属性 1.3.4
回退机制
tag-tooltip 中的配置按以下优先级生效:
tag-tooltip对象内显式声明的字段;- 继承
w-select上的同名共享属性(如effect、popper-class、popper-style、teleported、append-to、popper-options); w-tooltip组件的默认值。
因此可以只覆盖标签 tooltip 的个别行为,其余默认与 Select 下拉面板保持一致。
自定义容器定位
当通过 append-to 将 Tooltip 挂载到自定义容器时,建议为该容器设置 position: relative 或 position: absolute 以保证定位准确;如需阻止 Tooltip 溢出容器边界,可为容器追加 overflow: hidden。
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| append-to | Tooltip 内容挂载到哪个元素 | CSSSelector / HTMLElement | — |
| placement | Tooltip 出现的位置 | enum | bottom |
| fallback-placements | Tooltip 可用的备选位置,popper.js | array | ['bottom', 'top', 'right', 'left'] |
| effect | Tooltip 主题,内置了 dark / light 两种 | enum / string | — |
| popper-class | Tooltip popper 的自定义类名 | string | — |
| popper-style | Tooltip popper 的自定义样式 | string / object | — |
| transition | 动画名 | string | — |
| teleported | Tooltip 内容是否使用 teleport,为 true 时挂载到 append-to 指定的位置 | boolean | — |
| popper-options | popper.js 参数 | objectrefer to popper.js doc | — |
| show-after | 延迟显示,单位毫秒 | number | — |
| hide-after | 延迟隐藏,单位毫秒 | number | — |
| auto-close | 自动隐藏的超时时间(毫秒) | number | — |
| offset | Tooltip 的偏移量 | number | — |
Select 事件
| 事件名 | 说明 | Type |
|---|---|---|
| change | 选中值发生变化时触发 | Function |
| visible-change | 下拉框出现/隐藏时触发 | Function |
| open-change 1.3.4 | 下拉框真实开合状态变化时触发,参数为当前是否展开。只跟随 expanded 的真实开合,不受 remote 搜索过程中下拉派生可见性(loading/防抖/选项清空等)跳变影响,适合用于「下拉打开时初始化请求数据」的场景 | Function |
| remove-tag | 多选模式下移除 tag 时触发 | Function |
| clear | 可清空的单选模式下用户点击清空按钮时触发 | Function |
| blur | 当 input 失去焦点时触发 | Function |
| focus | 当 input 获得焦点时触发 | Function |
| popup-scroll | 下拉滚动时触发 | Function |
| end-reached 1.3.4 | 下拉列表滚动到尽头(顶部/底部/左侧/右侧)时触发 | Function |
| select-all 1.3.4 | 用户勾选/取消面板顶部「全选」(点击复选框或整行空白区域)时触发,回调为全部未禁用项的 value 数组(取消时为空数组) | Function |
| tag-drag-start 1.3.4 | tag 开始拖拽时触发 | Function |
| tag-drag-end 1.3.4 | tag 拖拽结束时触发,第二参为拖拽后的完整 value 数组 | Function |
| tag-drag-move 1.3.4 | tag 拖拽经过其他 tag 时触发。与 2.0 不同:origin 为被拖 tag 的索引 | Function |
Select 插槽
| 插槽名 | 说明 | 子标签 |
|---|---|---|
| default | option 组件列表 | Option Group / Option |
| header | 下拉列表顶部的内容 | — |
| footer | 下拉列表底部的内容 | — |
| top | 通过 :slot="'top'" 标记的置顶选项 | Option |
| prefix | Select 组件头部内容 | — |
| empty | 无选项时的列表 | — |
| tag | select 组件自定义标签内容 | — |
| loading | select 组件自定义 loading 内容 | — |
| label | select 组件自定义标签内容 | — |
Select Exposes
| 插槽名 | 说明 | 类型 |
|---|---|---|
| focus | 使选择器的输入框获取焦点 | Function |
| blur | 使选择器的输入框失去焦点,并隐藏下拉框 | Function |
| selectedLabel | 获取当前选中的标签 | object |
Option Group API
Option Group 属性
| 属性名 | 说明 | Type | Default |
|---|---|---|---|
| label | 分组的名称 | string | — |
| disabled | 是否将该分组下所有选项置为禁用 | boolean | false |
Option Group 插槽
| 属性名 | 说明 | Subtags |
|---|---|---|
| default | 自定义默认内容 | Option |
Option API
Option 属性
| 名称 | 详情 | 类型 | 默认 |
|---|---|---|---|
| value | 选项的值 | string / number / boolean / object | — |
| label | 选项的标签,若不设置则默认与value相同 | string / number | — |
| data | 额外数据,配合 Select filter-fields 本地筛选 | object | — |
| disabled | 是否禁用该选项 | boolean | false |
Option 插槽
| 名称 | 说明 |
|---|---|
| default | 默认插槽内容 |
Copyright 2025 Winning Health 版权所有

