Select 选择器 ​

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

TIP

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

TIP

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

基础用法 ​

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

Select

选项属性 ​

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

Select

禁用选项 ​

将 u-option 的 disabled 设为 true 可禁用该选项。

Select

禁用选择器 ​

禁用整个组件。

将 u-select 的 disabled 设为 true。

Select

可清空 ​

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

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

Select

尺寸 ​

使用 size 调整选择器尺寸,可选 large、small 等。

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

远程搜索 ​

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

同时设置 filterable 与 remote 为 true,并传入 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-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。

自定义标签文案 ​

可自定义选项标签展示。

: Option1

选择器 API ​

选择器 属性 ​

名称说明类型默认值
model-value / v-model绑定值string / number / boolean / object / array—
multiple是否多选booleanfalse
options选项数据,可通过 props 自定义 value、label、disabled 等字段键名array—
props选项字段映射配置object—
disabled是否禁用booleanfalse
value-key绑定值为对象时的唯一键字段名stringvalue
size输入框尺寸enum—
clearable是否可清空booleanfalse
collapse-tags多选时是否将标签折叠为文字booleanfalse
collapse-tags-tooltip折叠标签时悬停是否展示全部标签;需同时开启 collapse-tagsbooleanfalse
tag-tooltip折叠标签 Tooltip 的配置对象;需同时开启 collapse-tags 与 collapse-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回车是否选中第一项匹配项;配合 filterable 或 remotebooleanfalse
teleported下拉是否传送至 append-to 指定位置booleantrue
append-to下拉挂载的目标元素CSSSelector / HTMLElement—
persistent下拉失焦且 persistent 为 false 时是否销毁下拉 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: relative 或 position: 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默认内容