Select 选择器

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

提示

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

基础用法

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

选择器

Options 属性 2.10.5

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

选择器

禁用选项

el-option 中,设定 disabled 值为 true,即可禁用该选项。

选择器

禁用选择器

禁用整个组件。

el-select 设置 disabled 属性,则整个选择器不可用。

选择器

可清空

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

el-select 设置 clearable 属性,则可将选择器清空。需要注意的是,clearable 属性仅适用于单选。

选择器

尺寸

添加 size 属性来改变选择器的大小。除了默认大小外,还有另外两个选项:largesmall

选择器
选择器
选择器

基础多选

多选使用标签来显示所选选项。

el-select 设置 multiple 属性即可启用多选,此时 v-model 的值为当前选中值所组成的数组。 默认情况下,多选的选择结果以标签 (Tag) 的形式展现,你也可以设置 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 属性即可启用筛选功能。 默认情况下,Select 会找出所有 label 属性包含输入值的选项。 如果希望使用其他的搜索逻辑,可以通过传入一个 filter-method 来实现。 filter-method 是一个 Function,它会在输入值发生变化时调用,参数为当前输入值。

选择器

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

filterableremote 设置为 true 来启用远程搜索,同时需要提供一个 remote-methodremote-method 是一个 Function,它会在输入值发生变化时调用,参数为当前输入值。 需要注意的是,如果 el-option 是通过 v-for 指令渲染出来的,此时你需要为 el-option 添加 key 属性,且其值需具有唯一性,比如此例中的 item.value

default

请输入关键词

使用 remote-show-suffix

请输入关键词

创建新项目

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

通过使用 allow-create 属性,用户可以通过在输入框中键入来创建新项目。请注意,要使 allow-create 生效,filterable 必须为 true。此示例还演示了 default-first-option。当此属性设置为 true 时,您可以通过按 Enter 键选择当前选项列表中的第一个选项,而无需使用鼠标或箭头键进行导航。

为你的文章选择标签

使用 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
options 2.10.5选项的数据,其中 valuelabeldisabled 的键名可以通过 props 自定义array
props 2.10.5配置选项object
disabled是否禁用booleanfalse
value-key作为 value 唯一标识的键名,绑定值为对象类型时必填stringvalue
size输入框尺寸枚举
可清空是否可以清空选项booleanfalse
collapse-tags多选时是否将选中值按文字的形式展示booleanfalse
collapse-tags-tooltip 2.3.0当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,`collapse-tags` 属性必须设定为 truebooleanfalse
multiple-limit多选时用户最多可以选择的项目数, 为 0 则不限制number0
id原生输入框 idstring
名称选择器输入框的 name 属性string
effecttooltip 主题,内置主题:`dark` / `light`enum / stringlight
自动补全选择器输入框的 autocomplete 属性stringoff
占位符占位符,默认值为“选择”string
filterable是否可筛选booleanfalse
allow-create是否允许用户创建新项目, 需配合 `filterable` 使用booleanfalse
filter-method自定义筛选方法,第一个参数是当前输入值。若要使用此属性,`filterable` 必须为 trueFunction
remote其中的选项是否从服务器远程加载booleanfalse
remote-method当输入值改变时调用的函数。 它的参数是当前的输入值。 若要使用此属性,`filterable` 必须为 trueFunction
remote-show-suffix在远程搜索方法中显示后缀图标booleanfalse
加载中是否正在从远程获取数据booleanfalse
loading-text远程加载时显示的文字,默认为 '加载中'string
no-match-text搜索条件无匹配时显示的文字,也可以使用 `empty` 插槽,默认为 '无匹配数据'string
no-data-text选项为空时显示的文字,也可以使用 `empty` 插槽,默认为 '无数据'string
popper-classSelect 下拉框的自定义类名string''
popper-style 2.11.0为 Select 的下拉列表自定义样式string / object
reserve-keyword当 `multiple` 和 `filterable` 为 true 时,是否在选中一个选项后保留当前的搜索关键词booleantrue
default-first-option在输入框按下回车,选择第一个匹配项。需配合 `filterable` 或 `remote` 使用booleanfalse
teleported是否将下拉列表元素插入到 `append-to` 设置的元素中booleantrue
append-to 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
placement 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
suffix-transition 已废弃下拉框出现/消失图标时的动画booleantrue
tabindex 2.9.0输入框的 tabindexstring / number

警告

suffix-transition 已被 **废弃**,并 **将** 在 2.4.0 版本中被移除,请使用覆盖样式方案。

props

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

Select 事件

名称描述类型
change选中值改变时触发Function
visible-change下拉框出现/隐藏时触发Function
remove-tag多选模式下移除tag时触发Function
clear在可清空的 Select 组件上点击清除图标时触发Function
blur在 Input 失去焦点时触发Function
focus在 Input 获得焦点时触发Function
popup-scroll 2.9.4下拉列表滚动时触发Function

Select 插槽

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

Select Exposes

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

Option Group API

Option Group 属性

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

Option Group 插槽

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

Option API

Option 属性

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

Option 插槽

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

来源

组件样式文档

贡献者