Select 选择器

当选项较多时，使用下拉菜单承载候选项，帮助用户在有限空间内完成单选、多选、搜索或远程检索。

基础用法

使用 v-model 绑定当前选中值，通过 el-option 配置候选项。label 用于展示文本，value 用于表单提交值。

请选择模块

vue

<template>
  <el-select v-model="value" placeholder="请选择模块" style="width: 240px">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
      :disabled="item.disabled"
    />
  </el-select>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')

const options = [
  { value: 'project', label: '项目管理' },
  { value: 'quote', label: '报价配置' },
  { value: 'material', label: '素材管理' },
  { value: 'archive', label: '归档数据', disabled: true },
]
</script>

禁用状态

为 el-select 设置 disabled 可以禁用整个选择器；为单个 el-option 设置 disabled 可以禁用某个选项。

禁用选项

禁用选择器

vue

<template>
  <el-select v-model="value" placeholder="禁用选项">
    <el-option label="项目管理" value="project" />
    <el-option label="归档数据" value="archive" disabled />
  </el-select>

  <el-select v-model="value" disabled placeholder="禁用选择器">
    <el-option label="项目管理" value="project" />
  </el-select>
</template>

可清空

设置 clearable 后，选择器会在有值时显示清除按钮。可以通过 clear-icon 替换清除图标。

vue

<template>
  <el-select v-model="value" clearable placeholder="可清空">
    <el-option label="项目管理" value="project" />
    <el-option label="报价配置" value="quote" />
  </el-select>

  <el-select v-model="iconValue" clearable :clear-icon="CircleClose" placeholder="自定义清除图标">
    <el-option label="项目管理" value="project" />
    <el-option label="报价配置" value="quote" />
  </el-select>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { CircleClose } from '@element-plus/icons-vue'

const value = ref('')
const iconValue = ref('')
</script>

多选

设置 multiple 可以开启多选，此时绑定值应为数组。multiple-limit 可限制最多选择数量。

vue

<template>
  <el-select v-model="value" multiple :multiple-limit="3" placeholder="请选择模块">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref(['project', 'quote'])
</script>

折叠标签

多选时可设置 collapse-tags 折叠已选标签；配合 collapse-tags-tooltip 与 max-collapse-tags 控制折叠后的提示与展示数量。

vue

<template>
  <el-select
    v-model="value"
    multiple
    collapse-tags
    collapse-tags-tooltip
    :max-collapse-tags="2"
    placeholder="折叠标签"
  >
    <el-option label="项目管理" value="project" />
    <el-option label="报价配置" value="quote" />
    <el-option label="素材管理" value="material" />
  </el-select>
</template>

自定义选项

el-option 默认插槽可自定义下拉项内容，适合展示辅助信息、状态或图标。

自定义选项

vue

<template>
  <el-select v-model="value" placeholder="自定义选项">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    >
      <span style="float: left">{{ item.label }}</span>
      <span style="float: right; color: var(--vista-text-muted); font-size: 13px">
        {{ item.value }}
      </span>
    </el-option>
  </el-select>
</template>

分组选项

使用 el-option-group 可以将选项按业务维度分组，便于用户快速定位。

请选择功能

vue

<template>
  <el-select v-model="value" placeholder="请选择功能">
    <el-option-group
      v-for="group in groupedOptions"
      :key="group.label"
      :label="group.label"
    >
      <el-option
        v-for="item in group.options"
        :key="item.value"
        :label="item.label"
        :value="item.value"
      />
    </el-option-group>
  </el-select>
</template>

可筛选

设置 filterable 后，选择器支持按输入内容筛选本地选项。可通过 filter-method 自定义筛选逻辑。

搜索模块

vue

<template>
  <el-select v-model="value" filterable clearable placeholder="搜索模块">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

远程搜索

设置 filterable、remote 与 remote-method 后，可在输入时请求远程数据。loading 用于展示加载状态。

输入关键字搜索

vue

<template>
  <el-select
    v-model="value"
    filterable
    remote
    reserve-keyword
    clearable
    placeholder="输入关键字搜索"
    :remote-method="remoteMethod"
    :loading="loading"
  >
    <el-option
      v-for="item in remoteOptions"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const loading = ref(false)
const remoteOptions = ref([])

