Select 选择器

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

提示

2.5.0 版本之后,el-select 的默认宽度更改为 100%。在行内表单中使用时,宽度会收缩。为了正常显示,你需要给 el-select 一个具体的宽度(例如:示例)。

基础用法

v-model 的值为当前被选中的 el-option 的值。

选择器

Options 属性 2.10.5

基础 el-option 用法的快捷方式。你可以通过 props 属性自定义 options 的别名。

选择器

禁用选项

el-option 中的 disabled 设置为 true 即可禁用该选项。

选择器

禁用状态

禁用整个组件。

el-select 设置 disabled 属性使其禁用。

选择器

可清空

你可以使用清除图标来清除选择器。

el-select 设置 clearable 属性,则会出现清除图标。

选择器

尺寸

添加 size 属性可以更改选择器的尺寸。除了默认尺寸外,还有两个选项:largesmall

选择器
选择器
选择器

基础多选

多选模式下使用标签展示已选项。

el-select 设置 multiple 属性即可启用多选模式。此时,v-model 的值将为已选项组成的数组。默认情况下,已选项将以标签形式显示。你可以使用 collapse-tags 属性将它们合并为文本。使用 collapse-tags-tooltip 属性可以在鼠标悬停合并文本时查看它们。

default

选择器

使用 collapse-tags

选择器

使用 collapse-tags-tooltip

选择器

使用 max-collapse-tags

选择器

自定义模板

你可以自定义选项的 HTML 模板。

将自定义 HTML 模板插入到 el-option 的插槽中。

选择器

下拉菜单头部 2.4.3

您可以自定义下拉列表的页眉。

使用插槽来自定义内容。

选择器

您可以自定义下拉列表的页脚。

使用插槽来自定义内容。

选择器

分组

分组展示选项。

使用 el-option-group 对选项进行分组,其 label 属性代表组名。

选择器

选项筛选

你可以过滤出想要的选项。

el-select 添加 filterable 属性即可启用筛选功能。默认情况下,选择器会查找所有 label 属性包含输入值的选项。如果你倾向于其他筛选策略,可以传入 filter-methodfilter-method 是一个函数,当输入值发生变化时被调用,其参数为当前输入值。

选择器

输入关键字,并从服务器获取数据。

filterableremote 设置为 true 即可启用远程搜索,同时你应该传入 remote-methodremote-method 是一个函数,当输入值发生变化时被调用,其参数为当前输入值。注意,如果 el-option 是使用 v-for 指令渲染的,你应该为 el-option 添加 key 属性。其值必须是唯一的,例如下例中的 item.value

default

请输入关键词

使用 remote-show-suffix

请输入关键词

创建新项目

创建并选择选择器选项中不包含的新项目

通过使用 allow-create 属性,用户可以通过在输入框中输入来创建新项目。注意,要使 allow-create 生效,filterable 必须为 true。本例还展示了 default-first-option。当此属性设置为 true 时,无需使用鼠标或方向键导航,只需按回车键即可选中当前选项列表中的第一个选项。

为你的文章选择标签

使用 value-key 属性

如果选择器的绑定值是一个对象,请务必将 value-key 指定为其唯一的标识键名。

通过使用 value-key 属性,可以正确处理具有重复标签的数据。虽然 label 属性的值重复,但可以通过 id 标识该选项。

选择器

已选选项的描述:未选择

自定义标签 2.5.0

您可以自定义标签。

将自定义标签插入到 el-select 的插槽中。 collapse-tagscollapse-tags-tooltipmax-collapse-tags 将不起作用。

自定义加载 2.5.2

覆盖加载内容。

加载图标1

请输入关键词

加载图标2

请输入关键词

空值 2.7.0

如果您想支持空字符串,请将 empty-values 设置为 [null, undefined]

如果要将清除值更改为 null,请将 value-on-clear 设置为 null

自定义标签 2.7.4

您可以自定义标签。

: 选项1

Select API

Select 属性

