Select选择器

下拉选择器。

何时使用

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

代码演示

Lucy

基本使用

基本使用。

TypeScript
JavaScript
import React from 'react';
import { Select, Space } from 'antd';

const handleChange = (value: string) => {
  console.log(`selected ${value}`);
};

const App: React.FC = () => (
  <Space wrap>
    <Select
      defaultValue="lucy"
      style={{ width: 120 }}
      onChange={handleChange}
      options={[
        { value: 'jack', label: 'Jack' },
        { value: 'lucy', label: 'Lucy' },
        { value: 'Yiminghe', label: 'yiminghe' },
        { value: 'disabled', label: 'Disabled', disabled: true },
      ]}
    />
    <Select
      defaultValue="lucy"
      style={{ width: 120 }}
      disabled
      options={[{ value: 'lucy', label: 'Lucy' }]}
    />
    <Select
      defaultValue="lucy"
      style={{ width: 120 }}
      loading
      options={[{ value: 'lucy', label: 'Lucy' }]}
    />
    <Select
      defaultValue="lucy"
      style={{ width: 120 }}
      allowClear
      options={[{ value: 'lucy', label: 'Lucy' }]}
    />
  </Space>
);

export default App;

a10

c12

a10

c12

多选

多选，从已有条目中选择。

TypeScript
JavaScript
import React from 'react';
import { Select, Space } from 'antd';
import type { SelectProps } from 'antd';

const options: SelectProps['options'] = [];

for (let i = 10; i < 36; i++) {
  options.push({
    label: i.toString(36) + i,
    value: i.toString(36) + i,
  });
}

const handleChange = (value: string[]) => {
  console.log(`selected ${value}`);
};

const App: React.FC = () => (
  <Space style={{ width: '100%' }} direction="vertical">
    <Select
      mode="multiple"
      allowClear
      style={{ width: '100%' }}
      placeholder="Please select"
      defaultValue={['a10', 'c12']}
      onChange={handleChange}
      options={options}
    />
    <Select
      mode="multiple"
      disabled
      style={{ width: '100%' }}
      placeholder="Please select"
      defaultValue={['a10', 'c12']}
      onChange={handleChange}
      options={options}
    />
  </Space>
);

export default App;

China

定制回填内容

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

TypeScript
JavaScript
import React from 'react';
import { Select, Space } from 'antd';

const { Option } = Select;

const handleChange = (value: string[]) => {
  console.log(`selected ${value}`);
};

const App: React.FC = () => (
  <Select
    mode="multiple"
    style={{ width: '100%' }}
    placeholder="select one country"
    defaultValue={['china']}
    onChange={handleChange}
    optionLabelProp="label"
  >
    <Option value="china" label="China">
      <Space>
        <span role="img" aria-label="China">
          🇨🇳
        </span>
        China (中国)
      </Space>
    </Option>
    <Option value="usa" label="USA">
      <Space>
        <span role="img" aria-label="USA">
          🇺🇸
        </span>
        USA (美国)
      </Space>
    </Option>
    <Option value="japan" label="Japan">
      <Space>
        <span role="img" aria-label="Japan">
          🇯🇵
        </span>
        Japan (日本)
      </Space>
    </Option>
    <Option value="korea" label="Korea">
      <Space>
        <span role="img" aria-label="Korea">
          🇰🇷
        </span>
        Korea (韩国)
      </Space>
    </Option>
  </Select>
);

export default App;

Tags Mode

标签

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

TypeScript
JavaScript
import React from 'react';
import { Select } from 'antd';
import type { SelectProps } from 'antd';

const options: SelectProps['options'] = [];

for (let i = 10; i < 36; i++) {
  options.push({
    value: i.toString(36) + i,
    label: i.toString(36) + i,
  });
}

const handleChange = (value: string) => {
  console.log(`selected ${value}`);
};

const App: React.FC = () => (
  <Select
    mode="tags"
    style={{ width: '100%' }}
    placeholder="Tags Mode"
    onChange={handleChange}
    options={options}
  />
);

export default App;

Zhejiang

Hangzhou

联动

省市联动是典型的例子。

推荐使用 Cascader 组件。

TypeScript
JavaScript
import React, { useState } from 'react';
import { Select, Space } from 'antd';

const provinceData = ['Zhejiang', 'Jiangsu'];

const cityData = {
  Zhejiang: ['Hangzhou', 'Ningbo', 'Wenzhou'],
  Jiangsu: ['Nanjing', 'Suzhou', 'Zhenjiang'],
};

type CityName = keyof typeof cityData;

