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
属性来改变选择器的大小。除了默认大小外,还有另外两个选项:large
、small
。
基础多选
多选使用标签来显示所选选项。
为 el-select
设置 multiple
属性即可启用多选,此时 v-model
的值为当前选中值所组成的数组。 默认情况下,多选的选择结果以标签 (Tag) 的形式展现,你也可以设置 collapse-tags
属性将它们合并为一段文字。 您可以通过设置 collapse-tags-tooltip
在鼠标悬停时展示所有已选中的标签。
自定义模板
您可以为选项自定义 HTML 模板。
将自定义的 HTML 模板插入 el-option
的插槽中。
下拉列表的头部 2.4.3
您可以自定义下拉列表的页眉。
使用插槽来自定义内容。
下拉列表的底部 2.4.3
您可以自定义下拉列表的页脚。
使用插槽来自定义内容。
分组
将选项分组展示。
使用 el-option-group
对备选项进行分组,它的 label
属性为分组名。
筛选选项
您可以筛选出您想要的选项。
为 el-select
添加 filterable
属性即可启用筛选功能。 默认情况下,Select 会找出所有 label
属性包含输入值的选项。 如果希望使用其他的搜索逻辑,可以通过传入一个 filter-method
来实现。 filter-method
是一个 Function
,它会在输入值发生变化时调用,参数为当前输入值。
远程搜索
输入关键字,并从服务器获取数据。
将 filterable
和 remote
设置为 true
来启用远程搜索,同时需要提供一个 remote-method
。 remote-method
是一个 Function
,它会在输入值发生变化时调用,参数为当前输入值。 需要注意的是,如果 el-option
是通过 v-for
指令渲染出来的,此时你需要为 el-option
添加 key
属性,且其值需具有唯一性,比如此例中的 item.value
。
创建新项目
创建并选择选择器选项中不包含的新项目
通过使用 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-tags
、collapse-tags-tooltip
、max-collapse-tags
将不起作用。
自定义加载 2.5.2
覆盖加载内容。
空值 2.7.0
如果您想支持空字符串,请将 empty-values
设置为 [null, undefined]
。
如果要将清除值更改为 null
,请将 value-on-clear
设置为 null
。
自定义标签 2.7.4
您可以自定义标签。
Select API
Select 属性
名称 | 描述 | 类型 | 默认值 |
---|---|---|---|
model-value / v-model | 绑定值 | string / number / boolean / object / array | — |
multiple | 是否多选 | boolean | false |
options 2.10.5 | 选项的数据,其中 value 和 label 和 disabled 的键名可以通过 props 自定义 | array | — |
props 2.10.5 | 配置选项 | object | — |
disabled | 是否禁用 | boolean | false |
value-key | 作为 value 唯一标识的键名,绑定值为对象类型时必填 | string | value |
size | 输入框尺寸 | 枚举 | — |
可清空 | 是否可以清空选项 | boolean | false |
collapse-tags | 多选时是否将选中值按文字的形式展示 | boolean | false |
collapse-tags-tooltip 2.3.0 | 当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,`collapse-tags` 属性必须设定为 true | boolean | false |
multiple-limit | 多选时用户最多可以选择的项目数, 为 0 则不限制 | number | 0 |
id | 原生输入框 id | string | — |
名称 | 选择器输入框的 name 属性 | string | — |
effect | tooltip 主题,内置主题:`dark` / `light` | enum / string | light |
自动补全 | 选择器输入框的 autocomplete 属性 | string | off |
占位符 | 占位符,默认值为“选择” | string | — |
filterable | 是否可筛选 | boolean | false |
allow-create | 是否允许用户创建新项目, 需配合 `filterable` 使用 | boolean | false |
filter-method | 自定义筛选方法,第一个参数是当前输入值。若要使用此属性,`filterable` 必须为 true | Function | — |
remote | 其中的选项是否从服务器远程加载 | boolean | false |
remote-method | 当输入值改变时调用的函数。 它的参数是当前的输入值。 若要使用此属性,`filterable` 必须为 true | Function | — |
remote-show-suffix | 在远程搜索方法中显示后缀图标 | boolean | false |
加载中 | 是否正在从远程获取数据 | boolean | false |
loading-text | 远程加载时显示的文字,默认为 '加载中' | string | — |
no-match-text | 搜索条件无匹配时显示的文字,也可以使用 `empty` 插槽,默认为 '无匹配数据' | string | — |
no-data-text | 选项为空时显示的文字,也可以使用 `empty` 插槽,默认为 '无数据' | string | — |
popper-class | Select 下拉框的自定义类名 | string | '' |
popper-style 2.11.0 | 为 Select 的下拉列表自定义样式 | string / object | — |
reserve-keyword | 当 `multiple` 和 `filterable` 为 true 时,是否在选中一个选项后保留当前的搜索关键词 | boolean | true |
default-first-option | 在输入框按下回车,选择第一个匹配项。需配合 `filterable` 或 `remote` 使用 | boolean | false |
teleported | 是否将下拉列表元素插入到 `append-to` 设置的元素中 | boolean | true |
append-to 2.8.4 | 下拉列表应该附加到哪个元素 | CSSSelector / HTMLElement | — |
persistent | 当下拉列表不活动且 `persistent` 为 `false` 时,下拉列表将被销毁 | boolean | true |
automatic-dropdown | 对于不可过滤的 Select 组件,此属性决定是否在输入框获得焦点后自动弹出选项菜单 | boolean | false |
clear-icon | 自定义清除图标组件 | string / object | CircleClose |
fit-input-width | 下拉框的宽度是否与输入框相同 | boolean | false |
后缀图标 | 自定义后缀图标组件 | string / object | ArrowDown |
tag-type | 标签类型 | 枚举 | 信息 |
tag-effect 2.7.7 | 标签效果 | 枚举 | light |
validate-event | 是否触发表单验证 | boolean | true |
offset 2.8.8 | 下拉列表的偏移量 | number | 12 |
show-arrow 2.8.8 | 下拉列表是否带有箭头 | boolean | true |
placement 2.2.17 | 下拉框出现的位置 | 枚举 | 下左 |
fallback-placements 2.5.6 | 当下拉列表空间不足时,可使用的备用位置列表 popper.js | array | ['bottom-start', 'top-start', 'right', 'left'] |
max-collapse-tags 2.3.0 | 要显示的最大标签数。 要使用此属性,`collapse-tags` 必须为 true | number | 1 |
popper-options | popper.js 参数 | object 请参考 popper.js 文档 | {} |
aria-label 无障碍 | 与原生输入框的 `aria-label` 相同 | string | — |
empty-values 2.7.0 | 组件的空值,参见 config-provider | array | — |
value-on-clear 2.7.0 | 清除后的返回值,参见 config-provider | string / number / boolean / Function | — |
suffix-transition 已废弃 | 下拉框出现/消失图标时的动画 | boolean | true |
tabindex 2.9.0 | 输入框的 tabindex | string / number | — |
警告
suffix-transition
已被 **废弃**,并 **将** 在 2.4.0 版本中被移除,请使用覆盖样式方案。
props
属性 | 描述 | 类型 | 默认值 |
---|---|---|---|
value | 指定节点对象的哪个键用作节点的值 | string | value |
label | 指定节点对象的哪个键用作节点的标签 | string | label |
options 2.11.0 | 指定节点对象的哪个键用作节点的子节点 | string | options |
disabled | 指定节点对象的哪个键用作节点的禁用 | string | disabled |
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 | 下拉列表底部的内容 | — |
prefix | Select 组件头部内容 | — |
empty | 无选项时的内容 | — |
tag 2.5.0 | Select 标签内容,subTags 的 `data`、`selectDisabled` 和 `deleteTag` 在 2.10.3 中引入 | object |
loading 2.5.2 | Select 加载中的内容 | — |
label 2.7.4 | Select 标签内容 | — |
Select Exposes
名称 | 描述 | 类型 |
---|---|---|
focus | 使输入框获取焦点 | Function |
blur | 使输入框失去焦点,并隐藏下拉框 | Function |
selectedLabel 2.8.5 | 获取当前选中的标签 | object |
Option Group API
Option Group 属性
名称 | 描述 | 类型 | 默认值 |
---|---|---|---|
label | 分组的名称 | string | — |
disabled | 是否禁用该分组下的所有选项 | boolean | false |
Option Group 插槽
名称 | 描述 | 子标签 |
---|---|---|
default | 自定义默认内容 | Option |
Option API
Option 属性
名称 | 描述 | 类型 | 默认值 |
---|---|---|---|
value | 选项的值 | string / number / boolean / object | — |
label | 选项的标签,若不设置则默认与 `value` 相同 | string / number | — |
disabled | 是否禁用该选项 | boolean | false |
Option 插槽
名称 | 描述 |
---|---|
default | 自定义默认内容 |