Select 选择器
当选项过多时,使用下拉菜单展示并选择内容。
TIP
在版本 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 属性,则可将选择器清空。
尺寸
使用 size 属性改变选择器大小。 除了默认大小外,还有另外两个选项: large, small。
基础多选
多选选择器使用 tag 组件来展示已选中的选项。
为 el-select 设置 multiple 属性即可启用多选, 此时 v-model 的值为当前选中值所组成的数组。 默认情况下选中值会以 Tag 组件的形式展现, 你也可以设置 collapse-tags 属性将它们合并为一段文字。 您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。
自定义模板
你可以自定义如何来渲染每一个选项。
将自定义的 HTML 模板插入 el-option 的 slot 中即可。
自定义下拉菜单的头部 2.4.3
您可以自定义下拉菜单的头部。
Use slot to customize the content.
自定义下拉菜单的底部 2.4.3
您可以自定义下拉菜单的底部。
使用slot 自定义内容
将选项进行分组
你可以为选项进行分组来区分不同的选项
使用 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 的情况下,按下回车就可以选中当前选项列表中的第一个选项,无需使用鼠标或键盘方向键进行定位。
使用值键 value-key 属性
如果 Select 的绑定值为对象类型,请务必指定 value-key 作为它的唯一性标识。
通过使用 value-key 属性,可以正确处理带有重复label的数据。 这样虽然label 是重复的,但任可通过 id 来确认唯一性。
自定义标签 2.5.0
您可以自定义标签。
将自定义的标签插入 el-select 的 slot 中即可。 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 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 |
| 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 | 默认插槽内容 |