Select 选择器
当选项过多时，使用下拉菜单展示并选择内容。
TIP
在版本 2.5.0之后， el-select 的默认宽度更改为 100% 当使用内联形式时，宽度将显示异常。 为了保持显示正常, 您需要手动配置 el-select 的宽度 (如: 例子).
基础用法
Options 属性 2.10.5
有禁用选项
禁用状态
禁用整个选择器组件
可清空
您可以使用清除图标来清除选择。
尺寸
基础多选
多选选择器使用 tag 组件来展示已选中的选项。
自定义模板
你可以自定义如何来渲染每一个选项。
自定义下拉菜单的头部 2.4.3
您可以自定义下拉菜单的头部。
自定义下拉菜单的底部 2.4.3
您可以自定义下拉菜单的底部。
将选项进行分组
你可以为选项进行分组来区分不同的选项
筛选选项
可以利用筛选功能快速查找选项。
远程搜索
输入关键字以从远程服务器中查找数据。
创建新的选项
创建并选中未包含在初始选项中的条目。
使用值键 value-key 属性
如果 Select 的绑定值为对象类型，请务必指定 value-key 作为它的唯一性标识。
自定义标签 2.5.0
您可以自定义标签。
自定义加载 2.5.2
修改加载区域内容
空值配置2.7.0
若想配置如空字符串为有效值而不是空值，可以配置 empty-values 为 [null, undefined].
如果您想要将清空值更改为 null, 请设置 value-on-clear 为 null
自定义标签 2.7.4
您可以自定义标签
Select API
Select Attributes
| 属性名 | 说明 | 类型 | Default |
|---|---|---|---|
| model-value / v-model | 选中项绑定值 | string / number / boolean / object / array | — |
| multiple | 是否多选 | boolean | false |
| options 2.10.5 | 选项的数据源， value 的 key 和 label 和 disabled可以通过 props自定义. | array | — |
| props 2.10.5 | options 的配置 | object | — |
| disabled | 是否禁用 | boolean | false |
| value-key | 作为 value 唯一标识的键名，绑定值为对象类型时必填 | string | value |
| size | 输入框尺寸 | enum | — |
| clearable | 是否可以清空选项 | boolean | false |
| collapse-tags | 多选时是否将选中值按文字的形式展示 | boolean | false |
| collapse-tags-tooltip 2.3.0 | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，collapse-tags属性必须设定为 true | boolean | false |
| multiple-limit | multiple 属性设置为 true 时，代表多选场景下用户最多可以选择的项目数， 为 0 则不限制 | number | 0 |
| id | 原生 input 的 id | string | — |
| name | Select 输入框的原生 name 属性 | string | — |
| effect | tooltip 主题，内置了 dark / light 两种 | enum / string | light |
| autocomplete | Select 输入框的原生 autocomplete 属性 | string | off |
| placeholder | 占位符，默认为“Select” | string | — |
| filterable | Select 组件是否可筛选 | boolean | false |
| allow-create | 是否允许用户创建新条目， 只有当 filterable 设置为 true 时才会生效。 | boolean | false |
| filter-method | 自定义筛选方法的第一个参数是当前输入的值。 当filterable设置为 true 时才会生效 | Function | — |
| remote | 其中的选项是否从服务器远程加载 | boolean | false |
| debounce 2.11.7 | 远程搜索时的防抖延迟（以毫秒为单位） | number | 300 |
| remote-method | 当输入值发生变化时触发的函数。 它的参数就是当前的输入值。 当filterable设置为 true 时才会生效 | Function | — |
| remote-show-suffix | 远程搜索方法显示后缀图标 | boolean | false |
| loading | 是否正在从远程获取数据 | boolean | false |
| 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 时，是否在选中一个选项后保留当前的搜索关键词 | boolean | true |
| default-first-option | 是否在输入框按下回车时，选择第一个匹配项。 需配合 filterable 或 remote 使用 | boolean | false |
| teleported | 是否使用 teleport。设置成 true则会被追加到 append-to 的位置 | boolean | true |
| append-to 2.8.4 | 下拉框挂载到哪个 DOM 元素 | CSSSelector / HTMLElement | — |
| persistent | 当下拉选择器未被激活并且persistent设置为false，选择器会被删除。 | boolean | true |
| automatic-dropdown | 对于不可搜索的 Select，是否在输入框获得焦点后自动弹出选项菜单 | boolean | false |
| clear-icon | 自定义清除图标 | string / object | CircleClose |
| fit-input-width | 下拉框的宽度是否与输入框相同 | boolean | false |
| suffix-icon | 自定义后缀图标组件 | string / object | ArrowDown |
| tag-type | 标签类型 | enum | info |
| tag-effect 2.7.7 | 标签效果 | enum | light |
| validate-event | 是否触发表单验证 | boolean | true |
| offset 2.8.8 | 下拉面板偏移量 | number | 12 |
| show-arrow 2.8.8 | 下拉菜单的内容是否有箭头 | boolean | true |
| placement 2.2.17 | 下拉框出现的位置 | enum | bottom-start |
| fallback-placements 2.5.6 | dropdown 可用的 positions 请查看popper.js 文档 | array | ['bottom-start', 'top-start', 'right', 'left'] |
| max-collapse-tags 2.3.0 | 需要显示的 Tag 的最大数量 只有当 collapse-tags 设置为 true 时才会生效。 | number | 1 |
| popper-options | popper.js 参数 | objectrefer to popper.js doc | {} |
| aria-label a11y | 等价于原生 input 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 deprecated | 下拉菜单显示/消失时后缀图标的动画 | boolean | true |
| tabindex 2.9.0 | input 的 tabindex | string / number | — |
WARNING
suffix-transition 已被 弃用, 并 将会 在2.4.0中删除, 请使用覆盖样式方案。
Props
| Attribute | 说明 | Type | Default |
|---|---|---|---|
| value | 指定选项的值为选项对象的某个属性值 | string | value |
| label | 指定节点标签为节点对象的某个属性值 | string | label |
| options 2.11.0 | 指定选项的子选项为选项对象的某个属性值 | string | options |
| disabled | 指定选项的禁用为选项对象的某个属性值 | string | disabled |
Select Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 选中值发生变化时触发 | Function |
| visible-change | 下拉框出现/隐藏时触发 | Function |
| remove-tag | 多选模式下移除tag时触发 | Function |
| clear | 可清空的单选模式下用户点击清空按钮时触发 | Function |
| blur | 当 input 失去焦点时触发 | Function |
| focus | 当 input 获得焦点时触发 | Function |
| popup-scroll 2.9.4 | 下拉滚动时触发 | Function |
Select Slots
| 插槽名 | 说明 | 子标签 |
|---|---|---|
| default | option 组件列表 | Option Group / Option |
| header 2.4.3 | 下拉列表顶部的内容 | — |
| footer 2.4.3 | 下拉列表底部的内容 | — |
| prefix | Select 组件头部内容 | — |
| empty | 无选项时的列表 | — |
| tag 2.5.0 | 作为 Select 组件的内容时，子标签 data、selectDisabled 和 deleteTag 是在版本 2.10.3 中新增的。 | object |
| loading 2.5.2 | select 组件自定义 loading内容 | — |
| label 2.7.4 | select 组件自定义标签内容 index 引入于2.11.2 | object |
Select Exposes
| 方法名 | 说明 | Type |
|---|---|---|
| focus | 使选择器的输入框获取焦点 | Function |
| blur | 使选择器的输入框失去焦点，并隐藏下拉框 | Function |
| selectedLabel 2.8.5 | 获取当前选中的标签 | object |
Option Group API
Option Group Attributes
| 名称 | 详情 | 类型 | 默认值 |
|---|---|---|---|
| label | 分组的名称 | string | — |
| disabled | 是否将该分组下所有选项置为禁用 | boolean | false |
Option Group Slots
| 插槽名 | 详情 | Subtags |
|---|---|---|
| default | 自定义默认内容 | Option |
Option API
Option Attributes
| Name | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 选项的值 | string / number / boolean / object | — |
| label | 选项的标签，若不设置则默认与value相同 | string / number | ::: |
| disabled | 是否禁用该选项 | boolean | false |
Option Slots
| 名称 | 描述 |
|---|---|
| default | 默认插槽内容 |
源代码
贡献者
