Select 选择器 ​

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

TIP

在版本 2.5.0之后, el-select 的默认宽度更改为 100% 当使用内联形式时,宽度将显示异常。为了保持显示正常, 您需要手动配置 el-select 的宽度 (如: 例子).

基础用法 ​

适用广泛的基础单选 v-model 的值为当前被选中的 el-option 的 value 属性值

Select

Options 属性 2.10.5 ​

el-option 基本用法。您可以通过 props 属性自定义 options 的别名。

Select

有禁用选项 ​

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

Select

禁用状态 ​

禁用整个选择器组件

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

Select

可清空 ​

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

为 el-select 设置 clearable 属性,则可将选择器清空。

Select

尺寸 ​

使用 size 属性改变选择器大小。除了默认大小外,还有另外两个选项: large, small。

Select
Select
Select

基础多选 ​

多选选择器使用 tag 组件来展示已选中的选项。

为 el-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

自定义模板 ​

你可以自定义如何来渲染每一个选项。

将自定义的 HTML 模板插入 el-option 的 slot 中即可。

Select

自定义下拉菜单的头部 2.4.3 ​

您可以自定义下拉菜单的头部。

Use slot to customize the content.

Select

自定义下拉菜单的底部 2.4.3 ​

您可以自定义下拉菜单的底部。

使用slot 自定义内容

Select

将选项进行分组 ​

你可以为选项进行分组来区分不同的选项

使用 el-option-group 对备选项进行分组,它的 label 属性为分组名

Select

筛选选项 ​

可以利用筛选功能快速查找选项。

为el-select添加filterable属性即可启用搜索功能。默认情况下,Select 会找出所有 label 属性包含输入值的选项。如果希望使用其他的搜索逻辑,可以通过传入一个 filter-method 来实现。 filter-method 为一个 Function,它会在输入值发生变化时调用,参数为当前输入值。

Select

远程搜索 ​

输入关键字以从远程服务器中查找数据。

从服务器搜索数据,输入关键字进行查找。为了启用远程搜索,需要将filterable和remote设置为true,同时传入一个remote-method。 remote-method为一个Function,它会在输入值发生变化时调用,参数为当前输入值。需要注意的是,如果 el-option 是通过 v-for 指令渲染出来的,此时需要为 el-option 添加 key 属性,且其值需具有唯一性,比如这个例子中的 item.value。

default

Please enter a keyword

use remote-show-suffix

Please enter a keyword

创建新的选项 ​

创建并选中未包含在初始选项中的条目。

通过使用 allow-create 属性,用户可以通过输入框创建新项目。为了使 allow-create 正常工作, filterable 的值必须为 true。本例还使用了 default-first-option 属性,在该属性为 true 的情况下,按下回车就可以选中当前选项列表中的第一个选项,无需使用鼠标或键盘方向键进行定位。

Choose tags for your article

使用值键 value-key 属性 ​

如果 Select 的绑定值为对象类型,请务必指定 value-key 作为它的唯一性标识。

通过使用 value-key 属性,可以正确处理带有重复label的数据。这样虽然label 是重复的,但任可通过 id 来确认唯一性。

Select

selected option's description: no select

自定义标签 2.5.0 ​

您可以自定义标签。

将自定义的标签插入 el-select 的 slot 中即可。 collapse-tags, collapse-tags-tooltip, max-collapse-tags 在此模式下不生效.

自定义加载 2.5.2 ​

修改加载区域内容

loading icon1

Please enter a keyword

loading icon2

Please enter a keyword

空值配置2.7.0 ​

若想配置如空字符串为有效值而不是空值,可以配置 empty-values 为 [null, undefined].

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

自定义标签 2.7.4 ​

您可以自定义标签

: Option1

Select API ​

Select Attributes ​