const remoteMethod = (query: string) => {
  if (!query) {
    remoteOptions.value = []
    return
  }
  loading.value = true
  setTimeout(() => {
    loading.value = false
    remoteOptions.value = options.filter((item) =>
      item.label.toLowerCase().includes(query.toLowerCase()),
    )
  }, 250)
}
</script>

创建新条目

allow-create 允许用户输入并创建不存在的选项，通常与 filterable 配合使用。

输入并创建标签

vue

<template>
  <el-select
    v-model="value"
    filterable
    allow-create
    default-first-option
    clearable
    placeholder="输入并创建标签"
  >
    <el-option label="项目管理" value="project" />
    <el-option label="报价配置" value="quote" />
  </el-select>
</template>

前缀内容

通过 prefix 插槽可以在输入区域前侧展示图标或文本，帮助用户理解选择器用途。

搜索业务模块

vue

<template>
  <el-select v-model="value" clearable placeholder="搜索业务模块">
    <template #prefix>
      <el-icon><Search /></el-icon>
    </template>
    <el-option label="项目管理" value="project" />
    <el-option label="报价配置" value="quote" />
  </el-select>
</template>

使用 options

可以通过 options 直接传入数据源，并使用 props 指定字段映射，减少模板中的重复 el-option。

options 快捷配置

vue

<template>
  <el-select
    v-model="value"
    :options="options"
    :props="{ label: 'name', value: 'id', disabled: 'disabled' }"
    placeholder="options 快捷配置"
  />
</template>

页眉页脚

通过 header 与 footer 插槽可以在下拉面板顶部或底部放置辅助操作。

选择模块

vue

<template>
  <el-select v-model="value" placeholder="选择模块">
    <template #header>
      <div>常用模块</div>
    </template>

    <el-option label="项目管理" value="project" />
    <el-option label="报价配置" value="quote" />

    <template #footer>
      <el-button text type="primary" size="small">新增模块</el-button>
    </template>
  </el-select>
</template>

加载与空状态

loading 可展示加载状态；empty 与 loading 插槽可以自定义无数据和加载时的面板内容。

加载中

无数据

vue

<template>
  <el-select v-model="loadingValue" loading loading-text="加载模块中" placeholder="加载中" />

  <el-select v-model="emptyValue" placeholder="无数据">
    <template #empty>
      <div>暂无可选模块</div>
    </template>
  </el-select>
</template>

不同尺寸

size 支持 large、default、small 三种尺寸，用于适配不同密度的表单和工具栏场景。

Large

Default

Small

vue

<template>
  <el-select v-model="large" size="large" placeholder="Large" />
  <el-select v-model="defaultValue" placeholder="Default" />
  <el-select v-model="small" size="small" placeholder="Small" />
</template>

Select API

Select 属性

