Select 选择器 #

概述 #

Select 选择器用于从一组选项中选择一个或多个值，支持搜索、远程加载等功能。

基础用法 #

基本选择器 #

tsx

import { Select } from 'antd';

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

<Select
  style={{ width: 200 }}
  onChange={handleChange}
  options={[
    { value: 'jack', label: 'Jack' },
    { value: 'lucy', label: 'Lucy' },
    { value: 'disabled', label: 'Disabled', disabled: true },
  ]}
/>

三种大小 #

tsx

import { Select, Space } from 'antd';

<Space direction="vertical">
  <Select size="large" style={{ width: 200 }} options={options} />
  <Select style={{ width: 200 }} options={options} />
  <Select size="small" style={{ width: 200 }} options={options} />
</Space>

禁用状态 #

tsx

import { Select } from 'antd';

<Select disabled style={{ width: 200 }} options={options} />

禁用选项 #

tsx

import { Select } from 'antd';

<Select
  style={{ width: 200 }}
  options={[
    { value: 'jack', label: 'Jack' },
    { value: 'lucy', label: 'Lucy', disabled: true },
  ]}
/>

多选 #

多选模式 #

tsx

import { Select } from 'antd';

<Select
  mode="multiple"
  style={{ width: '100%' }}
  placeholder="请选择"
  options={options}
/>

标签模式 #

tsx

import { Select } from 'antd';

<Select
  mode="tags"
  style={{ width: '100%' }}
  placeholder="请输入标签"
  options={options}
/>

限制数量 #

tsx

import { Select } from 'antd';

<Select
  mode="multiple"
  maxTagCount={2}
  style={{ width: '100%' }}
  options={options}
/>

搜索功能 #

基本搜索 #

tsx

import { Select } from 'antd';

<Select
  showSearch
  style={{ width: 200 }}
  placeholder="搜索选择"
  optionFilterProp="label"
  options={options}
/>

自定义搜索 #

tsx

import { Select } from 'antd';

<Select
  showSearch
  style={{ width: 200 }}
  placeholder="搜索选择"
  filterOption={(input, option) =>
    (option?.label ?? '').toLowerCase().includes(input.toLowerCase())
  }
  options={options}
/>

远程搜索 #

tsx

import { Select } from 'antd';
import { useState } from 'react';

const [data, setData] = useState([]);
const [loading, setLoading] = useState(false);

const handleSearch = (value) => {
  if (value) {
    setLoading(true);
    fetch(`/api/search?q=${value}`)
      .then((response) => response.json())
      .then((data) => {
        setData(data);
        setLoading(false);
      });
  } else {
    setData([]);
  }
};

<Select
  showSearch
  loading={loading}
  filterOption={false}
  onSearch={handleSearch}
  options={data.map((item) => ({
    value: item.id,
    label: item.name,
  }))}
/>

分组 #

tsx

import { Select } from 'antd';

<Select
  style={{ width: 200 }}
  options={[
    {
      label: '管理员',
      options: [
        { value: 'admin1', label: '管理员1' },
        { value: 'admin2', label: '管理员2' },
      ],
    },
    {
      label: '用户',
      options: [
        { value: 'user1', label: '用户1' },
        { value: 'user2', label: '用户2' },
      ],
    },
  ]}
/>

自定义渲染 #

自定义选项 #

tsx

import { Select } from 'antd';

<Select
  style={{ width: 200 }}
  options={options}
  optionRender={(option) => (
    <span>
      {option.data.emoji} {option.data.label}
    </span>
  )}
/>

自定义选中项 #

tsx

import { Select } from 'antd';

<Select
  style={{ width: 200 }}
  labelRender={(option) => (
    <span>
      🎉 {option.label}
    </span>
  )}
  options={options}
/>

API #

Select #

