Select 选择器

下拉选择器。

何时使用

  • 弹出一个下拉菜单给用户选择操作，用于代替原生的选择器，或者需要一个更优雅的多选器时。
  • 当选项少时（少于 5 项），建议直接将选项平铺，使用 Radio 是更好的选择。

代码演示

use a-select-option

Lucy
Lucy
Lucy

use options (recommend)

Lucy
Lucy
Lucy
基本使用

基本使用。

<template>
  <h2>use a-select-option</h2>
  <a-space>
    <a-select
      ref="select"
      v-model:value="value1"
      style="width: 120px"
      @focus="focus"
      @change="handleChange"
    >
      <a-select-option value="jack">Jack</a-select-option>
      <a-select-option value="lucy">Lucy</a-select-option>
      <a-select-option value="disabled" disabled>Disabled</a-select-option>
      <a-select-option value="Yiminghe">yiminghe</a-select-option>
    </a-select>
    <a-select v-model:value="value2" style="width: 120px" disabled>
      <a-select-option value="lucy">Lucy</a-select-option>
    </a-select>
    <a-select v-model:value="value3" style="width: 120px" loading>
      <a-select-option value="lucy">Lucy</a-select-option>
    </a-select>
  </a-space>
  <h2 style="margin-top: 10px">use options (recommend)</h2>
  <a-space>
    <a-select
      ref="select"
      v-model:value="value1"
      style="width: 120px"
      :options="options1"
      @focus="focus"
      @change="handleChange"
    >
    </a-select>
    <a-select v-model:value="value2" style="width: 120px" disabled :options="options2"></a-select>
    <a-select v-model:value="value3" style="width: 120px" loading :options="options3"></a-select>
  </a-space>
</template>
<script lang="ts">
import { SelectTypes } from 'ant-design-vue/es/select';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const options1 = ref<SelectTypes['options']>([
      {
        value: 'jack',
        label: 'Jack',
      },
      {
        value: 'lucy',
        label: 'Lucy',
      },
      {
        value: 'disabled',
        label: 'Disabled',
        disabled: true,
      },
      {
        value: 'yiminghe',
        label: 'Yiminghe',
      },
    ]);
    const options2 = ref<SelectTypes['options']>([
      {
        value: 'lucy',
        label: 'Lucy',
      },
    ]);
    const options3 = ref<SelectTypes['options']>([
      {
        value: 'lucy',
        label: 'Lucy',
      },
    ]);
    const focus = () => {
      console.log('focus');
    }; 
    const handleChange = (value: string) => {
      console.log(`selected ${value}`);
    }; 
    return {
      focus,
      handleChange,
      value1: ref('lucy'),
      value2: ref('lucy'),
      value3: ref('lucy'),
      options1,
      options2,
      options3,
    };
  },
});
</script>
Tags Mode
标签

tags select，随意输入的内容（scroll the menu）

<template>
  <a-select
    v-model:value="value"
    mode="tags"
    style="width: 100%"
    placeholder="Tags Mode"
    :options="options"
    @change="handleChange"
  >
  </a-select>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const handleChange = (value: string) => {
      console.log(`selected ${value}`);
    };
    return {
      value: ref([]),
      handleChange,
      options: [...Array(25)].map((_, i) => ({ value: (i + 10).toString(36) + (i + 1) })),
    };
  },
});
</script>
Lucy (101)
获得选项的文本

默认情况下 onChange 里只能拿到 value，如果需要拿到选中的节点文本 label，可以使用 labelInValue 属性。 选中项的 label 会被包装到 value 中传递给 onChange 等函数，此时 value 是一个对象。

<template>
  <a-select
    v-model:value="value"
    label-in-value
    style="width: 120px"
    :options="options"
    @change="handleChange"
  >
  </a-select>
</template>
<script lang="ts">
import { SelectTypes } from 'ant-design-vue/es/select';
import { defineComponent, ref } from 'vue'; 
interface Value {
  value?: string;
  label?: string;
} 
export default defineComponent({
  setup() {
    const options = ref<SelectTypes['options']>([
      {
        value: 'jack',
        label: 'Jack (100)',
      },
      {
        value: 'lucy',
        label: 'Lucy (101)',
      },
    ]);
    const handleChange = (value: Value) => {
      console.log(value); // { key: "lucy", label: "Lucy (101)" }
    };
    return {
      value: ref<Value>({ value: 'lucy' }),
      options,
      handleChange,
    };
  },
});
</script>
Zhejiang
Hangzhou
联动

省市联动是典型的例子。 推荐使用 Cascader 组件。

