选择

当有很多选项时，使用下拉菜单来显示并选择所需的选项。

TIP

版本2.5.0之后，el-select 的默认宽度为 100%。如果需要更窄的输入区域，请在外层容器上约束宽度。

基本用法

v-model 是当前选择的 el-option 的值。

Select

选项属性 2.10.5

el-option 基本用法的快捷方式。您可以通过props属性自定义options的别名。

Select

禁用选项

将 el-option 中的 disabled 的值设置为 true 以禁用此选项。

Select

禁用选择

禁用整个组件。

设置 el-select 的 disabled 以使其禁用。

Select

可清除

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

为 el-select 设置 clearable 属性，会出现一个清晰的图标。

Select

尺寸

添加 size 属性以更改 Select 的大小。除了默认尺寸外，还有另外两个选项：large、small。

Select

基本的多选

多重选择使用标签来显示选定的选项。

设置 el-select 的 multiple 属性以启用多种模式。在这种情况下，v-model 的值将是选定选项的数组。默认情况下，所选选项将显示为标签。您可以使用 collapse-tags 属性将它们折叠为文本，并在点击折叠摘要时通过 collapse-tags-tooltip 查看完整选中项。

default

Select

use collapse-tags

Select

use collapse-tags-tooltip

Select

use max-collapse-tags

Select

确认与取消

Select 默认通过底部弹层展开；多选场景会先缓存草稿值，再在确认后同步。

这个示例展示单选和多选的默认行为。展开多选后可以查看确认与取消流程。

单选

请选择地区

当前值：未选择

多选

请选择团队

已确认：未确认

vue

<template>
  <DemoBlock>
    <div class="demo-block__stack">
      <div class="demo-block__section">
        <span class="demo-block__caption">单选</span>
        <el-select
          v-model="region"
          clearable
          filterable
          placeholder="请选择地区"
        >
          <el-option
            v-for="item in regionOptions"
            :key="item.value"
            :label="item.label"
            :value="item.value"
          />
        </el-select>
        <p class="select-demo__summary">当前值：{{ region || '未选择' }}</p>
      </div>

      <div class="demo-block__section">
        <span class="demo-block__caption">多选</span>
        <el-select
          v-model="owners"
          clearable
          collapse-tags
          collapse-tags-tooltip
          filterable
          multiple
          placeholder="请选择团队"
        >
          <el-option
            v-for="item in ownerOptions"
            :key="item.value"
            :label="item.label"
            :value="item.value"
          />
        </el-select>
        <p class="select-demo__summary">
          已确认：{{ owners.length ? owners.join('、') : '未确认' }}
        </p>
      </div>
    </div>
  </DemoBlock>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import DemoBlock from '../components/demo-block.vue'

const region = ref('')
const owners = ref<string[]>([])

const regionOptions = [
  { label: '华北', value: 'north' },
  { label: '华东', value: 'east' },
  { label: '华南', value: 'south' },
  { label: '西南', value: 'west' },
]

const ownerOptions = [
  { label: '运营', value: 'operations' },
  { label: '设计', value: 'design' },
  { label: '内容', value: 'content' },
  { label: '销售', value: 'sales' },
  { label: '客服', value: 'support' },
  { label: '技术', value: 'engineering' },
]
</script>

<style scoped lang="scss">
.select-demo__summary {
  margin: 0;
  font-size: 0.8125rem;
  line-height: 1.5;
  color: var(--el-text-color-secondary);
}
</style>

自定义模板

您可以自定义选项的 HTML 模板。

将自定义的 HTML 模板插入到 el-option 的插槽中。

Select

下拉菜单标题 2.4.3

您可以自定义下拉列表的标题。

使用插槽自定义内容。

Select

下拉菜单的页脚 2.4.3

您可以自定义下拉菜单的页脚。

使用插槽自定义内容。

Select

分组

分组显示选项。

使用 el-option-group 对选项进行分组，其 label 属性代表组的名称。

Select

选项过滤

您可以过滤您想要的选项。

将 filterable 添加到 el-select 即可启用过滤。默认情况下，Select 将查找 label 属性包含输入值的所有选项。如果您更喜欢其他过滤策略，可以传递filter-method。 filter-method是当输入值改变时调用的Function，其参数为当前输入值。

Select

远程搜索

输入关键字并从服务器搜索数据。