const App: React.FC = () => {
  const [cities, setCities] = useState(cityData[provinceData[0] as CityName]);
  const [secondCity, setSecondCity] = useState(cityData[provinceData[0] as CityName][0]);

  const handleProvinceChange = (value: CityName) => {
    setCities(cityData[value]);
    setSecondCity(cityData[value][0]);
  };

  const onSecondCityChange = (value: CityName) => {
    setSecondCity(value);
  };

  return (
    <Space wrap>
      <Select
        defaultValue={provinceData[0]}
        style={{ width: 120 }}
        onChange={handleProvinceChange}
        options={provinceData.map((province) => ({ label: province, value: province }))}
      />
      <Select
        style={{ width: 120 }}
        value={secondCity}
        onChange={onSecondCityChange}
        options={cities.map((city) => ({ label: city, value: city }))}
      />
    </Space>
  );
};

export default App;

Lucy (101)

获得选项的文本

默认情况下 onChange 里只能拿到 value，如果需要拿到选中的节点文本 label，可以使用 labelInValue 属性。

选中项的 label 会被包装到 value 中传递给 onChange 等函数，此时 value 是一个对象。

TypeScript
JavaScript
import React from 'react';
import { Select } from 'antd';

const handleChange = (value: { value: string; label: React.ReactNode }) => {
  console.log(value); // { value: "lucy", key: "lucy", label: "Lucy (101)" }
};

const App: React.FC = () => (
  <Select
    labelInValue
    defaultValue={{ value: 'lucy', label: 'Lucy (101)' }}
    style={{ width: 120 }}
    onChange={handleChange}
    options={[
      {
        value: 'jack',
        label: 'Jack (100)',
      },
      {
        value: 'lucy',
        label: 'Lucy (101)',
      },
    ]}
  />
);

export default App;

Select users

搜索用户

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

TypeScript
JavaScript
import React, { useMemo, useRef, useState } from 'react';
import { Select, Spin } from 'antd';
import type { SelectProps } from 'antd/es/select';
import debounce from 'lodash/debounce';

export interface DebounceSelectProps<ValueType = any>
  extends Omit<SelectProps<ValueType | ValueType[]>, 'options' | 'children'> {
  fetchOptions: (search: string) => Promise<ValueType[]>;
  debounceTimeout?: number;
}

function DebounceSelect<
  ValueType extends { key?: string; label: React.ReactNode; value: string | number } = any,
>({ fetchOptions, debounceTimeout = 800, ...props }: DebounceSelectProps<ValueType>) {
  const [fetching, setFetching] = useState(false);
  const [options, setOptions] = useState<ValueType[]>([]);
  const fetchRef = useRef(0);

  const debounceFetcher = useMemo(() => {
    const loadOptions = (value: string) => {
      fetchRef.current += 1;
      const fetchId = fetchRef.current;
      setOptions([]);
      setFetching(true);

      fetchOptions(value).then((newOptions) => {
        if (fetchId !== fetchRef.current) {
          // for fetch callback order
          return;
        }

        setOptions(newOptions);
        setFetching(false);
      });
    };

    return debounce(loadOptions, debounceTimeout);
  }, [fetchOptions, debounceTimeout]);

  return (
    <Select
      labelInValue
      filterOption={false}
      onSearch={debounceFetcher}
      notFoundContent={fetching ? <Spin size="small" /> : null}
      {...props}
      options={options}
    />
  );
}

// Usage of DebounceSelect
interface UserValue {
  label: string;
  value: string;
}

async function fetchUserList(username: string): Promise<UserValue[]> {
  console.log('fetching user', username);

  return fetch('https://randomuser.me/api/?results=5')
    .then((response) => response.json())
    .then((body) =>
      body.results.map(
        (user: { name: { first: string; last: string }; login: { username: string } }) => ({
          label: `${user.name.first} ${user.name.last}`,
          value: user.login.username,
        }),
      ),
    );
}

const App: React.FC = () => {
  const [value, setValue] = useState<UserValue[]>([]);

  return (
    <DebounceSelect
      mode="multiple"
      value={value}
      placeholder="Select users"
      fetchOptions={fetchUserList}
      onChange={(newValue) => {
        setValue(newValue as UserValue[]);
      }}
      style={{ width: '100%' }}
    />
  );
};

export default App;

Inserted are removed

隐藏已选择选项

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

TypeScript
JavaScript
import React, { useState } from 'react';
import { Select } from 'antd';

const OPTIONS = ['Apples', 'Nails', 'Bananas', 'Helicopters'];

const App: React.FC = () => {
  const [selectedItems, setSelectedItems] = useState<string[]>([]);

  const filteredOptions = OPTIONS.filter((o) => !selectedItems.includes(o));

  return (
    <Select
      mode="multiple"
      placeholder="Inserted are removed"
      value={selectedItems}
      onChange={setSelectedItems}
      style={{ width: '100%' }}
      options={filteredOptions.map((item) => ({
        value: item,
        label: item,
      }))}
    />
  );
};

export default App;

gold

cyan

自定义选择标签

允许自定义选择标签的样式。

TypeScript
JavaScript
import React from 'react';
import { Select, Tag } from 'antd';
import type { CustomTagProps } from 'rc-select/lib/BaseSelect';

