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 属性可以更改选择器的尺寸。除了默认尺寸外,还有两个选项:large 和 small。
基础多选
多选模式下使用标签展示已选项。
为 el-select 设置 multiple 属性即可启用多选模式。此时,v-model 的值将为已选项组成的数组。默认情况下,已选项将以标签形式显示。你可以使用 collapse-tags 属性将它们合并为文本。使用 collapse-tags-tooltip 属性可以在鼠标悬停合并文本时查看它们。
自定义模板
你可以自定义选项的 HTML 模板。
将自定义 HTML 模板插入到 el-option 的插槽中。
下拉菜单头部 2.4.3
您可以自定义下拉列表的页眉。
使用插槽来自定义内容。
下拉菜单底部 2.4.3
您可以自定义下拉列表的页脚。
使用插槽来自定义内容。
分组
分组展示选项。
使用 el-option-group 对选项进行分组,其 label 属性代表组名。
选项筛选
你可以过滤出想要的选项。
为 el-select 添加 filterable 属性即可启用筛选功能。默认情况下,选择器会查找所有 label 属性包含输入值的选项。如果你倾向于其他筛选策略,可以传入 filter-method。filter-method 是一个函数,当输入值发生变化时被调用,其参数为当前输入值。
远程搜索
输入关键字,并从服务器获取数据。
将 filterable 和 remote 设置为 true 即可启用远程搜索,同时你应该传入 remote-method。remote-method 是一个函数,当输入值发生变化时被调用,其参数为当前输入值。注意,如果 el-option 是使用 v-for 指令渲染的,你应该为 el-option 添加 key 属性。其值必须是唯一的,例如下例中的 item.value。
创建新项目
创建并选择选择器选项中不包含的新项目
通过使用 allow-create 属性,用户可以通过在输入框中输入来创建新项目。注意,要使 allow-create 生效,filterable 必须为 true。本例还展示了 default-first-option。当此属性设置为 true 时,无需使用鼠标或方向键导航,只需按回车键即可选中当前选项列表中的第一个选项。
使用 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 |
| 选项数据 2.10.5 | 选项数据,其中 `value` 和 `label` 和 `disabled` 的键名可以通过 `props` 自定义 | array | — |
| 属性配置 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 |
| 标签文字提示 2.13.3 | collapse-tags 文字提示的配置对象。要使用此功能,collapse-tags 和 collapse-tags-tooltip 必须为 true | object | {} |
| multiple-limit | 当 multiple 为 true 时,用户最多可以选择的选项数。设置为 0 则不限制 | number | 0 |
| id | 原生输入框 id | string | — |
| 名称 | 选择器输入框的 name 属性 | string | — |
| effect | tooltip 主题,内置主题:`dark` / `light` | enum / string | light |
| 自动补全 | 选择器输入框的 autocomplete 属性 | string | off |
| 占位符 | 占位文字,默认为 'Select' | string | — |
| filterable | 是否可筛选 | boolean | false |
| allow-create | 是否允许用户创建新项目, 需配合 `filterable` 使用 | boolean | false |
| filter-method | 自定义筛选方法,第一个参数是当前输入值。要使用此功能,filterable 必须为 true | Function | — |
| remote | 是否从服务器加载选项 | boolean | false |
| 防抖 2.11.7 | 远程搜索时的防抖延迟,单位为毫秒 | number | 300 |
| remote-method | 当输入值改变时调用的函数。 它的参数是当前的输入值。 若要使用此属性,`filterable` 必须为 true | Function | — |
| remote-show-suffix | 在远程搜索方法中显示后缀图标 | boolean | false |
| 加载中 | 是否正在从远程获取数据 | boolean | false |
| 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-keyword | 当 multiple 和 filterable 为 true 时,选中一个选项后是否保留当前关键词 | boolean | true |
| default-first-option | 在输入框按下回车,选择第一个匹配项。需配合 `filterable` 或 `remote` 使用 | boolean | false |
| teleported | 是否将下拉列表元素插入到 `append-to` 设置的元素中 | boolean | true |
| 插入至 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 |
| 出现位置 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 | — |
| 后缀过渡 已废弃 | 下拉菜单图标出现/消失时的动画 | boolean | true |
| tabindex 2.9.0 | 输入框的 tabindex | string / number | — |
警告
suffix-transition 已废弃,并将于 2.4.0 移除,请使用覆盖样式方案。
props
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| value | 指定节点对象的哪个键用作节点的值 | string | value |
| label | 指定节点对象的哪个键用作节点的标签 | string | label |
| 选项 2.11.0 | 指定节点对象的哪个键用作节点的子节点 | string | options |
| disabled | 指定节点对象的哪个键用作节点的禁用 | string | disabled |
标签文字提示 2.13.3
回退机制
tag-tooltip 中的属性遵循以下优先级顺序
- tag-tooltip 对象中显式定义的字段。
- 从 el-select 继承的共享属性(例如 effect, popper-class, popper-style, teleported, append-to, popper-options)。
- 底层 el-tooltip 组件的默认值。这允许你为标签覆盖特定的 tooltip 行为,同时默认情况下保持与 Select 下拉菜单的一致性。
自定义容器定位
当将 Tooltip 附加到自定义容器(通过 append-to 属性)时,该容器应配置为 position: relative 或 position: absolute 以确保精确定位。此外,如果你需要防止 Tooltip 超出其边界,可以为容器应用 overflow: hidden。
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| append-to | tooltip 内容插入至哪个元素 | CSSSelector / HTMLElement | — |
| placement | Tooltip 的出现位置 | 枚举 | bottom |
| fallback-placements | 文字提示可能出现的位置列表 popper.js | array | ['bottom', 'top', 'right', 'left'] |
| effect | Tooltip 的主题,内置主题:`dark` / `light` | enum / string | — |
| popper-class | Tooltip 弹出层的自定义类名 | string | — |
| popper-style | Tooltip 弹出层的自定义样式 | string / object | — |
| transition | 动画名称 | string | — |
| teleported | tooltip 内容是否使用 teleport,如果为 true,它将被传送至 append-to 设置的位置 | boolean | — |
| popper-options | popper.js 参数 | object请参考 popper.js 文档 | — |
| show-after | 延迟出现,单位毫秒 | number | — |
| hide-after | 延迟消失,单位毫秒 | number | — |
| auto-close | 隐藏提示框的超时毫秒数 | number | — |
| offset | Tooltip 的偏移量 | 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.0 | Select 标签内容,subTags 的 `data`、`selectDisabled` 和 `deleteTag` 在 2.10.3 中引入 | object |
| loading 2.5.2 | Select 加载中的内容 | — |
| label 2.7.4 | 作为 Select 标签的内容。index 在 2.11.2 中引入 | object |
Select 暴露的方法
| 名称 | 描述 | 类型 |
|---|---|---|
| focus | 使输入框获取焦点 | Function |
| blur | 使输入框失去焦点,并隐藏下拉框 | Function |
| selectedLabel 2.8.5 | 获取当前选中的标签 | object |
Option Group API
Option Group 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| label | 组名 | string | — |
| disabled | 是否禁用该组内的所有选项 | boolean | false |
Option Group 插槽
| 名称 | 描述 | 子标签 |
|---|---|---|
| default | 自定义默认内容 | 选项 |
Option API
Option 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| value | 选项的值 | string / number / boolean / object | — |
| label | 选项的标签,若省略则与 value 相同 | string / number | — |
| disabled | 是否禁用该选项 | boolean | false |
Option 插槽
| 名称 | 描述 |
|---|---|
| default | 自定义默认内容 |