Select 选择器

当选项较多时,使用下拉菜单展示并选择目标项。

TIP

u-select 默认宽度为 100%。在行内表单中可能坍缩,需为 u-select 指定明确宽度。

TIP

下拉层与触发器之间的小三角(Popper 箭头)默认不显示;需要时设置 show-arrow

基础用法

v-model 为当前选中的 u-option 对应值。

Select

选项属性

在基础 u-option 用法上的快捷方式,可通过 props 自定义 options 各字段别名。

Select

禁用选项

u-optiondisabled 设为 true 可禁用该选项。

Select

禁用选择器

禁用整个组件。

u-selectdisabled 设为 true

Select

可清空

可通过清空图标一键清除已选值。

u-select 设置 clearable,右侧会出现清空图标。

Select

尺寸

使用 size 调整选择器尺寸,可选 largesmall 等。

Select
Select
Select

基础多选

多选时默认以标签展示已选项。

设置 multiple 开启多选,此时 v-model 为选中项数组。默认以 Tag 展示;collapse-tags 可折叠为文字;collapse-tags-tooltip 可在悬停折叠文字时展示全部标签。

default

Select

use collapse-tags

Select

use collapse-tags-tooltip

Select

use max-collapse-tags

Select

自定义模板

可自定义选项的展示模板。

u-option 的插槽中插入自定义 HTML。

Select

下拉框头部

可自定义下拉面板顶部内容。

使用对应插槽自定义内容。

Select

下拉框底部

可自定义下拉面板底部内容。

使用对应插槽自定义内容。

Select

分组

将选项分组展示。

使用 u-option-group 分组,其 label 为分组名称。

Select

本地筛选

输入关键字筛选选项。

u-select 设置 filterable 开启筛选。默认按选项 label 是否包含输入值匹配;也可传入 filter-method 自定义 (query) => void 逻辑。

Select

远程搜索

输入关键字向服务端请求数据。

同时设置 filterableremotetrue,并传入 remote-method,在输入变化时以当前关键字为参数调用。使用 v-for 渲染 u-option 时请设置唯一 key(如下例 item.value)。

default

Please enter a keyword

use remote-show-suffix

Please enter a keyword

创建新条目

允许创建并选择当前选项列表中不存在的条目。

使用 allow-create,用户可在输入框中键入新项;需同时开启 filterable。本例还演示 default-first-option:为 true 时可直接回车选中当前列表第一项而无需鼠标操作。

Choose tags for your article

value-key

当绑定值为对象时,必须设置 value-key 指定唯一键字段名。

通过 value-key 区分 label 相同但 id 不同的选项。

Select

selected option's description: no select

自定义标签

可自定义多选标签展示。

u-select 的标签插槽中自定义;此方式下 collapse-tagscollapse-tags-tooltipmax-collapse-tags 不生效。

自定义加载

覆盖加载中展示内容。

loading icon1

Please enter a keyword

loading icon2

Please enter a keyword

空值配置

若需将空字符串视为有效值,可将 empty-values 设为 [null, undefined]

若希望清空后绑定值为 null,将 value-on-clear 设为 null

自定义标签文案

可自定义选项标签展示。

: Option1

选择器 API

选择器 属性