const options = [{ value: 'gold' }, { value: 'lime' }, { value: 'green' }, { value: 'cyan' }];

const tagRender = (props: CustomTagProps) => {
  const { label, value, closable, onClose } = props;
  const onPreventMouseDown = (event: React.MouseEvent<HTMLSpanElement>) => {
    event.preventDefault();
    event.stopPropagation();
  };
  return (
    <Tag
      color={value}
      onMouseDown={onPreventMouseDown}
      closable={closable}
      onClose={onClose}
      style={{ marginRight: 3 }}
    >
      {label}
    </Tag>
  );
};

const App: React.FC = () => (
  <Select
    mode="multiple"
    showArrow
    tagRender={tagRender}
    defaultValue={['gold', 'cyan']}
    style={{ width: '100%' }}
    options={options}
  />
);

export default App;

Ant Design 4.0

100000 Items

a10

c12

Ant Design 3.0

大数据

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

TypeScript
JavaScript
import React from 'react';
import type { SelectProps } from 'antd';
import { Divider, Select, Typography } from 'antd';

const { Title } = Typography;

const options: SelectProps['options'] = [];

for (let i = 0; i < 100000; i++) {
  const value = `${i.toString(36)}${i}`;
  options.push({
    label: value,
    value,
    disabled: i === 10,
  });
}

const handleChange = (value: string[]) => {
  console.log(`selected ${value}`);
};

const App: React.FC = () => (
  <>
    <Title level={3}>Ant Design 4.0</Title>
    <Title level={4}>{options.length} Items</Title>
    <Select
      mode="multiple"
      style={{ width: '100%' }}
      placeholder="Please select"
      defaultValue={['a10', 'c12']}
      onChange={handleChange}
      options={options}
    />

    <Divider />

    <Title level={3}>Ant Design 3.0</Title>
    <iframe
      title="Ant Design 3.0 Select demo"
      src="https://codesandbox.io/embed/solitary-voice-m3vme?fontsize=14&hidenavigation=1&theme=dark&view=preview"
      style={{ width: '100%', height: 300 }}
    />
  </>
);

export default App;

topLefttopRightbottomLeftbottomRight

HangZhou #310000

弹出位置

可以通过 placement 手动指定弹出的位置。

TypeScript
JavaScript
import React, { useState } from 'react';
import type { RadioChangeEvent } from 'antd';
import { Radio, Select } from 'antd';
import type { SelectCommonPlacement } from 'antd/es/_util/motion';

const App: React.FC = () => {
  const [placement, SetPlacement] = useState<SelectCommonPlacement>('topLeft');

  const placementChange = (e: RadioChangeEvent) => {
    SetPlacement(e.target.value);
  };

  return (
    <>
      <Radio.Group value={placement} onChange={placementChange}>
        <Radio.Button value="topLeft">topLeft</Radio.Button>
        <Radio.Button value="topRight">topRight</Radio.Button>
        <Radio.Button value="bottomLeft">bottomLeft</Radio.Button>
        <Radio.Button value="bottomRight">bottomRight</Radio.Button>
      </Radio.Group>
      <br />
      <br />
      <Select
        defaultValue="HangZhou"
        style={{ width: 120 }}
        dropdownMatchSelectWidth={false}
        placement={placement}
        options={[
          {
            value: 'HangZhou',
            label: 'HangZhou #310000',
          },
          {
            value: 'NingBo',
            label: 'NingBo #315000',
          },
          {
            value: 'WenZhou',
            label: 'WenZhou #325000',
          },
        ]}
      />
    </>
  );
};

export default App;

Select a person

带搜索框

展开后可对选项进行搜索。

TypeScript
JavaScript
import React from 'react';
import { Select } from 'antd';

const onChange = (value: string) => {
  console.log(`selected ${value}`);
};

const onSearch = (value: string) => {
  console.log('search:', value);
};

const App: React.FC = () => (
  <Select
    showSearch
    placeholder="Select a person"
    optionFilterProp="children"
    onChange={onChange}
    onSearch={onSearch}
    filterOption={(input, option) =>
      (option?.label ?? '').toLowerCase().includes(input.toLowerCase())
    }
    options={[
      {
        value: 'jack',
        label: 'Jack',
      },
      {
        value: 'lucy',
        label: 'Lucy',
      },
      {
        value: 'tom',
        label: 'Tom',
      },
    ]}
  />
);

export default App;

LargeDefaultSmall

a10

c12

a10

c12

三种大小

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

TypeScript
JavaScript
import React, { useState } from 'react';
import { Radio, Select, Space } from 'antd';
import type { SizeType } from 'antd/es/config-provider/SizeContext';
import type { SelectProps, RadioChangeEvent } from 'antd';

const options: SelectProps['options'] = [];

for (let i = 10; i < 36; i++) {
  options.push({
    value: i.toString(36) + i,
    label: i.toString(36) + i,
  });
}