属性名说明类型Default
model-value / v-model选中项绑定值string / number / boolean / object / array—
multiple是否多选booleanfalse
options 2.10.5选项的数据源, value 的 key 和 label 和 disabled可以通过 props自定义.array—
props 2.10.5options 的配置object—
disabled是否禁用booleanfalse
value-key作为 value 唯一标识的键名,绑定值为对象类型时必填stringvalue
size输入框尺寸enum—
clearable是否可以清空选项booleanfalse
collapse-tags多选时是否将选中值按文字的形式展示booleanfalse
collapse-tags-tooltip 2.3.0当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。要使用此属性,collapse-tags属性必须设定为 truebooleanfalse
tag-tooltip 2.13.3折叠标签工具提示的配置对象。要使用此项, collapse-tags 和 collapse-tags-tooltip 必须为 trueobject{}
multiple-limitmultiple 属性设置为 true 时,代表多选场景下用户最多可以选择的项目数,为 0 则不限制number0
id原生 input 的 idstring—
nameSelect 输入框的原生 name 属性string—
effecttooltip 主题,内置了 dark / light 两种enum / stringlight
autocompleteSelect 输入框的原生 autocomplete 属性stringoff
placeholder占位符,默认为“Select”string—
filterableSelect 组件是否可筛选booleanfalse
allow-create是否允许用户创建新条目,当filterable设置为 true 时才会生效booleanfalse
filter-method自定义筛选方法的第一个参数是当前输入的值。只有当 filterable 设置为 true 时才会生效。Function—
remote其中的选项是否从服务器远程加载booleanfalse
debounce 2.11.7远程搜索时的防抖延迟(以毫秒为单位)number300
remote-method当输入值发生变化时触发的函数。它的参数就是当前的输入值。当filterable设置为 true 时才会生效Function—
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为 Select 下拉菜单和标签提示设置自定义类名string''
popper-style 2.11.0为 Select 下拉菜单和标签提示设置自定义样式string / object—
reserve-keyword当 multiple 和 filterable被设置为 true 时,是否在选中一个选项后保留当前的搜索关键词booleantrue
default-first-option是否在输入框按下回车时,选择第一个匹配项。需配合 filterable 或 remote 使用booleanfalse
teleported是否使用 teleport。设置成 true则会被追加到 append-to 的位置booleantrue
append-to 2.8.4下拉框挂载到哪个 DOM 元素CSSSelector / HTMLElement—
persistent当下拉选择器未被激活并且persistent设置为false,选择器会被删除。booleantrue
automatic-dropdown对于不可搜索的 Select,是否在输入框获得焦点后自动弹出选项菜单booleanfalse
clear-icon自定义清除图标string / objectCircleClose
fit-input-width下拉框的宽度是否与输入框相同booleanfalse
suffix-icon自定义后缀图标组件string / objectArrowDown
tag-type标签类型enuminfo
tag-effect 2.7.7标签效果enumlight
validate-event是否触发表单验证booleantrue
offset 2.8.8下拉面板偏移量number12
show-arrow 2.8.8下拉菜单的内容是否有箭头booleantrue
placement 2.2.17下拉框出现的位置enumbottom-start
fallback-placements 2.5.6dropdown 可用的 positions 请查看popper.js 文档array['bottom-start', 'top-start', 'right', 'left']
max-collapse-tags 2.3.0需要显示的 Tag 的最大数量只有当 collapse-tags 设置为 true 时才会生效。number1
popper-optionspopper.js 参数objectrefer to popper.js doc{}
aria-label a11y等价于原生 input aria-label 属性string—
empty-values 2.7.0组件的空值配置, 参考config-providerarray—
value-on-clear 2.7.0清空选项的值, 参考config-providerstring / number / boolean / Function—
suffix-transition deprecated下拉菜单显示/消失时后缀图标的动画booleantrue
tabindex 2.9.0input 的 tabindexstring / number—

WARNING

suffix-transition 已被 弃用, 并 将会 在中删除, 请使用覆盖样式方案。

Props ​

Attribute说明TypeDefault
value指定选项的值为选项对象的某个属性值stringvalue
label指定节点标签为节点对象的某个属性值stringlabel
options 2.11.0指定选项的子选项为选项对象的某个属性值stringoptions
disabled指定选项的禁用为选项对象的某个属性值stringdisabled

tag-tooltip 2.13.3 ​

备用机制

标签工具提示中的属性遵循此优先级顺序:

  1. 在标签工具提示对象中明确定义的字段。
  2. 从 el-select 继承的共享属性(例如 effect、popper-class、popper-style、teleported、append-to、popper-options)。
  3. 底层 el-tooltip 组件的默认值。这样,您就可以覆盖标签的特定工具提示行为,同时保持与默认的“选择”下拉菜单的一致性。

自定义容器位置

当将 Tooltip 添加到自定义容器时(通过 append-to 属性),应将容器配置为 position: relative 或 position: absolute,以确保准确定位。此外,如果需要防止工具提示超出其边界,可以对容器应用 overflow: hidden。

属性说明类型默认值
append-to指示 Tooltip 的内容将附加在哪一个网页元素上CSSSelector / HTMLElement—
placementTooltip 组件出现的位置enumbottom
fallback-placementsTooltip 可用的 positions 请查看popper.js 文档array['bottom', 'top', 'right', 'left']
effect文字提示(Tooltip)的主题,内置dark和light两种。enum / string—
popper-class为 Tooltip 的 popper 添加自定义类名string—
popper-style为 Tooltip 的 popper 添加自定义样式string / object—
transitionTooltip 所应用过渡动画的名称string—
teleported是否使用 teleport。设置成 true则会被追加到 append-to 的位置boolean—
popper-optionspopper.js 参数objectrefer to popper.js doc—
show-after在触发后多久显示内容,单位毫秒number—
hide-after关闭时的延迟number—
auto-closetooltip 出现后自动隐藏延时,单位毫秒number—
offsetTooltip 出现位置的偏移量number—

Select Events ​

事件名说明Type
change选中值发生变化时触发Function
visible-change下拉框出现/隐藏时触发Function
remove-tag多选模式下移除tag时触发Function
clear可清空的单选模式下用户点击清空按钮时触发Function
blur当 input 失去焦点时触发Function
focus当 input 获得焦点时触发Function
popup-scroll 2.9.4下拉滚动时触发Function
end-reached 2.14.0下拉滚动到结束时触发器Function

Select Slots ​

插槽名说明子标签
defaultoption 组件列表Option Group / Option
header 2.4.3下拉列表顶部的内容—
footer 2.4.3下拉列表底部的内容—
prefixSelect 组件头部内容—
empty无选项时的列表:::
tag 2.5.0作为 Select 组件的内容时,子标签 data、selectDisabled 和 deleteTag 是在版本 2.10.3 中新增的。object
loading 2.5.2select 组件自定义 loading内容—
label 2.7.4select 组件自定义标签内容 index 引入于2.11.2object

Select Exposes ​

方法名详情类型
focus使选择器的输入框获取焦点Function
blur使选择器的输入框失去焦点,并隐藏下拉框Function
selectedLabel 2.8.5获取当前选中的标签object

Option Group API ​

Option Group Attributes ​

名称详情类型默认值
label分组的名称string—
disabled是否将该分组下所有选项置为禁用booleanfalse

Option Group Slots ​

插槽名说明Subtags
default自定义默认内容Option

Option API ​

Option Attributes ​

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

Option Slots ​

名称说明
default默认插槽内容

源代码 ​

组件 • 样式 • 文档

贡献者 ​