名称说明类型默认值
model-value / v-model绑定值string / number / boolean / object / array
multiple是否多选booleanfalse
options选项数据,可通过 props 自定义 valuelabeldisabled 等字段键名array
props选项字段映射配置object
disabled是否禁用booleanfalse
value-key绑定值为对象时的唯一键字段名stringvalue
size输入框尺寸enum
clearable是否可清空booleanfalse
collapse-tags多选时是否将标签折叠为文字booleanfalse
collapse-tags-tooltip折叠标签时悬停是否展示全部标签;需同时开启 collapse-tagsbooleanfalse
tag-tooltip折叠标签 Tooltip 的配置对象;需同时开启 collapse-tagscollapse-tags-tooltipobject{}
multiple-limit多选时最多可选数量,0 表示不限制number0
id原生 input 的 idstring
name原生 input 的 namestring
effect下拉与标签 Tooltip 的主题,内置 dark / lightenum / stringlight
autocomplete原生 input 的 autocompletestringoff
placeholder占位符,默认「Select」string
filterable是否可筛选booleanfalse
allow-create是否允许创建条目;需开启 filterablebooleanfalse
filter-method自定义筛选函数,参数为当前输入;需开启 filterableFunction
remote是否远程加载选项booleanfalse
debounce远程搜索防抖毫秒数number300
remote-method远程搜索函数,参数为当前输入;需开启 filterableFunction
remote-show-suffix远程搜索时是否显示后缀图标booleanfalse
loading是否处于远程加载状态booleanfalse
loading-text远程加载时展示文案,默认「Loading」string
no-match-text无匹配结果时文案,可用 empty 插槽覆盖,默认「No matching data」string
no-data-text无选项时文案,可用 empty 插槽覆盖,默认「No data」string
popper-class下拉与标签 Tooltip 的自定义 classstring''
popper-style下拉与标签 Tooltip 的自定义 stylestring / object
reserve-keyword多选且可筛选时,选中后是否保留当前关键字booleantrue
default-first-option回车是否选中第一项匹配项;配合 filterableremotebooleanfalse
teleported下拉是否传送至 append-to 指定位置booleantrue
append-to下拉挂载的目标元素CSSSelector / HTMLElement
persistent下拉失焦且 persistentfalse 时是否销毁下拉 DOMbooleantrue
automatic-dropdown不可筛选时,聚焦输入框是否自动展开菜单booleanfalse
clear-icon自定义清空图标组件string / objectCircleClose
fit-input-width下拉宽度是否与输入框一致booleanfalse
suffix-icon自定义后缀图标组件string / objectArrowDown
tag-type标签类型enuminfo
tag-effect标签效果enumlight
validate-event是否触发表单校验booleantrue
offset下拉偏移量number12
show-arrow下拉是否显示箭头booleanfalse
placement下拉出现位置enumbottom-start
fallback-placements下拉备选方位列表,见 popper.jsarray['bottom-start', 'top-start', 'right', 'left']
max-collapse-tags折叠时最多展示标签数;需开启 collapse-tagsnumber1
popper-optionspopper.js 参数objectrefer to popper.js doc{}
aria-label a11y原生 aria-labelstring
empty-values视为空的取值列表,见 config-providerarray
value-on-clear清空后的绑定值,见 config-providerstring / number / boolean / Function
tabindex原生 input 的 tabindexstring / number

WARNING

suffix-transition弃用,请改用样式覆盖方案。

props

属性说明类型默认值
value选项对象中作为取值的字段名stringvalue
label选项对象中作为展示文案的字段名stringlabel
options选项对象中表示子级的字段名stringoptions
disabled选项对象中表示禁用态的字段名stringdisabled

tag-tooltip

回退机制

tag-tooltip 内各属性的优先级为:

  1. tag-tooltip 对象内显式声明的字段;
  2. u-select 继承的共用属性(如 effect、popper-class、popper-style、teleported、append-to、popper-options);
  3. 底层 u-tooltip 的默认值。 这样可在覆盖标签 Tooltip 行为的同时,默认与下拉框保持一致。

自定义挂载容器

通过 append-to 将 Tooltip 挂到自定义容器时,容器建议设置 position: relativeposition: absolute 以保证定位准确;若需限制 Tooltip 溢出,可为容器设置 overflow: hidden

属性说明类型默认值
append-toTooltip 内容挂载到的元素CSSSelector / HTMLElement
placementTooltip 方位enumbottom
fallback-placementsTooltip 备选方位,见 popper.jsarray['bottom', 'top', 'right', 'left']
effectTooltip 主题,内置 dark / lightenum / string
popper-classTooltip 浮层的 classstring
popper-styleTooltip 浮层的 stylestring / object
transition动画名称string
teleported是否将 Tooltip 内容传送到 append-to 指定位置boolean
popper-optionspopper.js 参数objectrefer to popper.js doc
show-after显示延迟(毫秒)number
hide-after隐藏延迟(毫秒)number
auto-close自动关闭延时(毫秒)number
offsetTooltip 偏移量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是否禁用该分组下全部选项booleanfalse

选项分组 插槽

名称说明子标签
default默认内容选项

选项 API

选项 属性

名称说明类型默认值
value选项值string / number / boolean / object
label选项标签,缺省与 value 相同string / number
disabled是否禁用该选项booleanfalse

选项 插槽

名称说明
default默认内容