const handleChange = (value: string | string[]) => {
  console.log(`Selected: ${value}`);
};

const App: React.FC = () => {
  const [size, setSize] = useState<SizeType>('middle');

  const handleSizeChange = (e: RadioChangeEvent) => {
    setSize(e.target.value);
  };

  return (
    <>
      <Radio.Group value={size} onChange={handleSizeChange}>
        <Radio.Button value="large">Large</Radio.Button>
        <Radio.Button value="middle">Default</Radio.Button>
        <Radio.Button value="small">Small</Radio.Button>
      </Radio.Group>
      <br />
      <br />
      <Space direction="vertical" style={{ width: '100%' }}>
        <Select
          size={size}
          defaultValue="a1"
          onChange={handleChange}
          style={{ width: 200 }}
          options={options}
        />
        <Select
          mode="multiple"
          size={size}
          placeholder="Please select"
          defaultValue={['a10', 'c12']}
          onChange={handleChange}
          style={{ width: '100%' }}
          options={options}
        />
        <Select
          mode="tags"
          size={size}
          placeholder="Please select"
          defaultValue={['a10', 'c12']}
          onChange={handleChange}
          style={{ width: '100%' }}
          options={options}
        />
      </Space>
    </>
  );
};

export default App;

Search to Select

带排序的搜索

在搜索模式下对过滤结果项进行排序。

TypeScript
JavaScript
import React from 'react';
import { Select } from 'antd';

const App: React.FC = () => (
  <Select
    showSearch
    style={{ width: 200 }}
    placeholder="Search to Select"
    optionFilterProp="children"
    filterOption={(input, option) => (option?.label ?? '').includes(input)}
    filterSort={(optionA, optionB) =>
      (optionA?.label ?? '').toLowerCase().localeCompare((optionB?.label ?? '').toLowerCase())
    }
    options={[
      {
        value: '1',
        label: 'Not Identified',
      },
      {
        value: '2',
        label: 'Closed',
      },
      {
        value: '3',
        label: 'Communicated',
      },
      {
        value: '4',
        label: 'Identified',
      },
      {
        value: '5',
        label: 'Resolved',
      },
      {
        value: '6',
        label: 'Cancelled',
      },
    ]}
  />
);

export default App;

Lucy

分组

用 OptGroup 进行选项分组。

TypeScript
JavaScript
import React from 'react';
import { Select } from 'antd';

const handleChange = (value: string) => {
  console.log(`selected ${value}`);
};

const App: React.FC = () => (
  <Select
    defaultValue="lucy"
    style={{ width: 200 }}
    onChange={handleChange}
    options={[
      {
        label: 'Manager',
        options: [
          { label: 'Jack', value: 'jack' },
          { label: 'Lucy', value: 'lucy' },
        ],
      },
      {
        label: 'Engineer',
        options: [{ label: 'yiminghe', value: 'Yiminghe' }],
      },
    ]}
  />
);

export default App;

input search text

搜索框

搜索和远程数据结合。

TypeScript
JavaScript
import React, { useState } from 'react';
import { Select } from 'antd';
import jsonp from 'fetch-jsonp';
import qs from 'qs';
import type { SelectProps } from 'antd';

let timeout: ReturnType<typeof setTimeout> | null;
let currentValue: string;

const fetch = (value: string, callback: Function) => {
  if (timeout) {
    clearTimeout(timeout);
    timeout = null;
  }
  currentValue = value;

  const fake = () => {
    const str = qs.stringify({
      code: 'utf-8',
      q: value,
    });
    jsonp(`https://suggest.taobao.com/sug?${str}`)
      .then((response: any) => response.json())
      .then((d: any) => {
        if (currentValue === value) {
          const { result } = d;
          const data = result.map((item: any) => ({
            value: item[0],
            text: item[0],
          }));
          callback(data);
        }
      });
  };

  timeout = setTimeout(fake, 300);
};

const SearchInput: React.FC<{ placeholder: string; style: React.CSSProperties }> = (props) => {
  const [data, setData] = useState<SelectProps['options']>([]);
  const [value, setValue] = useState<string>();

  const handleSearch = (newValue: string) => {
    if (newValue) {
      fetch(newValue, setData);
    } else {
      setData([]);
    }
  };

  const handleChange = (newValue: string) => {
    setValue(newValue);
  };

  return (
    <Select
      showSearch
      value={value}
      placeholder={props.placeholder}
      style={props.style}
      defaultActiveFirstOption={false}
      showArrow={false}
      filterOption={false}
      onSearch={handleSearch}
      onChange={handleChange}
      notFoundContent={null}
      options={(data || []).map((d) => ({
        value: d.value,
        label: d.text,
      }))}
    />
  );
};

const App: React.FC = () => <SearchInput placeholder="input search text" style={{ width: 200 }} />;

export default App;

自动分词

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

TypeScript
JavaScript
import React from 'react';
import { Select } from 'antd';
import type { SelectProps } from 'antd';