<template>
  <a-space>
    <a-select
      v-model:value="province"
      style="width: 120px"
      :options="provinceData.map(pro => ({ value: pro }))"
    >
    </a-select>
    <a-select
      v-model:value="secondCity"
      style="width: 120px"
      :options="cities.map(city => ({ value: city }))"
    >
    </a-select>
  </a-space>
</template>
<script lang="ts">
const provinceData = ['Zhejiang', 'Jiangsu'];
const cityData = {
  Zhejiang: ['Hangzhou', 'Ningbo', 'Wenzhou'],
  Jiangsu: ['Nanjing', 'Suzhou', 'Zhenjiang'],
};
import { defineComponent, reactive, toRefs, computed, watch } from 'vue';
export default defineComponent({
  setup() {
    const province = provinceData[0];
    const state = reactive({
      province,
      provinceData,
      cityData,
      secondCity: cityData[province][0],
    });
    const cities = computed(() => {
      return cityData[state.province];
    }); 
    watch(
      () => state.province,
      val => {
        state.secondCity = state.cityData[val][0];
      },
    ); 
    return {
      ...toRefs(state),
      cities,
    };
  },
});
</script>
Select users
搜索用户

一个带有远程搜索，节流控制，请求时序控制，加载状态的多选示例。

<template>
  <a-select
    v-model:value="value"
    mode="multiple"
    label-in-value
    placeholder="Select users"
    style="width: 100%"
    :filter-option="false"
    :not-found-content="fetching ? undefined : null"
    :options="data"
    @search="fetchUser"
  >
    <template v-if="fetching" #notFoundContent>
      <a-spin size="small" />
    </template>
  </a-select>
</template>
<script>
import { defineComponent, reactive, toRefs, watch } from 'vue';
import { debounce } from 'lodash-es'; 
export default defineComponent({
  setup() {
    let lastFetchId = 0; 
    const state = reactive({
      data: [],
      value: [],
      fetching: false,
    }); 
    const fetchUser = debounce(value => {
      console.log('fetching user', value);
      lastFetchId += 1;
      const fetchId = lastFetchId;
      state.data = [];
      state.fetching = true;
      fetch('https://randomuser.me/api/?results=5')
        .then(response => response.json())
        .then(body => {
          if (fetchId !== lastFetchId) {
            // for fetch callback order
            return;
          }
          const data = body.results.map(user => ({
            label: `${user.name.first} ${user.name.last}`,
            value: user.login.username,
          }));
          state.data = data;
          state.fetching = false;
        });
    }, 300); 
    watch(state.value, () => {
      state.data = [];
      state.fetching = false;
    }); 
    return {
      ...toRefs(state),
      fetchUser,
    };
  },
});
</script>
Inserted are removed
隐藏已选择选项

隐藏下拉列表中已选择的选项。

<template>
  <a-select
    v-model:value="selectedItems"
    mode="multiple"
    placeholder="Inserted are removed"
    style="width: 100%"
    :options="filteredOptions.map(item => ({ value: item }))"
  >
  </a-select>
</template>
<script lang="ts">
import { computed, defineComponent, ref } from 'vue'; 
const OPTIONS = ['Apples', 'Nails', 'Bananas', 'Helicopters'];
export default defineComponent({
  setup() {
    const selectedItems = ref<string[]>([]); 
    const filteredOptions = computed(() => OPTIONS.filter(o => !selectedItems.value.includes(o))); 
    return {
      selectedItems,
      filteredOptions,
    };
  },
});
</script>
China
China (中国)
Note: v-slot:option support from v2.2.5
定制回填内容

使用 optionLabelProp 指定回填到选择框的 Option 属性。

<template>
  <a-space direction="vertical" style="width: 100%">
    <a-select
      v-model:value="value"
      mode="multiple"
      style="width: 100%"
      placeholder="select one country"
      option-label-prop="label"
    >
      <a-select-option value="china" label="China">
        <span role="img" aria-label="China">🇨🇳</span>
        &nbsp;&nbsp;China (中国)
      </a-select-option>
      <a-select-option value="usa" label="USA">
        <span role="img" aria-label="USA">🇺🇸</span>
        &nbsp;&nbsp;USA (美国)
      </a-select-option>
      <a-select-option value="japan" label="Japan">
        <span role="img" aria-label="Japan">🇯🇵</span>
        &nbsp;&nbsp;Japan (日本)
      </a-select-option>
      <a-select-option value="korea" label="Korea">
        <span role="img" aria-label="Korea">🇰🇷</span>
        &nbsp;&nbsp;Korea (韩国)
      </a-select-option>
    </a-select> 
    <a-select
      v-model:value="value"
      mode="multiple"
      style="width: 100%"
      placeholder="select one country"
      option-label-prop="label"
      :options="options"
    >
      <template #option="{ value: val, label, icon }">
        <span role="img" :aria-label="val">{{ icon }}</span>
        &nbsp;&nbsp;{{ label }}
      </template>
    </a-select>
    <span>Note: v-slot:option support from v2.2.5</span>
  </a-space>