将filterable和remote的值与true一起设置以启用远程搜索，并且您应该传递remote-method。 remote-method是当输入值改变时调用的Function，其参数为当前输入值。请注意，如果使用 v-for 指令呈现 el-option，则应为 el-option 添加 key 属性。它的值需要是唯一的，例如下面示例中的 item.value。

default

Please enter a keyword

use remote-show-suffix

Please enter a keyword

vue

<template>
  <div class="flex flex-wrap">
    <div class="m-4">
      <p>default</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
      </el-select>
    </div>
    <div class="m-4">
      <p>use remote-show-suffix</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        remote-show-suffix
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
      </el-select>
    </div>
  </div>
</template>

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

interface ListItem {
  value: string
  label: string
}

const list = ref<ListItem[]>([])
const options = ref<ListItem[]>([])
const value = ref<string[]>([])
const loading = ref(false)

onMounted(() => {
  list.value = states.map((item) => {
    return { value: `value:${item}`, label: `label:${item}` }
  })
})

const remoteMethod = (query: string) => {
  if (query) {
    loading.value = true
    setTimeout(() => {
      loading.value = false
      options.value = list.value.filter((item) => {
        return item.label.toLowerCase().includes(query.toLowerCase())
      })
    }, 200)
  } else {
    options.value = []
  }
}

const states = [
  'Alabama',
  'Alaska',
  'Arizona',
  'Arkansas',
  'California',
  'Colorado',
  'Connecticut',
  'Delaware',
  'Florida',
  'Georgia',
  'Hawaii',
  'Idaho',
  'Illinois',
  'Indiana',
  'Iowa',
  'Kansas',
  'Kentucky',
  'Louisiana',
  'Maine',
  'Maryland',
  'Massachusetts',
  'Michigan',
  'Minnesota',
  'Mississippi',
  'Missouri',
  'Montana',
  'Nebraska',
  'Nevada',
  'New Hampshire',
  'New Jersey',
  'New Mexico',
  'New York',
  'North Carolina',
  'North Dakota',
  'Ohio',
  'Oklahoma',
  'Oregon',
  'Pennsylvania',
  'Rhode Island',
  'South Carolina',
  'South Dakota',
  'Tennessee',
  'Texas',
  'Utah',
  'Vermont',
  'Virginia',
  'Washington',
  'West Virginia',
  'Wisconsin',
  'Wyoming',
]
</script>

创建新项目

创建并选择未包含在选择选项中的新项目

通过使用 allow-create 属性，用户可以通过在输入框中键入内容来创建新项目。请注意，要使 allow-create 正常工作，filterable 必须是 true。此示例还演示了 default-first-option。当此属性设置为 true 时，您可以通过按 Enter 键选择当前选项列表中的第一个选项，而无需使用鼠标或箭头键导航。

Choose tags for your article

使用值键属性

如果 Select 的绑定值是一个对象，请确保指定 value-key 作为其唯一标识键名称。

通过使用value-key属性，可以正确处理具有重复标签的数据。 label 属性的值重复，但可以通过 id 识别该选项。

Select

selected option's description: no select

自定义标签 2.5.0

您可以自定义标签。

将自定义标签插入 el-select 的插槽中。 collapse-tags、collapse-tags-tooltip、max-collapse-tags 将不起作用。

自定义加载 2.5.2

覆盖加载内容。

loading icon1

Please enter a keyword

loading icon2

Please enter a keyword

vue

<template>
  <div class="flex flex-wrap">
    <div class="m-4">
      <p>loading icon1</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
        <template #loading>
          <svg class="circular" viewBox="0 0 50 50">
            <circle class="path" cx="25" cy="25" r="20" fill="none" />
          </svg>
        </template>
      </el-select>
    </div>
    <div class="m-4">
      <p>loading icon2</p>
      <el-select
        v-model="value"
        multiple
        filterable
        remote
        reserve-keyword
        placeholder="Please enter a keyword"
        :remote-method="remoteMethod"
        :loading="loading"
        style="width: 240px"
      >
        <el-option
          v-for="item in options"
          :key="item.value"
          :label="item.label"
          :value="item.value"
        />
        <template #loading>
          <el-icon class="is-loading">
            <svg class="circular" viewBox="0 0 20 20">
              <g
                class="path2 loading-path"
                stroke-width="0"
                style="animation: none; stroke: none"
              >
                <circle r="3.375" class="dot1" rx="0" ry="0" />
                <circle r="3.375" class="dot2" rx="0" ry="0" />
                <circle r="3.375" class="dot4" rx="0" ry="0" />
                <circle r="3.375" class="dot3" rx="0" ry="0" />
              </g>
            </svg>
          </el-icon>
        </template>
      </el-select>
    </div>
  </div>
