Select 选择器
当选项较多时,使用下拉菜单展示并选择目标项。
TIP
u-select 默认宽度为 100%。在行内表单中可能坍缩,需为 u-select 指定明确宽度。
TIP
下拉层与触发器之间的小三角(Popper 箭头)默认不显示;需要时设置 show-arrow。
基础用法
v-model 为当前选中的 u-option 对应值。
选项属性
在基础 u-option 用法上的快捷方式,可通过 props 自定义 options 各字段别名。
禁用选项
将 u-option 的 disabled 设为 true 可禁用该选项。
禁用选择器
禁用整个组件。
将 u-select 的 disabled 设为 true。
可清空
可通过清空图标一键清除已选值。
为 u-select 设置 clearable,右侧会出现清空图标。
尺寸
使用 size 调整选择器尺寸,可选 large、small 等。
基础多选
多选时默认以标签展示已选项。
设置 multiple 开启多选,此时 v-model 为选中项数组。默认以 Tag 展示;collapse-tags 可折叠为文字;collapse-tags-tooltip 可在悬停折叠文字时展示全部标签。
default
use collapse-tags
use collapse-tags-tooltip
use max-collapse-tags
自定义模板
可自定义选项的展示模板。
在 u-option 的插槽中插入自定义 HTML。
下拉框头部
可自定义下拉面板顶部内容。
使用对应插槽自定义内容。
下拉框底部
可自定义下拉面板底部内容。
使用对应插槽自定义内容。
分组
将选项分组展示。
使用 u-option-group 分组,其 label 为分组名称。
本地筛选
输入关键字筛选选项。
为 u-select 设置 filterable 开启筛选。默认按选项 label 是否包含输入值匹配;也可传入 filter-method 自定义 (query) => void 逻辑。
远程搜索
输入关键字向服务端请求数据。
同时设置 filterable 与 remote 为 true,并传入 remote-method,在输入变化时以当前关键字为参数调用。使用 v-for 渲染 u-option 时请设置唯一 key(如下例 item.value)。
default
use remote-show-suffix
创建新条目
允许创建并选择当前选项列表中不存在的条目。
使用 allow-create,用户可在输入框中键入新项;需同时开启 filterable。本例还演示 default-first-option:为 true 时可直接回车选中当前列表第一项而无需鼠标操作。
value-key
当绑定值为对象时,必须设置 value-key 指定唯一键字段名。
通过 value-key 区分 label 相同但 id 不同的选项。
selected option's description: no select
自定义标签
可自定义多选标签展示。
在 u-select 的标签插槽中自定义;此方式下 collapse-tags、collapse-tags-tooltip、max-collapse-tags 不生效。
自定义加载
覆盖加载中展示内容。
loading icon1
loading icon2
空值配置
若需将空字符串视为有效值,可将 empty-values 设为 [null, undefined]。
若希望清空后绑定值为 null,将 value-on-clear 设为 null。
自定义标签文案
可自定义选项标签展示。
选择器 API
选择器 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string / number / boolean / object / array | — |
| multiple | 是否多选 | boolean | false |
| options | 选项数据,可通过 props 自定义 value、label、disabled 等字段键名 | array | — |
| props | 选项字段映射配置 | object | — |
| disabled | 是否禁用 | boolean | false |
| value-key | 绑定值为对象时的唯一键字段名 | string | value |
| size | 输入框尺寸 | enum | — |
| clearable | 是否可清空 | boolean | false |
| collapse-tags | 多选时是否将标签折叠为文字 | boolean | false |
| collapse-tags-tooltip | 折叠标签时悬停是否展示全部标签;需同时开启 collapse-tags | boolean | false |
| tag-tooltip | 折叠标签 Tooltip 的配置对象;需同时开启 collapse-tags 与 collapse-tags-tooltip | object | {} |
| 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 | 占位符,默认「Select」 | string | — |
| filterable | 是否可筛选 | boolean | false |
| allow-create | 是否允许创建条目;需开启 filterable | boolean | false |
| filter-method | 自定义筛选函数,参数为当前输入;需开启 filterable | Function | — |
| remote | 是否远程加载选项 | boolean | false |
| debounce | 远程搜索防抖毫秒数 | number | 300 |
| remote-method | 远程搜索函数,参数为当前输入;需开启 filterable | Function | — |
| remote-show-suffix | 远程搜索时是否显示后缀图标 | boolean | false |
| loading | 是否处于远程加载状态 | boolean | false |
| loading-text | 远程加载时展示文案,默认「Loading」 | string | — |
| no-match-text | 无匹配结果时文案,可用 empty 插槽覆盖,默认「No matching data」 | string | — |
| no-data-text | 无选项时文案,可用 empty 插槽覆盖,默认「No data」 | string | — |
| popper-class | 下拉与标签 Tooltip 的自定义 class | string | '' |
| popper-style | 下拉与标签 Tooltip 的自定义 style | string / object | — |
| reserve-keyword | 多选且可筛选时,选中后是否保留当前关键字 | boolean | true |
| default-first-option | 回车是否选中第一项匹配项;配合 filterable 或 remote | boolean | false |
| teleported | 下拉是否传送至 append-to 指定位置 | boolean | true |
| append-to | 下拉挂载的目标元素 | CSSSelector / HTMLElement | — |
| persistent | 下拉失焦且 persistent 为 false 时是否销毁下拉 DOM | boolean | true |
| automatic-dropdown | 不可筛选时,聚焦输入框是否自动展开菜单 | boolean | false |
| clear-icon | 自定义清空图标组件 | string / object | CircleClose |
| fit-input-width | 下拉宽度是否与输入框一致 | boolean | false |
| suffix-icon | 自定义后缀图标组件 | string / object | ArrowDown |
| 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 | 下拉备选方位列表,见 popper.js | array | ['bottom-start', 'top-start', 'right', 'left'] |
| max-collapse-tags | 折叠时最多展示标签数;需开启 collapse-tags | number | 1 |
| popper-options | popper.js 参数 | objectrefer to popper.js doc | {} |
| 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 | — |
WARNING
suffix-transition 已弃用,请改用样式覆盖方案。
props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 选项对象中作为取值的字段名 | string | value |
| label | 选项对象中作为展示文案的字段名 | string | label |
| options | 选项对象中表示子级的字段名 | string | options |
| disabled | 选项对象中表示禁用态的字段名 | string | disabled |
tag-tooltip
回退机制
tag-tooltip 内各属性的优先级为:
tag-tooltip对象内显式声明的字段;- 从
u-select继承的共用属性(如 effect、popper-class、popper-style、teleported、append-to、popper-options); - 底层
u-tooltip的默认值。 这样可在覆盖标签 Tooltip 行为的同时,默认与下拉框保持一致。
自定义挂载容器
通过 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 浮层的 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 | 下拉显隐变化时触发 | Function |
| remove-tag | 多选移除标签时触发 | Function |
| clear | 可清空时点击清空图标触发 | Function |
| blur | 输入框失焦时触发 | Function |
| focus | 输入框聚焦时触发 | Function |
| popup-scroll | 下拉滚动时触发 | Function |
选择器 插槽
| 名称 | 说明 | 子标签 |
|---|---|---|
| default | 选项列表 | 选项分组 / 选项 |
| header | 下拉顶部内容 | — |
| footer | 下拉底部内容 | — |
| prefix | 选择器前缀内容 | — |
| empty | 无选项时的内容 | — |
| tag | 自定义标签 | object |
| loading | 自定义加载中内容 | — |
| label | 自定义标签文案 | object |
选择器 方法
| 名称 | 说明 | 类型 |
|---|---|---|
| focus | 聚焦输入框 | Function |
| blur | 失焦输入框并关闭下拉 | Function |
| selectedLabel | 获取当前选中项的展示文案 | object |
选项分组 API
选项分组 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label | 分组名称 | string | — |
| disabled | 是否禁用该分组下全部选项 | boolean | false |
选项分组 插槽
| 名称 | 说明 | 子标签 |
|---|---|---|
| default | 默认内容 | 选项 |
选项 API
选项 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 选项值 | string / number / boolean / object | — |
| label | 选项标签,缺省与 value 相同 | string / number | — |
| disabled | 是否禁用该选项 | boolean | false |
选项 插槽
| 名称 | 说明 |
|---|---|
| default | 默认内容 |