const options: SelectProps['options'] = [];

for (let i = 10; i < 36; i++) {
  options.push({
    value: i.toString(36) + i,
    label: i.toString(36) + i,
  });
}

const handleChange = (value: string) => {
  console.log(`selected ${value}`);
};

const App: React.FC = () => (
  <Select
    mode="tags"
    style={{ width: '100%' }}
    onChange={handleChange}
    tokenSeparators={[',']}
    options={options}
  />
);

export default App;

custom dropdown render

扩展菜单

使用 dropdownRender 对下拉菜单进行自由扩展。如果希望点击自定义内容后关闭浮层，你需要使用受控模式自行控制（codesandbox）。

TypeScript
JavaScript
import React, { useState, useRef } from 'react';
import { PlusOutlined } from '@ant-design/icons';
import { Divider, Input, Select, Space, Button } from 'antd';
import type { InputRef } from 'antd';

let index = 0;

const App: React.FC = () => {
  const [items, setItems] = useState(['jack', 'lucy']);
  const [name, setName] = useState('');
  const inputRef = useRef<InputRef>(null);

  const onNameChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setName(event.target.value);
  };

  const addItem = (e: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => {
    e.preventDefault();
    setItems([...items, name || `New item ${index++}`]);
    setName('');
    setTimeout(() => {
      inputRef.current?.focus();
    }, 0);
  };

  return (
    <Select
      style={{ width: 300 }}
      placeholder="custom dropdown render"
      dropdownRender={(menu) => (
        <>
          {menu}
          <Divider style={{ margin: '8px 0' }} />
          <Space style={{ padding: '0 8px 4px' }}>
            <Input
              placeholder="Please enter item"
              ref={inputRef}
              value={name}
              onChange={onNameChange}
            />
            <Button type="text" icon={<PlusOutlined />} onClick={addItem}>
              Add item
            </Button>
          </Space>
        </>
      )}
      options={items.map((item) => ({ label: item, value: item }))}
    />
  );
};

export default App;

Lucy

无边框

无边框样式。

TypeScript
JavaScript
import { Select, Space } from 'antd';
import React from 'react';

const App: React.FC = () => (
  <Space wrap>
    <Select
      defaultValue="lucy"
      style={{ width: 120 }}
      bordered={false}
      options={[
        { value: 'jack', label: 'Jack' },
        { value: 'lucy', label: 'Lucy' },
        { value: 'Yiminghe', label: 'yiminghe' },
      ]}
    />
    <Select
      defaultValue="lucy"
      style={{ width: 120 }}
      disabled
      bordered={false}
      options={[{ value: 'lucy', label: 'Lucy' }]}
    />
  </Space>
);

export default App;

响应式 maxTagCount

多选下通过响应式布局让选项自动收缩。该功能对性能有所消耗，不推荐在大表单场景下使用。

TypeScript
JavaScript
import React, { useState } from 'react';
import type { SelectProps } from 'antd';
import { Select, Space } from 'antd';

interface ItemProps {
  label: string;
  value: string;
}

const options: ItemProps[] = [];

for (let i = 10; i < 36; i++) {
  const value = i.toString(36) + i;
  options.push({
    label: `Long Label: ${value}`,
    value,
  });
}

const App: React.FC = () => {
  const [value, setValue] = useState(['a10', 'c12', 'h17', 'j19', 'k20']);

  const selectProps: SelectProps = {
    mode: 'multiple',
    style: { width: '100%' },
    value,
    options,
    onChange: (newValue: string[]) => {
      setValue(newValue);
    },
    placeholder: 'Select Item...',
    maxTagCount: 'responsive',
  };

  return (
    <Space direction="vertical" style={{ width: '100%' }}>
      <Select {...selectProps} />
      <Select {...selectProps} disabled />
    </Space>
  );
};

export default App;

自定义状态

使用 status 为 Select 添加状态，可选 error 或者 warning。

TypeScript
JavaScript
import React from 'react';
import { Select, Space } from 'antd';

const App: React.FC = () => (
  <Space direction="vertical" style={{ width: '100%' }}>
    <Select status="error" style={{ width: '100%' }} />
    <Select status="warning" style={{ width: '100%' }} />
  </Space>
);

export default App;

API

<Select>
  <Option value="lucy">lucy</Option>
</Select>

Select props