属性名	说明	类型	默认值
model-value / v-model	绑定值，单选为基础类型或对象，多选为数组	`string \| number \| boolean \| object \| array`	`''`
multiple	是否多选	`boolean`	`false`
disabled	是否禁用	`boolean`	`false`
value-key	作为 value 唯一标识的键名，绑定值为对象时必填	`string`	`value`
size	输入框尺寸	`enum`	`default`
clearable	是否可以清空选项	`boolean`	`false`
collapse-tags	多选时是否折叠标签	`boolean`	`false`
collapse-tags-tooltip	折叠标签时是否通过 tooltip 展示全部标签	`boolean`	`false`
max-collapse-tags	需要展示的标签最大数量	`number`	`1`
multiple-limit	多选时用户最多可以选择的项目数，`0` 表示不限制	`number`	`0`
name	原生 input 的 name 属性	`string`	`''`
effect	tooltip 主题	`enum`	`light`
autocomplete	原生 input 的 autocomplete 属性	`string`	`off`
placeholder	占位文本	`string`	`请选择`
filterable	是否可筛选	`boolean`	`false`
allow-create	是否允许创建新条目，需配合 `filterable` 使用	`boolean`	`false`
filter-method	自定义筛选方法	`function`	`-`
remote	是否启用远程搜索	`boolean`	`false`
remote-method	远程搜索方法	`function`	`-`
remote-show-suffix	远程搜索时是否显示后缀图标	`boolean`	`false`
loading	是否正在加载数据	`boolean`	`false`
loading-text	加载时显示的文本	`string`	`加载中`
no-match-text	搜索条件无匹配时显示的文本	`string`	`无匹配数据`
no-data-text	无选项时显示的文本	`string`	`无数据`
popper-class	下拉菜单的自定义类名	`string`	`''`
reserve-keyword	多选且可筛选时，选中后是否保留当前搜索关键词	`boolean`	`true`
default-first-option	输入后按回车是否选择第一个匹配项，需配合 `filterable` 或 `remote` 使用	`boolean`	`false`
teleported	下拉菜单是否插入至 body	`boolean`	`true`
persistent	下拉菜单不展示时是否保留 DOM	`boolean`	`true`
automatic-dropdown	输入框获得焦点后是否自动弹出下拉菜单	`boolean`	`false`
clear-icon	自定义清除图标组件	`string \| component`	`CircleClose`
fit-input-width	下拉框宽度是否与输入框相同	`boolean`	`false`
suffix-icon	自定义后缀图标组件	`string \| component`	`ArrowDown`
tag-type	多选标签类型	`enum`	`info`
tag-effect	多选标签主题	`enum`	`light`
validate-event	输入时是否触发表单校验	`boolean`	`true`
placement	下拉框出现的位置	`enum`	`bottom-start`
fallback-placements	下拉框可用的备用位置	`array`	`['bottom-start', 'top-start', 'right', 'left']`
popper-options	popper.js 参数	`object`	`{}`
aria-label	等价于原生 input aria-label 属性	`string`	`-`
empty-values	组件的空值配置	`array`	`-`
value-on-clear	清空时设置的值	`string \| number \| boolean \| function`	`-`
options	选项数据源	`array`	`[]`
props	options 字段映射配置	`object`	`-`

Select 事件

事件名	说明	类型
change	选中值变化时触发	`Function`
visible-change	下拉框显示状态变化时触发	`Function`
remove-tag	多选模式下移除标签时触发	`Function`
clear	点击清空按钮时触发	`Function`
blur	组件失去焦点时触发	`Function`
focus	组件获得焦点时触发	`Function`
popup-scroll	下拉滚动时触发	`Function`

Select 插槽

插槽名	说明
default	Option 组件列表
prefix	输入框前缀内容
empty	无选项时的内容
tag	自定义多选标签内容
loading	自定义加载中内容
header	下拉面板头部内容
footer	下拉面板底部内容
label	自定义已选中项的展示内容

Select 暴露

名称	说明	类型
focus	使选择器获得焦点	`Function`
blur	使选择器失去焦点	`Function`
selectedLabel	当前选中的标签文本	`object`

Option API

Option 属性

属性名	说明	类型	默认值
value	选项的值	`string \| number \| boolean \| object`	`-`
label	选项展示文本，未设置时默认与 `value` 相同	`string \| number`	`-`
disabled	是否禁用该选项	`boolean`	`false`
created	是否为用户创建的选项	`boolean`	`false`

Option 插槽

插槽名	说明
default	自定义选项内容

Option Group API

Option Group 属性

属性名	说明	类型	默认值
label	分组名称	`string`	`-`
disabled	是否禁用该分组下所有选项	`boolean`	`false`

Option Group 插槽

插槽名	说明
default	Option 组件列表

Select 选择器 ​

基础用法 ​

禁用状态 ​

可清空 ​

多选 ​

折叠标签 ​

自定义选项 ​

分组选项 ​

可筛选 ​

远程搜索 ​

创建新条目 ​

前缀内容 ​

使用 options ​

页眉页脚 ​

加载与空状态 ​

不同尺寸 ​

Select API ​

Select 属性 ​

Select 事件 ​

Select 插槽 ​

Select 暴露 ​

Option API ​

Option 属性 ​

Option 插槽 ​

Option Group API ​

Option Group 属性 ​

Option Group 插槽 ​

Select 选择器

基础用法

禁用状态

可清空

多选

折叠标签

自定义选项

分组选项

可筛选

远程搜索

创建新条目

前缀内容

使用 options

页眉页脚

加载与空状态

不同尺寸

Select API

Select 属性

Select 事件

Select 插槽

Select 暴露

Option API

Option 属性

Option 插槽

Option Group API

Option Group 属性

Option Group 插槽