Select 选择器

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

TIP

在 SSR 场景下,您需要将组件包裹在 <client-only></client-only> 之中 (如: Nuxt) 和 SSG (e.g: VitePress).

基础用法

适用广泛的基础单选 v-model 的值为当前被选中的 el-option 的 value 属性值

有禁用选项

el-option 中,设定 disabled 值为 true,即可禁用该选项

禁用状态

禁用整个选择器组件

el-select 设置 disabled属性,则整个选择器不可用。

可清空单选

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

el-select 设置 clearable 属性,则可将选择器清空。 需要注意的是,clearable 属性仅适用于单选。

基础多选

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

el-select 设置 multiple 属性即可启用多选, 此时 v-model 的值为当前选中值所组成的数组。 默认情况下选中值会以 Tag 组件的形式展现, 你也可以设置 collapse-tags 属性将它们合并为一段文字。 您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

default

use collapse-tags

use collapse-tags-tooltip

use max-collapse-tags

自定义模板

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

将自定义的 HTML 模板插入 el-option 的 slot 中即可。

将选项进行分组

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

使用 el-option-group 对备选项进行分组,它的 label 属性为分组名

筛选选项

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

el-select添加filterable属性即可启用搜索功能。 默认情况下,Select 会找出所有 label 属性包含输入值的选项。 如果希望使用其他的搜索逻辑,可以通过传入一个 filter-method 来实现。 filter-method 为一个 Function,它会在输入值发生变化时调用,参数为当前输入值。

远程搜索

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

从服务器搜索数据,输入关键字进行查找。为了启用远程搜索,需要将filterableremote设置为true,同时传入一个remote-methodremote-method为一个Function,它会在输入值发生变化时调用,参数为当前输入值。 需要注意的是,如果 el-option 是通过 v-for 指令渲染出来的,此时需要为 el-option 添加 key 属性, 且其值需具有唯一性,比如这个例子中的 item.value

default

use remote-show-suffix

创建新的选项

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

通过使用 allow-create 属性,用户可以通过输入框创建新项目。 为了使 allow-create 正常工作, filterable 的值必须为 true。 本例还使用了 default-first-option 属性, 在该属性为 true 的情况下,按下回车就可以选中当前选项列表中的第一个选项,无需使用鼠标或键盘方向键进行定位。

TIP

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

Select 属性

属性名说明类型可选值默认值
model-value / v-model选中项绑定值array / string / number / boolean / object
multiple是否多选booleantrue/falsefalse
disabled是否禁用booleantrue / falsefalse
value-key作为 value 唯一标识的键名,绑定值为对象类型时必填stringvalue
size输入框尺寸stringlarge/default/smalldefault
clearable是否可以清空选项booleantrue / falsefalse
collapse-tags多选时是否将选中值按文字的形式展示booleantrue/falsefalse
collapse-tags-tooltip当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,collapse-tags属性必须设定为 truebooleantrue / falsefalse
multiple-limitmultiple 属性设置为 true 时,代表多选场景下用户最多可以选择的项目数, 为 0 则不限制number0
nameSelect 输入框的原生 name 属性string
effectTooltip 主题,内置了 dark / light 两种stringstringlight
autocompleteSelect 输入框的原生 autocomplete 属性stringoff
placeholder占位文字stringSelect
filterableSelect 组件是否可筛选booleantrue / falsefalse
allow-create是否允许用户创建新条目, 只有当 filterable 设置为 true 时才会生效。booleantrue/falsefalse
filter-method自定义筛选方法function
remote其中的选项是否从服务器远程加载booleantrue / falsefalse
remote-method自定义远程搜索方法function
remote-show-suffix远程搜索方法显示后缀图标booleantrue / falsefalse
loading是否正在从远程获取数据booleantrue / falsefalse
loading-text从服务器加载内容时显示的文本stringLoading
no-match-text搜索条件无匹配时显示的文字,也可以使用 empty 插槽设置stringNo matching data
no-data-text无选项时显示的文字,也可以使用 empty 插槽设置自定义内容stringNo data
popper-class选择器下拉菜单的自定义类名string
reserve-keywordmultiplefilter被设置为 true 时,是否在选中一个选项后保留当前的搜索关键词booleantrue / falsetrue
default-first-option是否在输入框按下回车时,选择第一个匹配项。 需配合 filterableremote 使用booleantrue / falsefalse
popper-append-to-body(已废弃)是否将弹出框插入至 body 元素 当弹出框的位置出现问题时,你可以尝试将该属性设置为 false。booleantrue / falsetrue
teleported该下拉菜单是否使用 teleport 插入 body 元素booleantrue / falsetrue
persistent当下拉选择器未被激活并且persistent设置为false,选择器会被删除。booleantrue / falsetrue
automatic-dropdown对于不可过滤的 Select 组件,此属性决定是否在输入框获得焦点后自动弹出选项菜单booleantrue / falsefalse
clear-icon自定义清除图标string | ComponentCircleClose
fit-input-width下拉框的宽度是否与输入框相同booleantrue / falsefalse
suffix-icon自定义后缀图标组件string | ComponentArrowDown
suffix-transitiondeprecated下拉菜单显示/消失时后缀图标的动画booleantrue / falsetrue
tag-type标签类型stringsuccess/info/warning/dangerinfo
validate-event是否触发表单验证booleantrue / falsetrue
placement下拉框出现的位置stringtop/top-start/top-end/bottom/bottom-start/bottom-end/left/left-start/left-end/right/right-start/right-endbottom-start

WARNING

suffix-transition 已被 弃用, 之后 将会被 移除到2.3.0, 请使用覆盖样式方案.

Select 事件

事件名说明回调参数
change选中值发生变化时触发val,目前的选中值
visible-change下拉框出现/隐藏时触发val,出现则为 true,隐藏则为 false
remove-tag多选模式下移除 tag 时触发val,移除的 tag 值
clear可清空的单选模式下用户点击清空按钮时触发
blur当 input 失去焦点时触发(event: FocusEvent)
focus当 input 获得焦点时触发(event: FocusEvent)

Select 插槽

插槽名说明子标签
Option 组件列表Option Group / Option
prefixSelect 组件头部内容
empty无选项时的列表

Option Group 属性

属性名说明类型可选值默认值
label分组的组名string
disabled是否将该分组下所有选项置为禁用booleanfalse

Option Group 插槽

插槽名说明子标签
-自定义默认内容Option

Option 属性

属性名说明类型可选值默认值
value选项的值string / number / boolean / object
label选项的标签,若不设置则默认与value相同string/number
disabled是否禁用该选项booleanfalse

Option 插槽

插槽名说明
默认插槽

Select 方法

方法名说明参数
focus使选择器的输入框获取焦点-
blur使选择器的输入框失去焦点,并隐藏下拉框-