</template>
<script lang="ts">
import { defineComponent, ref, watch } from 'vue'; 
export default defineComponent({
  setup() {
    const value = ref(['china']); 
    const options = ref([
      {
        value: 'china',
        label: 'China (中国)',
        icon: '🇨🇳',
      },
      {
        value: 'usa',
        label: 'USA (美国)',
        icon: '🇺🇸',
      },
      {
        value: 'japan',
        label: 'Japan (日本)',
        icon: '🇯🇵',
      },
      {
        value: 'korea',
        label: 'Korea (韩国)',
        icon: '🇨🇰',
      },
    ]);
    watch(value, val => {
      console.log(`selected:`, val);
    }); 
    return {
      options,
      value,
    };
  },
});
</script>


a1
a1
b2
a1
b2
三种大小

三种大小的选择框，当 size 分别为 large 和 small 时，输入框高度为 40px 和 24px ，默认高度为 32px。

<template>
  <a-radio-group v-model:value="size">
    <a-radio-button value="large">Large</a-radio-button>
    <a-radio-button value="default">Default</a-radio-button>
    <a-radio-button value="small">Small</a-radio-button>
  </a-radio-group>
  <br />
  <br />
  <a-space direction="vertical">
    <a-select
      v-model:value="value1"
      :size="size"
      style="width: 200px"
      :options="options"
    ></a-select>
    <a-select
      v-model:value="value2"
      :options="options"
      mode="multiple"
      :size="size"
      placeholder="Please select"
      style="width: 200px"
      @popupScroll="popupScroll"
    >
    </a-select>
    <a-select
      v-model:value="value3"
      :options="options"
      mode="tags"
      :size="size"
      placeholder="Please select"
      style="width: 200px"
    >
    </a-select>
  </a-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const popupScroll = () => {
      console.log('popupScroll');
    }; 
    return {
      popupScroll,
      size: ref('default'),
      value1: ref('a1'),
      value2: ref(['a1', 'b2']),
      value3: ref(['a1', 'b2']),
      options: [...Array(25)].map((_, i) => ({ value: (i + 10).toString(36) + (i + 1) })),
    };
  },
});
</script>
Automatic tokenization
自动分词

试下复制 露西,杰克 到输入框里。只在 tags 和 multiple 模式下可用。

<template>
  <a-select
    v-model:value="value"
    mode="tags"
    style="width: 100%"
    :token-separators="[',']"
    placeholder="Automatic tokenization"
    :options="options"
    @change="handleChange"
  ></a-select>
</template>
<script lang="ts">
import { defineComponent, ref, watch } from 'vue';
import { SelectTypes } from 'ant-design-vue/es/select';
export default defineComponent({
  setup() {
    const options = ref<SelectTypes['options']>([
      {
        value: 'a1',
        label: 'a1',
      },
    ]);
    const value = ref<string[]>([]);
    const handleChange = (value: string) => {
      console.log(`selected ${value}`);
    };
    watch(value, () => {
      console.log('value', value.value);
    });
    return {
      options,
      handleChange,
      value,
    };
  },
});
</script>
a1
b2
多选

多选，从已有条目中选择（scroll the menu）

<template>
  <a-select
    v-model:value="value"
    mode="multiple"
    style="width: 100%"
    placeholder="Please select"
    :options="[...Array(25)].map((_, i) => ({ value: (i + 10).toString(36) + (i + 1) }))"
    @change="handleChange"
  >
  </a-select>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const handleChange = (value: string[]) => {
      console.log(`selected ${value}`);
    };
    return {
      handleChange,
      value: ref(['a1', 'b2']),
    };
  },
});
</script>
Lucy
Lucy
分组

用 OptGroup 或 options.options 进行选项分组。

<template>
  <a-space>
    <a-select v-model:value="value" style="width: 200px" @change="handleChange">
      <a-select-opt-group>
        <template #label>
          <span>
            <user-outlined />
            Manager
          </span>
        </template>
        <a-select-option value="jack">Jack</a-select-option>
        <a-select-option value="lucy">Lucy</a-select-option>
      </a-select-opt-group>
      <a-select-opt-group label="Engineer">
        <a-select-option value="Yiminghe">yiminghe</a-select-option>
        <a-select-option value="Yiminghe1">yiminghe1</a-select-option>
      </a-select-opt-group>
    </a-select>
    <a-select
      v-model:value="value"
      :options="options"
      style="width: 200px"
      @change="handleChange"
    ></a-select>
  </a-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { UserOutlined } from '@ant-design/icons-vue';