</template>

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

interface ListItem {
  value: string
  label: string
}

const list = ref<ListItem[]>([])
const options = ref<ListItem[]>([])
const value = ref<string[]>([])
const loading = ref(false)

onMounted(() => {
  list.value = states.map((item) => {
    return { value: `value:${item}`, label: `label:${item}` }
  })
})

const remoteMethod = (query: string) => {
  if (query) {
    loading.value = true
    setTimeout(() => {
      loading.value = false
      options.value = list.value.filter((item) => {
        return item.label.toLowerCase().includes(query.toLowerCase())
      })
    }, 3000)
  } else {
    options.value = []
  }
}

const states = [
  'Alabama',
  'Alaska',
  'Arizona',
  'Arkansas',
  'California',
  'Colorado',
  'Connecticut',
  'Delaware',
  'Florida',
  'Georgia',
  'Hawaii',
  'Idaho',
  'Illinois',
  'Indiana',
  'Iowa',
  'Kansas',
  'Kentucky',
  'Louisiana',
  'Maine',
  'Maryland',
  'Massachusetts',
  'Michigan',
  'Minnesota',
  'Mississippi',
  'Missouri',
  'Montana',
  'Nebraska',
  'Nevada',
  'New Hampshire',
  'New Jersey',
  'New Mexico',
  'New York',
  'North Carolina',
  'North Dakota',
  'Ohio',
  'Oklahoma',
  'Oregon',
  'Pennsylvania',
  'Rhode Island',
  'South Carolina',
  'South Dakota',
  'Tennessee',
  'Texas',
  'Utah',
  'Vermont',
  'Virginia',
  'Washington',
  'West Virginia',
  'Wisconsin',
  'Wyoming',
]
</script>

<style>
.el-select-dropdown__loading {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100px;
  font-size: 20px;
}