属性	说明	类型	默认值
allowClear	允许清除	boolean	false
autoClearSearchValue	自动清除搜索值	boolean	true
autoFocus	自动聚焦	boolean	false
bordered	是否有边框	boolean	true
clearIcon	清除图标	ReactNode	-
defaultActiveFirstOption	默认高亮第一个选项	boolean	true
defaultOpen	默认展开	boolean	false
defaultValue	默认值	string \| string[]	-
disabled	禁用状态	boolean	false
dropdownMatchSelectWidth	下拉菜单宽度	boolean \| number	true
dropdownRender	自定义下拉菜单	(menu) => ReactNode	-
dropdownStyle	下拉菜单样式	CSSProperties	-
fieldNames	字段名映射	object	-
filterOption	筛选选项	boolean \| (input, option) => boolean	true
getPopupContainer	弹出容器	(triggerNode) => HTMLElement	-
labelInValue	返回值包含 label	boolean	false
listHeight	列表高度	number	256
loading	加载状态	boolean	false
maxTagCount	最多显示标签数	number \| `responsive`	-
maxTagPlaceholder	隐藏标签提示	ReactNode \| (omittedValues) => ReactNode	-
maxTagTextLength	标签文字最大长度	number	-
menuItemSelectedIcon	选中图标	ReactNode	-
mode	模式	`multiple` \| `tags`	-
notFoundContent	无数据内容	ReactNode	`Not Found`
open	是否展开	boolean	-
optionFilterProp	搜索字段	string	`value`
optionLabelProp	显示字段	string	`label`
options	选项数据	Option[]	-
placeholder	占位符	string	-
placement	弹出位置	`bottomLeft` \| `bottomRight` \| `topLeft` \| `topRight`	`bottomLeft`
popupClassName	弹出菜单类名	string	-
removeIcon	删除图标	ReactNode	-
searchValue	搜索值	string	-
showArrow	显示箭头	boolean	true
showSearch	显示搜索	boolean	false
size	大小	`large` \| `middle` \| `small`	-
status	状态	`error` \| `warning`	-
suffixIcon	后缀图标	ReactNode	-
tagRender	自定义标签渲染	(props) => ReactNode	-
tokenSeparators	分隔符	string[]	-
value	当前值	string \| string[]	-
virtual	虚拟滚动	boolean	true
onBlur	失焦回调	function	-
onChange	变化回调	function	-
onClear	清除回调	function	-
onDeselect	取消选中回调	function	-
onDropdownVisibleChange	展开回调	function	-
onFocus	聚焦回调	function	-
onInputKeyDown	键盘回调	function	-
onMouseEnter	鼠标进入回调	function	-
onMouseLeave	鼠标离开回调	function	-
onPopupScroll	滚动回调	function	-
onSearch	搜索回调	function	-
onSelect	选中回调	function	-

Option #

属性	说明	类型	默认值
className	类名	string	-
disabled	禁用	boolean	false
title	标题	string	-
value	值	string \| number	-

最佳实践 #

1. 表单中使用 #

tsx

import { Form, Select } from 'antd';

<Form.Item name="city" label="城市" rules={[{ required: true }]}>
  <Select placeholder="请选择城市" options={cityOptions} />
</Form.Item>

2. 联动选择 #

tsx

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

const [province, setProvince] = useState();
const [city, setCity] = useState();

const provinceOptions = [
  { value: 'zhejiang', label: '浙江' },
  { value: 'jiangsu', label: '江苏' },
];

const cityOptionsMap = {
  zhejiang: [
    { value: 'hangzhou', label: '杭州' },
    { value: 'ningbo', label: '宁波' },
  ],
  jiangsu: [
    { value: 'nanjing', label: '南京' },
    { value: 'suzhou', label: '苏州' },
  ],
};

<Space>
  <Select
    style={{ width: 120 }}
    options={provinceOptions}
    onChange={(value) => {
      setProvince(value);
      setCity(undefined);
    }}
  />
  <Select
    style={{ width: 120 }}
    value={city}
    options={cityOptionsMap[province] || []}
    onChange={setCity}
  />
</Space>

3. 大数据量 #

tsx

import { Select } from 'antd';

<Select
  style={{ width: 200 }}
  options={largeData}
  virtual
  showSearch
/>

下一步 #

接下来学习 Table 表格组件！