import { SelectTypes } from 'ant-design-vue/es/select';
export default defineComponent({
  components: {
    UserOutlined,
  },
  setup() {
    const handleChange = (value: string) => {
      console.log(`selected ${value}`);
    }; 
    const options = ref<SelectTypes['options']>([
      {
        label: 'Manager',
        options: [
          {
            value: 'jack',
            label: 'Jack',
          },
          {
            value: 'lucy',
            label: 'Lucy',
          },
        ],
      },
      {
        label: 'Engineer',
        options: [
          {
            value: 'yiminghe',
            label: 'Yiminghe',
          },
        ],
      },
    ]); 
    return {
      value: ref(['lucy']),
      handleChange,
      options,
    };
  },
});
</script>
Lucy
Lucy
后缀图标

基本使用。

<template>
  <a-space>
    <a-select
      v-model:value="value1"
      style="width: 120px"
      :options="options1"
      @change="handleChange"
    >
      <template #suffixIcon><smile-outlined /></template>
    </a-select>
    <a-select v-model:value="value2" style="width: 120px" disabled :options="options2">
      <template #suffixIcon><meh-outlined /></template>
    </a-select>
  </a-space>
</template>
<script lang="ts">
import { SmileOutlined, MehOutlined } from '@ant-design/icons-vue';
import { SelectTypes } from 'ant-design-vue/es/select';
import { defineComponent, ref } from 'vue'; 
export default defineComponent({
  components: {
    SmileOutlined,
    MehOutlined,
  },
  setup() {
    const handleChange = (value: string) => {
      console.log(`selected ${value}`);
    }; 
    const options1 = ref<SelectTypes['options']>([
      {
        value: 'jack',
        label: 'Jack',
      },
      {
        value: 'lucy',
        label: 'Lucy',
      },
      {
        value: 'disabled',
        label: 'Disabled',
        disabled: true,
      },
      {
        value: 'yiminghe',
        label: 'Yiminghe',
      },
    ]);
    const options2 = ref<SelectTypes['options']>([
      {
        value: 'lucy',
        label: 'Lucy',
      },
    ]);
    return {
      handleChange,
      value1: ref('lucy'),
      value2: ref('lucy'),
      options1,
      options2,
    };
  },
});
</script>
lucy
扩展菜单

使用 dropdownRender 对下拉菜单进行自由扩展。

<template>
  <a-select
    v-model:value="value"
    style="width: 120px"
    :options="items.map(item => ({ value: item }))"
  >
    <template #dropdownRender="{ menuNode: menu }">
      <v-nodes :vnodes="menu" />
      <a-divider style="margin: 4px 0" />
      <div
        style="padding: 4px 8px; cursor: pointer"
        @mousedown="e => e.preventDefault()"
        @click="addItem"
      >
        <plus-outlined />
        Add item
      </div>
    </template>
  </a-select>
</template>
<script lang="ts">
import { PlusOutlined } from '@ant-design/icons-vue';
import { defineComponent, ref } from 'vue'; 
let index = 0;
export default defineComponent({
  components: {
    PlusOutlined,
    VNodes: (_, { attrs }) => {
      return attrs.vnodes;
    },
  },
  setup() {
    const items = ref(['jack', 'lucy']);
    const value = ref('lucy'); 
    const addItem = () => {
      console.log('addItem');
      items.value.push(`New item ${index++}`);
    };
    return {
      items,
      value,
      addItem,
    };
  },
});
</script>

10000 Items

a10
c12
大数据

Select 使用了虚拟滚动技术，因而获得了比 1.x 更好的性能

<template>
  <h2>{{ options.length }} Items</h2>
  <a-select
    v-model:value="value"
    mode="multiple"
    style="width: 100%"
    placeholder="Please select"
    :options="options"
  />
</template>
<script lang="ts">
import { defineComponent, reactive } from 'vue';
const options: { value: string; disabled: boolean }[] = [];
for (let i = 0; i < 10000; i++) {
  const value = `${i.toString(36)}${i}`;
  options.push({
    value,
    disabled: i === 10,
  });
}
export default defineComponent({
  setup() {
    const state = reactive({
      options,
      value: ['a10', 'c12'],
    });
    return state;
  },
});
</script>

API#

<a-select>
  <a-select-option value="lucy">lucy</a-select-option>
</a-select>

Select props