名称描述类型默认值
model-value / v-model绑定值string / number / boolean / object / array
multiple是否启用多选模式booleanfalse
选项数据 2.10.5选项数据,其中 `value` 和 `label` 和 `disabled` 的键名可以通过 `props` 自定义array
属性配置 2.10.5配置选项object
disabled是否禁用选择器booleanfalse
value-key作为 value 唯一标识的键名,绑定值为对象类型时必填stringvalue
size输入框尺寸枚举
可清空是否可以清空选项booleanfalse
collapse-tags多选时是否将选中值按文字的形式展示booleanfalse
collapse-tags-tooltip 2.3.0当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,`collapse-tags` 属性必须设定为 truebooleanfalse
标签文字提示 2.13.3collapse-tags 文字提示的配置对象。要使用此功能,collapse-tagscollapse-tags-tooltip 必须为 trueobject{}
multiple-limitmultipletrue 时,用户最多可以选择的选项数。设置为 0 则不限制number0
id原生输入框 idstring
名称选择器输入框的 name 属性string
effecttooltip 主题,内置主题:`dark` / `light`enum / stringlight
自动补全选择器输入框的 autocomplete 属性stringoff
占位符占位文字,默认为 'Select'string
filterable是否可筛选booleanfalse
allow-create是否允许用户创建新项目, 需配合 `filterable` 使用booleanfalse
filter-method自定义筛选方法,第一个参数是当前输入值。要使用此功能,filterable 必须为 trueFunction
remote是否从服务器加载选项booleanfalse
防抖 2.11.7远程搜索时的防抖延迟,单位为毫秒number300
remote-method当输入值改变时调用的函数。 它的参数是当前的输入值。 若要使用此属性,`filterable` 必须为 trueFunction
remote-show-suffix在远程搜索方法中显示后缀图标booleanfalse
加载中是否正在从远程获取数据booleanfalse
loading-text远程加载时显示的文字,默认为 '加载中'string
no-match-text搜索条件无匹配时显示的文字,也可以使用 `empty` 插槽,默认为 '无匹配数据'string
no-data-text无选项时显示的文本,也可以使用插槽 empty,默认为 'No data'string
popper-class选择器下拉菜单和标签文字提示的自定义类名string''
popper-style 2.11.0选择器下拉菜单和标签文字提示的自定义样式string / object
reserve-keywordmultiplefilterable 为 true 时,选中一个选项后是否保留当前关键词booleantrue
default-first-option在输入框按下回车,选择第一个匹配项。需配合 `filterable` 或 `remote` 使用booleanfalse
teleported是否将下拉列表元素插入到 `append-to` 设置的元素中booleantrue
插入至 2.8.4下拉列表应该附加到哪个元素CSSSelector / HTMLElement
persistent当下拉列表不活动且 `persistent` 为 `false` 时,下拉列表将被销毁booleantrue
automatic-dropdown对于不可过滤的 Select 组件,此属性决定是否在输入框获得焦点后自动弹出选项菜单booleanfalse
clear-icon自定义清除图标组件string / objectCircleClose
fit-input-width下拉框的宽度是否与输入框相同booleanfalse
后缀图标自定义后缀图标组件string / objectArrowDown
tag-type标签类型枚举信息
tag-effect 2.7.7标签效果枚举light
validate-event是否触发表单验证booleantrue
offset 2.8.8下拉列表的偏移量number12
show-arrow 2.8.8下拉列表是否带有箭头booleantrue
出现位置 2.2.17下拉框出现的位置枚举下左
fallback-placements 2.5.6下拉菜单可能出现的位置列表 popper.jsarray['bottom-start', 'top-start', 'right', 'left']
max-collapse-tags 2.3.0最多显示的标签数。要使用此功能,collapse-tags 必须为 truenumber1
popper-optionspopper.js 参数object请参考 popper.js 文档{}
aria-label 无障碍与原生输入框的 `aria-label` 相同string
empty-values 2.7.0组件的空值,请参阅 config-providerarray
value-on-clear 2.7.0清空时的返回值,请参阅 config-providerstring / number / boolean / Function
后缀过渡 已废弃下拉菜单图标出现/消失时的动画booleantrue
tabindex 2.9.0输入框的 tabindexstring / number