参数	说明	类型	默认值	版本
allowClear	支持清除	boolean	false
autoClearSearchValue	是否在选中项后清空搜索框，只在 `mode` 为 `multiple` 或 `tags` 时有效	boolean	true
autoFocus	默认获取焦点	boolean	false
bordered	是否有边框	boolean	true
clearIcon	自定义的多选框清空图标	ReactNode	-
defaultActiveFirstOption	是否默认高亮第一个选项	boolean	true
defaultOpen	是否默认展开下拉菜单	boolean	-
defaultValue	指定默认选中的条目	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
disabled	是否禁用	boolean	false
popupClassName	下拉菜单的 className 属性	string	-	4.23.0
dropdownMatchSelectWidth	下拉菜单和选择器同宽。默认将设置 `min-width`，当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动	boolean \| number	true
dropdownRender	自定义下拉框内容	(originNode: ReactNode) => ReactNode	-
dropdownStyle	下拉菜单的 style 属性	CSSProperties	-
fieldNames	自定义节点 label、value、options 的字段	object	{ label: `label`, value: `value`, options: `options` }	4.17.0
filterOption	是否根据输入项进行筛选。当其为一个函数时，会接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 true，反之则返回 false	boolean \| function(inputValue, option)	true
filterSort	搜索时对筛选结果项的排序函数, 类似Array.sort里的 compareFunction	(optionA: Option, optionB: Option) => number	-	4.9.0
getPopupContainer	菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。示例	function(triggerNode)	() => document.body
labelInValue	是否把每个选项的 label 包装到 value 中，会把 Select 的 value 类型从 `string` 变为 { value: string, label: ReactNode } 的格式	boolean	false
listHeight	设置弹窗滚动高度	number	256
loading	加载中状态	boolean	false
maxTagCount	最多显示多少个 tag，响应式模式会对性能产生损耗	number \| `responsive`	-	responsive: 4.10
maxTagPlaceholder	隐藏 tag 时显示的内容	ReactNode \| function(omittedValues)	-
maxTagTextLength	最大显示的 tag 文本长度	number	-
menuItemSelectedIcon	自定义多选时当前选中的条目图标	ReactNode	-
mode	设置 Select 的模式为多选或标签	`multiple` \| `tags`	-
notFoundContent	当下拉列表为空时显示的内容	ReactNode	`Not Found`
open	是否展开下拉菜单	boolean	-
optionFilterProp	搜索时过滤对应的 `option` 属性，如设置为 `children` 表示对内嵌内容进行搜索。若通过 `options` 属性配置选项内容，建议设置 `optionFilterProp="label"` 来对内容进行搜索。	string	`value`
optionLabelProp	回填到选择框的 Option 的属性值，默认是 Option 的子元素。比如在子元素需要高亮效果时，此值可以设为 `value`。示例	string	`children`
options	数据化配置选项内容，相比 jsx 定义会获得更好的渲染性能	{ label, value }[]	-
placeholder	选择框默认文本	string	-
placement	选择框弹出的位置	`bottomLeft` `bottomRight` `topLeft` `topRight`	bottomLeft
removeIcon	自定义的多选框清除图标	ReactNode	-
searchValue	控制搜索文本	string	-
showArrow	是否显示下拉小箭头	boolean	单选为 true，多选为 false
showSearch	配置是否可搜索	boolean	单选为 false，多选为 true
size	选择框大小	`large` \| `middle` \| `small`	`middle`
status	设置校验状态	'error' \| 'warning'	-	4.19.0
suffixIcon	自定义的选择框后缀图标	ReactNode	-
tagRender	自定义 tag 内容 render，仅在 `mode` 为 `multiple` 或 `tags` 时生效	(props) => ReactNode	-
tokenSeparators	自动分词的分隔符，仅在 `mode="tags"` 时生效	string[]	-
value	指定当前选中的条目，多选时为一个数组。（value 数组引用未变化时，Select 不会更新）	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
virtual	设置 false 时关闭虚拟滚动	boolean	true	4.1.0
onBlur	失去焦点时回调	function	-
onChange	选中 option，或 input 的 value 变化时，调用此函数	function(value, option:Option \| Array<Option>)	-
onClear	清除内容时回调	function	-	4.6.0
onDeselect	取消选中时调用，参数为选中项的 value (或 key) 值，仅在 `multiple` 或 `tags` 模式下生效	function(value: string \| number \| LabeledValue)	-
onDropdownVisibleChange	展开下拉菜单的回调	function(open)	-
onFocus	获得焦点时回调	function	-
onInputKeyDown	按键按下时回调	function	-
onMouseEnter	鼠标移入时回调	function	-
onMouseLeave	鼠标移出时回调	function	-
onPopupScroll	下拉列表滚动时的回调	function	-
onSearch	文本框值变化时回调	function(value: string)	-
onSelect	被选中时调用，参数为选中项的 value (或 key) 值	function(value: string \| number \| LabeledValue, option: Option)	-

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

Select Methods

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

Option props

参数	说明	类型	默认值
className	Option 器类名	string	-
disabled	是否禁用	boolean	false
title	选项上的原生 title 提示	string	-
value	默认根据此属性值进行筛选	string \| number	-

OptGroup props

参数	说明	类型	默认值	版本
key	Key	string	-
label	组名	string \| React.Element	-

Design Token

Global Token