参数 说明 类型 默认值 版本
allowClear 支持清除 boolean false
autoClearSearchValue 是否在选中项后清空搜索框，只在 mode 为 multiple 或 tags 时有效。 boolean true
autofocus 默认获取焦点 boolean false
bordered 是否有边框 boolean true
defaultActiveFirstOption 是否默认高亮第一个选项。 boolean true
disabled 是否禁用 boolean false
dropdownClassName 下拉菜单的 className 属性 string -
dropdownMatchSelectWidth 下拉菜单和选择器同宽 boolean true 」
dropdownRender 自定义下拉框内容 ({menuNode: VNode, props}) => VNode | v-slot -
dropdownStyle 下拉菜单的 style 属性 object -
dropdownMenuStyle dropdown 菜单自定义样式 object -
filterOption 是否根据输入项进行筛选。当其为一个函数时，会接收 inputValue option 两个参数，当 option 符合筛选条件时，应返回 true，反之则返回 false。 boolean or function(inputValue, option) true
firstActiveValue 默认高亮的选项 string|string[] -
getPopupContainer 菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。 Function(triggerNode) () => document.body
labelInValue 是否把每个选项的 label 包装到 value 中，会把 Select 的 value 类型从 string 变为 {key: string, label: vNodes} 的格式 boolean false
maxTagCount 最多显示多少个 tag number -
maxTagPlaceholder 隐藏 tag 时显示的内容 slot/function(omittedValues) -
maxTagTextLength 最大显示的 tag 文本长度 number -
mode 设置 Select 的模式为多选或标签 'multiple' | 'tags' | 'combobox' -
notFoundContent 当下拉列表为空时显示的内容 string|slot 'Not Found'
optionFilterProp 搜索时过滤对应的 option 属性，不支持 children string value
optionLabelProp 回填到选择框的 Option 的属性值，默认是 Option 的子元素。比如在子元素需要高亮效果时，此值可以设为 value。 string children （combobox 模式下为 value）
placeholder 选择框默认文字 string|slot -
showSearch 使单选模式可搜索 boolean false
showArrow 是否显示下拉小箭头 boolean true
size 选择框大小，可选 large small string default
suffixIcon 自定义的选择框后缀图标 VNode | slot -
removeIcon 自定义的多选框清除图标 VNode | slot -
clearIcon 自定义的多选框清空图标 VNode | slot -
menuItemSelectedIcon 自定义当前选中的条目图标 VNode | slot -
tokenSeparators 在 tags 和 multiple 模式下自动分词的分隔符 string[]
value(v-model) 指定当前选中的条目 string|string[]|number|number[] -
options options 数据，如果设置则不需要手动构造 selectOption 节点 array<{value, label, [disabled, key, title]}> []
option 通过 option 插槽，自定义节点 v-slot:option="{value, label, [disabled, key, title]}" - 2.2.5
defaultOpen 是否默认展开下拉菜单 boolean -
open 是否展开下拉菜单 boolean -

注意，如果发现下拉菜单跟随页面滚动，或者需要在其他弹层中触发 Select，请尝试使用 getPopupContainer={triggerNode => triggerNode.parentNode} 将下拉弹层渲染节点固定在触发器的父元素中。

事件

事件名称 说明 回调参数
blur 失去焦点的时回调 function
change 选中 option，或 input 的 value 变化（combobox 模式下）时，调用此函数 function(value, option:Option/Array<Option>)
deselect 取消选中时调用，参数为选中项的 value (或 key) 值，仅在 multiple 或 tags 模式下生效 function(value，option:Option)
focus 获得焦点时回调 function
inputKeyDown 键盘按下时回调 function
mouseenter 鼠标移入时回调 function
mouseleave 鼠标移出时回调 function
popupScroll 下拉列表滚动时的回调 function
search 文本框值变化时回调 function(value: string)
select 被选中时调用，参数为选中项的 value (或 key) 值 function(value, option:Option)
dropdownVisibleChange 展开下拉菜单的回调 function(open)

Select Methods

名称 说明
blur() 取消焦点
focus() 获取焦点

Option props

参数 说明 类型 默认值
disabled 是否禁用 boolean false
key 和 value 含义一致。如果 Vue 需要你设置此项，此项值与 value 的值相同，然后可以省略 value 设置 string
title 选中该 Option 后，Select 的 title string -
value 默认根据此属性值进行筛选 string|number -
class Option 器类名 string -

OptGroup props

参数 说明 类型 默认值
key string -
label 组名 string||function(h)|slot 无

FAQ

点击 dropdownRender 里的内容浮层关闭怎么办？

看下 dropdownRender 例子 里的说明。