Select 选择器

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

提示

el-select 的默认宽度更改为 100%。当使用内联形式时，宽度可能显示异常。为了保持显示正常，您需要手动配置 el-select 的宽度（如: 例子）。

import { createApp } from 'vue'
import { ElSelect } from '@szhn/dh-design-pc'

const app = createApp()
app.use(ElSelect)

基础用法

Options 属性

有禁用选项

禁用状态

禁用整个选择器组件

可清空

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

尺寸

基础多选

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

自定义模板

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

自定义下拉菜单的头部

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

自定义下拉菜单的底部

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

将选项进行分组

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

筛选选项

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

远程搜索

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

创建新的选项

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

使用值键 value-key 属性

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

自定义标签

您可以自定义标签。

自定义加载

修改加载区域内容

空值配置

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

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

自定义标签

您可以自定义标签

Select API

Select Attributes

属性名	说明	类型	Default
model-value / v-model	选中项绑定值	string / number / boolean / object / array	—
multiple	是否多选	boolean	false
options	选项的数据源， `value` 的 key 和 `label` 和 `disabled`可以通过 `props`自定义.	array	—
props	options 的配置	object	—
disabled	是否禁用	boolean	false
value-key	作为 value 唯一标识的键名，绑定值为对象类型时必填	string	value
size	输入框尺寸	enum	—
clearable	是否可以清空选项	boolean	false
collapse-tags	多选时是否将选中值按文字的形式展示	boolean	false
collapse-tags-tooltip	当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。要使用此属性，`collapse-tags`属性必须设定为 true	boolean	false
tag-tooltip	折叠标签工具提示的配置对象。要使用此项， `collapse-tags` 和 `collapse-tags-tooltip` 必须为 true	object	{}
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	远程搜索时的防抖延迟（以毫秒为单位）	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	为 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	下拉框挂载到哪个 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	标签效果	enum	light
validate-event	是否触发表单验证	boolean	true
offset	下拉面板偏移量	number	4
show-arrow	下拉菜单的内容是否有箭头	boolean	false
placement	下拉框出现的位置	enum	bottom-start
fallback-placements	dropdown 可用的 positions 请查看popper.js 文档	array	['bottom-start', 'top-start', 'right', 'left']
max-collapse-tags	需要显示的 Tag 的最大数量只有当 `collapse-tags` 设置为 true 时才会生效。	number	1
popper-options	popper.js 参数	object	{}
aria-label a11y	等价于原生 input `aria-label` 属性	string	—
empty-values	组件的空值配置，参考config-provider	array	—
value-on-clear	清空选项的值，参考config-provider	string / number / boolean / Function	—
suffix-transition deprecated	下拉菜单显示/消失时后缀图标的动画	boolean	true
tabindex	input 的 tabindex	string / number	—

注意

suffix-transition 已被弃用，之后将会被删除，请使用覆盖样式方案。

Props

Attribute	说明	Type	Default
value	指定选项的值为选项对象的某个属性值	string	value
label	指定节点标签为节点对象的某个属性值	string	label
options	指定选项的子选项为选项对象的某个属性值	string	options
disabled	指定选项的禁用为选项对象的某个属性值	string	disabled

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

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

属性	说明	类型	默认值
append-to	指示 Tooltip 的内容将附加在哪一个网页元素上	CSSSelector / HTMLElement	—
placement	Tooltip 组件出现的位置	enum	bottom
fallback-placements	Tooltip 可用的 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	—
transition	Tooltip 所应用过渡动画的名称	string	—
teleported	是否使用 teleport。设置成 `true`则会被追加到 `append-to` 的位置	boolean	—
popper-options	popper.js 参数	object	—
show-after	在触发后多久显示内容，单位毫秒	number	—
hide-after	关闭时的延迟	number	—
auto-close	tooltip 出现后自动隐藏延时，单位毫秒	number	—
offset	Tooltip 出现位置的偏移量	number	—

Select Events

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

Select Slots

插槽名	说明	子标签
default	option 组件列表	Option Group / Option
header	下拉列表顶部的内容	—
footer	下拉列表底部的内容	—
prefix	Select 组件头部内容	—
empty	无选项时的列表	—
tag	作为 Select 组件的内容时，子标签支持 `data`、`selectDisabled` 和 `deleteTag`。	object
loading	select 组件自定义 loading内容	—
label	select 组件自定义标签内容，支持 `index`。	object

Select Exposes

方法名	详情	类型
focus	使选择器的输入框获取焦点	Function
blur	使选择器的输入框失去焦点，并隐藏下拉框	Function
selectedLabel	获取当前选中的标签	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	默认插槽内容

Select 选择器 ​

基础用法 ​

Options 属性 ​

有禁用选项 ​

禁用状态 ​

可清空 ​

尺寸 ​

基础多选 ​

自定义模板 ​

自定义下拉菜单的头部 ​

自定义下拉菜单的底部 ​

将选项进行分组 ​

筛选选项 ​

远程搜索 ​

创建新的选项 ​

使用值键 value-key 属性 ​

自定义标签 ​

自定义加载 ​

空值配置 ​

自定义标签 ​

Select API ​

Select Attributes ​

Props ​

tag-tooltip ​

Select Events ​

Select Slots ​

Select Exposes ​

Option Group API ​

Option Group Attributes ​

Option Group Slots ​

Option API ​

Option Attributes ​

Option Slots ​

Select 选择器

基础用法

Options 属性

有禁用选项

禁用状态

可清空

尺寸

基础多选

自定义模板

自定义下拉菜单的头部

自定义下拉菜单的底部

将选项进行分组

筛选选项

远程搜索

创建新的选项

使用值键 value-key 属性

自定义标签

自定义加载

空值配置

自定义标签

Select API

Select Attributes

Props

tag-tooltip

Select Events

Select Slots

Select Exposes

Option Group API

Option Group Attributes

Option Group Slots

Option API

Option Attributes

Option Slots