Token 名称	描述	类型	默认值
colorBgContainer	组件的容器背景色，例如：默认按钮、输入框等。务必不要将其与 `colorBgElevated` 混淆。	string	#ffffff
colorBgContainerDisabled	控制容器在禁用状态下的背景色。	string	rgba(0, 0, 0, 0.04)
colorBgElevated	浮层容器背景色，在暗色模式下该 token 的色值会比 `colorBgContainer` 要亮一些。例如：模态框、弹出框、菜单等。	string	#ffffff
colorBorder	默认使用的边框颜色, 用于分割不同的元素，例如：表单的分割线、卡片的分割线等。	string	#d9d9d9
colorErrorHover	错误色的深色悬浮态	string	#ff7875
colorErrorOutline	控制输入组件错误状态下的外轮廓线颜色。	string	rgba(255, 38, 5, 0.06)
colorFillSecondary	二级填充色可以较为明显地勾勒出元素形体，如 Rate、Skeleton 等。也可以作为三级填充色的 Hover 状态，如 Table 等。	string	rgba(0, 0, 0, 0.06)
colorIcon	控制弱操作图标的颜色，例如 allowClear 或 Alert 关闭按钮。 *	string	rgba(0, 0, 0, 0.45)
colorIconHover	控制弱操作图标在悬浮状态下的颜色，例如 allowClear 或 Alert 关闭按钮。	string	rgba(0, 0, 0, 0.88)
colorPrimary	品牌色是体现产品特性和传播理念最直观的视觉元素之一。在你完成品牌主色的选取之后，我们会自动帮你生成一套完整的色板，并赋予它们有效的设计语义	string	#1677ff
colorPrimaryHover	主色梯度下的悬浮态。	string	#4096ff
colorSplit	用于作为分割线的颜色，此颜色和 colorBorderSecondary 的颜色一致，但是用的是透明色。	string	rgba(5, 5, 5, 0.06)
colorText	最深的文本色。为了符合W3C标准，默认的文本颜色使用了该色，同时这个颜色也是最深的中性色。	string	rgba(0, 0, 0, 0.88)
colorTextDescription	控制文本描述字体颜色。	string	rgba(0, 0, 0, 0.45)
colorTextDisabled	控制禁用状态下的字体颜色。	string	rgba(0, 0, 0, 0.25)
colorTextPlaceholder	控制占位文本的颜色。	string	rgba(0, 0, 0, 0.25)
colorTextQuaternary	第四级文本色是最浅的文本色，例如表单的输入提示文本、禁用色文本等。	string	rgba(0, 0, 0, 0.25)
colorTextTertiary	第三级文本色一般用于描述性文本，例如表单的中的补充说明文本、列表的描述性文本等场景。	string	rgba(0, 0, 0, 0.45)
colorWarningHover	警戒色的深色悬浮态	string	#ffd666
colorWarningOutline	控制输入组件警告状态下的外轮廓线颜色。	string	rgba(255, 215, 5, 0.1)
borderRadius	基础组件的圆角大小，例如按钮、输入框、卡片等	number	6
borderRadiusLG	LG号圆角，用于组件中的一些大圆角，如 Card、Modal 等一些组件样式。	number	8
borderRadiusSM	SM号圆角，用于组件小尺寸下的圆角，如 Button、Input、Select 等输入类控件在 small size 下的圆角	number	4
borderRadiusXS	XS号圆角，用于组件中的一些小圆角，如 Segmented 、Arrow 等一些内部圆角的组件样式中。	number	2
boxShadowSecondary	控制元素二级阴影样式。	string	0 6px 16px 0 rgba(0, 0, 0, 0.08), 0 3px 6px -4px rgba(0, 0, 0, 0.12), 0 9px 28px 8px rgba(0, 0, 0, 0.05)
controlHeight	Ant Design 中按钮和输入框等基础控件的高度	number	32
controlHeightLG	较高的组件高度	number	40
controlHeightSM	较小的组件高度	number	24
controlHeightXS	更小的组件高度	number	16
controlItemBgActive	控制组件项在激活状态下的背景颜色。	string	#e6f4ff
controlItemBgHover	控制组件项在鼠标悬浮时的背景颜色。	string	rgba(0, 0, 0, 0.04)
controlOutline	控制输入组件的外轮廓线颜色。	string	rgba(5, 145, 255, 0.1)
controlOutlineWidth	控制输入组件的外轮廓线宽度。	number	2
controlPaddingHorizontal	控制元素水平内间距。	number	12
controlPaddingHorizontalSM	控制元素中小尺寸水平内间距。	number	8
fontFamily	Ant Design 的字体家族中优先使用系统默认的界面字体，同时提供了一套利于屏显的备用字体库，来维护在不同平台以及浏览器的显示下，字体始终保持良好的易读性和可读性，体现了友好、稳定和专业的特性。	string	-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'
fontSize	设计系统中使用最广泛的字体大小，文本梯度也将基于该字号进行派生。	number	14
fontSizeIcon	控制选择器、级联选择器等中的操作图标字体大小。正常情况下与 fontSizeSM 相同。	number	12
fontSizeLG	大号字体大小	number	16
fontSizeSM	小号字体大小	number	12
fontWeightStrong	控制标题类组件（如 h1、h2、h3）或选中项的字体粗细。	number	600
lineHeight	文本行高	number	1.5714285714285714
lineType	用于控制组件边框、分割线等的样式，默认是实线	string	solid
lineWidth	用于控制组件边框、分割线等的宽度	number	1
motionDurationMid	动效播放速度，中速。用于中型元素动画交互	string	0.2s
motionDurationSlow	动效播放速度，慢速。用于大型元素如面板动画交互	string	0.3s
motionEaseInOut	预设动效曲率	string	cubic-bezier(0.645, 0.045, 0.355, 1)
motionEaseInOutCirc	预设动效曲率	string	cubic-bezier(0.78, 0.14, 0.15, 0.86)
motionEaseInQuint	预设动效曲率	string	cubic-bezier(0.755, 0.05, 0.855, 0.06)
motionEaseOutCirc	预设动效曲率	string	cubic-bezier(0.08, 0.82, 0.17, 1)
motionEaseOutQuint	预设动效曲率	string	cubic-bezier(0.23, 1, 0.32, 1)
paddingSM	控制元素的小内间距。	number	12
paddingXS	控制元素的特小内间距。	number	8
paddingXXS	控制元素的极小内间距。	number	4
zIndexPopupBase	浮层类组件的基础 Z 轴值，用于一些悬浮类的组件的可以基于该值 Z 轴控制层级，例如 FloatButton、 Affix、Modal 等	number	1000