警告

suffix-transition废弃,并将于 2.4.0 移除,请使用覆盖样式方案。

props

属性描述类型默认值
value指定节点对象的哪个键用作节点的值stringvalue
label指定节点对象的哪个键用作节点的标签stringlabel
选项 2.11.0指定节点对象的哪个键用作节点的子节点stringoptions
disabled指定节点对象的哪个键用作节点的禁用stringdisabled

标签文字提示 2.13.3

回退机制

tag-tooltip 中的属性遵循以下优先级顺序

  1. tag-tooltip 对象中显式定义的字段。
  2. 从 el-select 继承的共享属性(例如 effect, popper-class, popper-style, teleported, append-to, popper-options)。
  3. 底层 el-tooltip 组件的默认值。这允许你为标签覆盖特定的 tooltip 行为,同时默认情况下保持与 Select 下拉菜单的一致性。

自定义容器定位

当将 Tooltip 附加到自定义容器(通过 append-to 属性)时,该容器应配置为 position: relativeposition: absolute 以确保精确定位。此外,如果你需要防止 Tooltip 超出其边界,可以为容器应用 overflow: hidden

属性描述类型默认值
append-totooltip 内容插入至哪个元素CSSSelector / HTMLElement
placementTooltip 的出现位置枚举bottom
fallback-placements文字提示可能出现的位置列表 popper.jsarray['bottom', 'top', 'right', 'left']
effectTooltip 的主题,内置主题:`dark` / `light`enum / string
popper-classTooltip 弹出层的自定义类名string
popper-styleTooltip 弹出层的自定义样式string / object
transition动画名称string
teleportedtooltip 内容是否使用 teleport,如果为 true,它将被传送至 append-to 设置的位置boolean
popper-optionspopper.js 参数object请参考 popper.js 文档
show-after延迟出现,单位毫秒number
hide-after延迟消失,单位毫秒number
auto-close隐藏提示框的超时毫秒数number
offsetTooltip 的偏移量number

Select 事件

名称描述类型
change选中值发生变化时触发Function
visible-change下拉框出现/隐藏时触发Function
remove-tag多选模式下移除标签时触发Function
clear在可清空的 Select 组件上点击清除图标时触发Function
blur在 Input 失去焦点时触发Function
focus在 Input 获得焦点时触发Function
弹出层滚动 2.9.4下拉菜单滚动时触发Function
滚动到底部 2.14.0下拉菜单滚动到底部时触发Function

Select 插槽

名称描述子标签
default选项组件列表选项组 / 选项
头部 2.4.3下拉列表顶部的内容
footer 2.4.3下拉列表底部的内容
prefix作为 Select 前缀的内容
empty无选项时的内容
tag 2.5.0Select 标签内容,subTags 的 `data`、`selectDisabled` 和 `deleteTag` 在 2.10.3 中引入object
loading 2.5.2Select 加载中的内容
label 2.7.4作为 Select 标签的内容。index2.11.2 中引入object

Select 暴露的方法

名称描述类型
focus使输入框获取焦点Function
blur使输入框失去焦点,并隐藏下拉框Function
selectedLabel 2.8.5获取当前选中的标签object

Option Group API

Option Group 属性

名称描述类型默认值
label组名string
disabled是否禁用该组内的所有选项booleanfalse

Option Group 插槽

名称描述子标签
default自定义默认内容选项

Option API

Option 属性

名称描述类型默认值
value选项的值string / number / boolean / object
label选项的标签,若省略则与 value 相同string / number
disabled是否禁用该选项booleanfalse

Option 插槽

名称描述
default自定义默认内容

来源

组件源码样式源码文档源码

贡献者