.circular {
  display: inline;
  height: 30px;
  width: 30px;
  animation: loading-rotate 2s linear infinite;
}
.path {
  animation: loading-dash 1.5s ease-in-out infinite;
  stroke-dasharray: 90, 150;
  stroke-dashoffset: 0;
  stroke-width: 2;
  stroke: var(--el-color-primary);
  stroke-linecap: round;
}
.loading-path .dot1 {
  transform: translate(3.75px, 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
}
.loading-path .dot2 {
  transform: translate(calc(100% - 3.75px), 3.75px);
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.4s;
}
.loading-path .dot3 {
  transform: translate(3.75px, calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 1.2s;
}
.loading-path .dot4 {
  transform: translate(calc(100% - 3.75px), calc(100% - 3.75px));
  fill: var(--el-color-primary);
  animation: custom-spin-move 1s infinite linear alternate;
  opacity: 0.3;
  animation-delay: 0.8s;
}
@keyframes loading-rotate {
  to {
    transform: rotate(360deg);
  }
}
@keyframes loading-dash {
  0% {
    stroke-dasharray: 1, 200;
    stroke-dashoffset: 0;
  }
  50% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -40px;
  }
  100% {
    stroke-dasharray: 90, 150;
    stroke-dashoffset: -120px;
  }
}
@keyframes custom-spin-move {
  to {
    opacity: 1;
  }
}
</style>

空值 2.7.0

如果要支持空字符串，请将empty-values设置为[null, undefined]。

如果要将清除值更改为null，请将value-on-clear设置为null。

自定义标签 2.7.4

您可以自定义标签。

: Option1

选择API

选择属性

名称	描述	类型	默认
模型值 / v 模型	绑定值	`字符串` / `数字` / `布尔值` / `对象` / `数组`	—
多个	是否激活多选	`布尔值`	假
选项 2.10.5	选项数据，`value` 和 `label` 和 `disabled` 的密钥可以由 `props` 自定义	`数组`	—
道具 2.10.5	配置选项	`对象`	—
已禁用	是否禁用选择	`布尔值`	假
值键	值的唯一标识键名称，当值是对象时需要	`字符串`	价值
尺寸	输入的大小	`枚举`	—
可清除	是否可以清除select	`布尔值`	假
折叠标签	多重选择时是否将标签折叠为文本	`布尔值`	假
折叠标签工具提示 2.3.0	点击折叠标签摘要时是否显示所有选定的标签。要使用此功能，`collapse-tags` 必须为 true	`布尔值`	假
标签工具提示 2.13.3	折叠标签工具提示的配置对象。要使用此功能，`collapse-tags` 和 `collapse-tags-tooltip` 必须为 true	`对象`	{}
多重限制	当 `multiple` 为 `true` 时，用户可以选择的最大选项数。设置为 0 时无限制	`数字`	0
编号	本机输入 id 输入	`字符串`	—
名称	选择输入的名称属性	`字符串`	—
效果	工具提示主题，内置主题：`dark` / `light`	`枚举` / `字符串`	光
自动完成	select input 的自动完成属性	`字符串`	关闭
占位符	占位符，默认为“选择”	`字符串`	—
可过滤	Select 是否可过滤	`布尔值`	假
允许创建	是否允许创建新项目。要使用此功能，`filterable` 必须为 true	`布尔值`	假
过滤方法	自定义过滤方法，第一个参数是当前输入值。要使用此功能，`filterable` 必须为 true	`功能`	—
远程	是否从服务器加载选项	`布尔值`	假
去抖 2.11.7	远程搜索期间的去抖延迟（毫秒）	`数字`	300
远程方法	当输入值改变时调用的函数。其参数为当前输入值。要使用此功能，`filterable` 必须为 true	`功能`	—
远程显示后缀	在远程搜索方法中显示后缀图标	`布尔值`	假
加载	Select 是否正在从服务器加载数据	`布尔值`	假
加载文本	从服务器加载数据时显示的文本，默认为“正在加载”	`字符串`	—
不匹配文本	当没有数据匹配过滤查询时显示的文本，也可以使用插槽`empty`，默认为'无匹配数据'	`字符串`	—
无数据文本	没有选项时显示的文本，也可以使用插槽`empty`，默认为“无数据”	`字符串`	—
波普尔级	Select 下拉列表和标签工具提示的自定义类名称	`字符串`	''
波普风格 2.11.0	选择下拉菜单和标签工具提示的自定义样式	`字符串` / `对象`	—
保留关键字	当`multiple`和`filterable`为true时，选择选项后是否保留当前关键字	`布尔值`	真实
默认第一选项	按 Enter 键选择第一个匹配选项。与 `filterable` 或 `remote` 一起使用	`布尔值`	假
执着	当选择下拉列表处于非活动状态且 `persistent` 为 `false` 时，选择下拉列表将被销毁	`布尔值`	真实
自动下拉	对于不可过滤的 Select，此属性决定当输入聚焦时是否弹出选项菜单	`布尔值`	假
清除图标	自定义透明图标组件	`字符串` / `对象`	圆圈关闭
后缀图标	自定义后缀图标组件	`字符串` / `对象`	向下箭头
标签类型	标签类型	`枚举`	信息
标签效果 2.7.7	标签效果	`枚举`	光
验证事件	是否触发表单验证	`布尔值`	真实
最大折叠标签 2.3.0	要显示的最大标签数。要使用此功能，`collapse-tags` 必须为 true	`数字`	1
咏叹调标签 a11y	与本机输入中的 `aria-label` 相同	`字符串`	—
空值 2.7.0	组件的空值，参见配置提供程序	`数组`	—
清除值 2.7.0	清除返回值，参见配置提供程序	`字符串` / `数字` / `布尔值` / `函数`	—
后缀转换^（已弃用）	下拉图标出现/消失时的动画	`布尔值`	真实
选项卡索引 2.9.0	输入的 tabindex	`字符串` / `数字`	—

WARNING

suffix-transition 已被弃用，并且将在 2.4.0 中删除，请使用覆盖样式方案。

道具

属性	描述	类型	默认
价值	指定节点对象的哪个键用作节点的值	`字符串`	价值
标签	指定节点对象的哪个键用作节点的标签	`字符串`	标签
选项 2.11.0	指定节点对象的哪个键用作节点的子节点	`字符串`	选项
已禁用	指定节点对象的哪个键用作节点的禁用	`字符串`	已禁用

标签工具提示 2.13.3

回退机制

tag-tooltip 中的属性遵循以下优先顺序：

标签工具提示对象中显式定义的字段。
从 el-select 继承的共享属性，例如 effect、popper-class、popper-style。
底层 el-tooltip 组件的默认值。

这允许您覆盖标签工具提示的局部行为，同时保持与默认下拉层一致的基础表现。

属性	描述	类型	默认
效果	工具提示主题，内置主题：`dark` / `light`	`枚举` / `字符串`	—
波普尔级	工具提示弹出器的自定义类名	`字符串`	—
波普风格	工具提示弹出窗口的自定义样式	`字符串` / `对象`	—
过渡	动画名称	`字符串`	—
后显示	出现延迟，以毫秒为单位	`数字`	—
隐藏后	消失延迟，以毫秒为单位	`数字`	—
自动关闭	隐藏工具提示的超时时间（毫秒）	`数字`	—

选择活动

名称	描述	类型
改变	当所选值更改时触发	`功能`
可见变化	当下拉菜单出现/消失时触发	`功能`
删除标签	在多重模式下删除标签时触发	`功能`
清除	在可清除的 Select 中单击清除图标时触发	`功能`
模糊	当输入模糊时触发	`功能`
焦点	当输入聚焦时触发	`功能`
弹出滚动 2.9.4	下拉菜单滚动时触发	`功能`

选择插槽

名称	描述	子标签
默认	选项组件列表	选项组/选项
标头 2.4.3	下拉菜单顶部的内容	—
页脚 2.4.3	下拉菜单底部的内容	—
前缀	内容作为选择前缀	—
空	没有选项时的内容	—
标签 2.5.0	作为 Select 标签的内容。`data`、`selectDisabled` 和 `deleteTag` 在 2.10.3 中引入。	`对象`
加载 2.5.2	内容为选择加载	—
标签 2.7.4	作为选择标签的内容。`index` 在 2.11.2 中引入。	`对象`

选择暴露

名称	描述	类型
焦点	聚焦输入组件	`功能`
模糊	模糊输入组件，并隐藏下拉菜单	`功能`
选定标签 2.8.5	获取当前选择的标签	`对象`

选项组 API

选项组属性

名称	描述	类型	默认
标签	分组标题	`字符串`	—
已禁用	是否禁用该组中的所有选项	`布尔值`	假

选项组插槽

名称	描述	子标签
默认	自定义默认内容	选项

选项 API

选项属性

名称	描述	类型	默认
价值	期权价值	`字符串` / `数字` / `布尔值` / `对象`	—
标签	选项标签，如果省略则与 `value` 相同	`字符串` / `数字`	—
已禁用	选项是否被禁用	`布尔值`	假

选项槽

名称	描述
默认	自定义默认内容

Rate 评分

Virtualized Select 虚拟化选择器

选择 ​

基本用法 ​

选项属性 2.10.5 ​

禁用选项 ​

禁用选择 ​

可清除 ​

尺寸 ​

基本的多选 ​

确认与取消 ​

自定义模板 ​

下拉菜单标题 2.4.3 ​

下拉菜单的页脚 2.4.3 ​

分组 ​

选项过滤 ​

远程搜索 ​

创建新项目 ​

使用值键属性 ​

自定义标签 2.5.0 ​

自定义加载 2.5.2 ​

空值 2.7.0 ​

自定义标签 2.7.4 ​

选择API ​

选择属性 ​

道具 ​

标签工具提示 2.13.3 ​

选择活动 ​

选择插槽 ​

选择暴露 ​

选项组 API ​

选项组属性 ​

选项组插槽 ​

选项 API ​

选项属性 ​

选项槽 ​

选择

基本用法

选项属性 2.10.5

禁用选项

禁用选择

可清除

尺寸

基本的多选

确认与取消

自定义模板

下拉菜单标题 2.4.3

下拉菜单的页脚 2.4.3

分组

选项过滤

远程搜索

创建新项目

使用值键属性

自定义标签 2.5.0

自定义加载 2.5.2

空值 2.7.0

自定义标签 2.7.4

选择API

选择属性

道具

标签工具提示 2.13.3

选择活动

选择插槽

选择暴露

选项组 API

选项组属性

选项组插槽

选项 API

选项属性

选项槽