FAQ

`mode="tags"` 模式下为何搜索有时会出现两个相同选项？

这一般是 options 中的 label 和 value 不同导致的，你可以通过 optionFilterProp="label" 将过滤设置为展示值以避免这种情况。

点击 `dropdownRender` 里的元素，下拉菜单不会自动消失？

你可以使用受控模式，手动设置 open 属性：codesandbox。

反过来希望点击 `dropdownRender` 里元素不消失该怎么办？

Select 当失去焦点时会关闭下拉框，如果你可以通过阻止默认行为避免丢失焦点导致的关闭：

<Select
  dropdownRender={() => (
    <div
      onMouseDown={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
    >
      Some Content
    </div>
  )}
/>

自定义 Option 样式导致滚动异常怎么办？

这是由于虚拟滚动默认选项高度为 24px，如果你的选项高度小于该值则需要通过 listItemHeight 属性调整，而 listHeight 用于设置滚动容器高度：

<Select listItemHeight={10} listHeight={250} />

注意：listItemHeight 和 listHeight 为内部属性，如无必要，请勿修改该值。

为何无障碍测试会报缺失 `aria-` 属性？

Select 无障碍辅助元素仅在弹窗展开时创建，因而当你在进行无障碍检测时请先打开下拉后再进行测试。对于 aria-label 与 aria-labelledby 属性缺失警告，请自行为 Select 组件添加相应无障碍属性。

Select 虚拟滚动会模拟无障碍绑定元素。如果需要读屏器完整获取全部列表，你可以设置 virtual={false} 关闭虚拟滚动，无障碍选项将会绑定到真实元素上。

Select选择器

Select选择器

何时使用

代码演示

Ant Design 4.0

100000 Items

Ant Design 3.0

API

Select props

Select Methods

Option props

OptGroup props

Design Token

Global Token

FAQ

mode="tags" 模式下为何搜索有时会出现两个相同选项？

点击 dropdownRender 里的元素，下拉菜单不会自动消失？

反过来希望点击 dropdownRender 里元素不消失该怎么办？

自定义 Option 样式导致滚动异常怎么办？

为何无障碍测试会报缺失 aria- 属性？

何时使用

代码演示

Ant Design 4.0

100000 Items

Ant Design 3.0

API

Select props

Select Methods

Option props

OptGroup props

Design Token

Global Token

FAQ

mode="tags" 模式下为何搜索有时会出现两个相同选项？

点击 dropdownRender 里的元素，下拉菜单不会自动消失？

反过来希望点击 dropdownRender 里元素不消失该怎么办？

自定义 Option 样式导致滚动异常怎么办？

为何无障碍测试会报缺失 aria- 属性？

`mode="tags"` 模式下为何搜索有时会出现两个相同选项？

点击 `dropdownRender` 里的元素，下拉菜单不会自动消失？

反过来希望点击 `dropdownRender` 里元素不消失该怎么办？

为何无障碍测试会报缺失 `aria-` 属性？

`mode="tags"` 模式下为何搜索有时会出现两个相同选项？

点击 `dropdownRender` 里的元素，下拉菜单不会自动消失？

反过来希望点击 `dropdownRender` 里元素不消失该怎么办？

为何无障碍测试会报缺失 `aria-` 属性？