Select
选择器

下拉选择器。

使用import { Select } from "antd";

源码components/select

文档

编辑此页更新日志

何时使用

弹出一个下拉菜单给用户选择操作，用于代替原生的选择器，或者需要一个更优雅的多选器时。
当选项少时（少于 5 项），建议直接将选项平铺，使用 Radio 是更好的选择。
如果你在寻找一个可输可选的输入框，那你可能需要 AutoComplete。

用法升级 5.11.0+

升级提示

在 5.11.0 版本后，我们提供了 <Select options={[...]} /> 的简写方式，有更好的性能和更方便的数据组织方式，开发者不再需要自行拼接 JSX。同时我们废弃了原先的写法，你还是可以在 5.x 继续使用，但会在控制台看到警告，并会在 6.0 后移除。

jsx

// >=5.11.0 可用，推荐的写法 ✅
return <Select options={[{ value: 'sample', label: <span>sample</span> }]} />;

// 5.x 都可用，>=5.11.0 时不推荐 🙅🏻‍♀️
return (
  <Select onChange={onChange}>
    <Select.Option value="sample">Sample</Select.Option>
  </Select>
);

代码演示

Lucy

基本使用

基本使用。

LargeDefaultSmall

a10

c12

a10

c12

三种大小

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

Search to Select

带排序的搜索

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

lucy

分组

用 OptGroup 进行选项分组。

自动分词

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

User

Lucy

User

Lucy

前后缀

自定义前缀 prefix 和后缀图标 suffixIcon。

5.22.0

Inserted are removed

隐藏已选择选项

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

gold

cyan

自定义选择标签

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

Select Item...

响应式 maxTagCount

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

自定义状态

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

Ava Swift

最大选中数量

你可以通过设置 maxCount 约束最多可选中的数量，当超出限制时会变成禁止选中状态。

5.13.0

Select a person

带搜索框

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

a10

c12

a10

c12

多选

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

China

自定义下拉选项

使用 optionRender 自定义渲染下拉选项。

Tags Mode

标签

标签形式的多选框，用户亦可自由输入。

Zhejiang

Hangzhou

联动

省市联动是典型的例子，联动场景我们更推荐使用 Cascader 组件。

Lucy (101)

获得选项的文本

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

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

Select users

搜索用户

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

Outlined

Lucy

Filled

Lucy

Borderless

Lucy

Underlined

Lucy

形态变体

Select 形态变体，可选 outlined filled borderless underlined 四种形态。

5.13.0

No option match

自定义选中 label

允许自定义渲染当前选中的 label, 可用于 value 回填但对应选项缺失而不想直接渲染 value 的场景。

100000 Items

a10

c12

大数据

Select 默认针对大数据开启了虚拟滚动，因而获得了更好的性能，可以通过 virtual={false} 关闭。

topLefttopRightbottomLeftbottomRight

HangZhou #310000

弹出位置

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

API

通用属性参考：通用属性

Select props

参数	说明	类型	默认值	版本
allowClear	自定义清除按钮	boolean \| { clearIcon?: ReactNode }	false	5.8.0: 支持对象类型
autoClearSearchValue	是否在选中项后清空搜索框，只在 `mode` 为 `multiple` 或 `tags` 时有效	boolean	true
autoFocus	默认获取焦点	boolean	false
classNames	语义化结构 class	Record<SemanticDOM, string>	-	5.25.0
defaultActiveFirstOption	是否默认高亮第一个选项	boolean	true
defaultOpen	是否默认展开下拉菜单	boolean	-
defaultValue	指定默认选中的条目	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
disabled	是否禁用	boolean	false
~~popupClassName~~	下拉菜单的 className 属性，使用 `classNames.popup.root` 替换	string	-	4.23.0
popupMatchSelectWidth	下拉菜单和选择器同宽。默认将设置 `min-width`，当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动	boolean \| number	true	5.5.0
~~dropdownRender~~	自定义下拉框内容，使用 `popupRender` 替换	(originNode: ReactNode) => ReactNode	-
popupRender	自定义下拉框内容	(originNode: ReactNode) => ReactNode	-
~~dropdownStyle~~	下拉菜单的 style 属性，使用 `styles.popup.root` 替换	CSSProperties	-
fieldNames	自定义节点 label、value、options、groupLabel 的字段	object	{ label: `label`, value: `value`, options: `options`, groupLabel: `label` }	4.17.0（`groupLabel` 在 5.6.0 新增）
filterOption	是否根据输入项进行筛选。当其为一个函数时，会接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 true，反之则返回 false。示例	boolean \| function(inputValue, option)	true
filterSort	搜索时对筛选结果项的排序函数, 类似Array.sort里的 compareFunction	(optionA: Option, optionB: Option, info: { searchValue: string }) => number	-	`searchValue`: 5.19.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
maxCount	指定可选中的最多 items 数量，仅在 `mode` 为 `multiple` 或 `tags` 时生效	number	-	5.13.0
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 }[]	-
optionRender	自定义渲染下拉选项	(option: FlattenOptionData<BaseOptionType> , info: { index: number }) => React.ReactNode	-	5.11.0
placeholder	选择框默认文本	string	-
placement	选择框弹出的位置	`bottomLeft` `bottomRight` `topLeft` `topRight`	bottomLeft
prefix	自定义前缀	ReactNode	-	5.22.0
removeIcon	自定义的多选框清除图标	ReactNode	-
searchValue	控制搜索文本	string	-
showSearch	配置是否可搜索	boolean	单选为 false，多选为 true
size	选择框大小	`large` \| `middle` \| `small`	`middle`
status	设置校验状态	'error' \| 'warning'	-	4.19.0
suffixIcon	自定义的选择框后缀图标。以防止图标被用于其他交互，替换的图标默认不会响应展开、收缩事件，可以通过添加 `pointer-events: none` 样式透传。	ReactNode	`<DownOutlined />`
styles	语义化结构 style	Record<SemanticDOM, CSSProperties>	-	5.25.0
tagRender	自定义 tag 内容 render，仅在 `mode` 为 `multiple` 或 `tags` 时生效	(props) => ReactNode	-
labelRender	自定义当前选中的 label 内容 render （LabelInValueType的定义见 LabelInValueType）	(props: LabelInValueType) => ReactNode	-	5.15.0
tokenSeparators	自动分词的分隔符，仅在 `mode="tags"` 时生效	string[]	-
value	指定当前选中的条目，多选时为一个数组。（value 数组引用未变化时，Select 不会更新）	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
variant	形态变体	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.0
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~~	展开下拉菜单的回调，使用 `onOpenChange` 替换	(open: boolean) => void	-
onOpenChange	展开下拉菜单的回调	(open: boolean) => void	-
onFocus	获得焦点时回调	(event: FocusEvent) => void	-
onInputKeyDown	按键按下时回调	(event: KeyboardEvent) => void	-
onPopupScroll	下拉列表滚动时的回调	(event: UIEvent) => void	-
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	组名	React.ReactNode	-
className	Option 器类名	string	-
title	选项上的原生 title 提示	string	-

Semantic DOM

aojunhao123

root
5.25.0
根元素
popup.root
5.25.0
弹出菜单元素

主题变量（Design Token）

组件 Token如何定制？

Token 名称	描述	类型	默认值
activeBorderColor	激活态边框色	string	#1677ff
activeOutlineColor	激活态 outline 颜色	string	rgba(5,145,255,0.1)
clearBg	清空按钮背景色	string	#ffffff
hoverBorderColor	悬浮态边框色	string	#4096ff
multipleItemBg	多选标签背景色	string	rgba(0,0,0,0.06)
multipleItemBorderColor	多选标签边框色	string	transparent
multipleItemBorderColorDisabled	多选标签禁用边框色	string	transparent
multipleItemColorDisabled	多选标签禁用文本颜色	string	rgba(0,0,0,0.25)
multipleItemHeight	多选标签高度	number	24
multipleItemHeightLG	大号多选标签高度	number	32
multipleItemHeightSM	小号多选标签高度	number	16
multipleSelectorBgDisabled	多选框禁用背景	string	rgba(0,0,0,0.04)
optionActiveBg	选项激活态时背景色	string	rgba(0,0,0,0.04)
optionFontSize	选项字体大小	number	14
optionHeight	选项高度	number	32
optionLineHeight	选项行高	undefined \| LineHeight<string \| number>	1.5714285714285714
optionPadding	选项内间距	undefined \| Padding<string \| number>	5px 12px
optionSelectedBg	选项选中时背景色	string	#e6f4ff
optionSelectedColor	选项选中时文本颜色	string	rgba(0,0,0,0.88)
optionSelectedFontWeight	选项选中时文本字重	undefined \| FontWeight	600
selectorBg	选框背景色	string	#ffffff
showArrowPaddingInlineEnd	箭头的行末内边距	number	18
singleItemHeightLG	单选大号回填项高度	number	40
zIndexPopup	下拉菜单 z-index	number	1050

全局 Token如何定制？

FAQ

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

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

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

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

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

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

tsx

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

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

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

tsx

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

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

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

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

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

文档贡献者

Select选择器

Select选择器

何时使用

用法升级 5.11.0+

代码演示

100000 Items

API

Select props

Select Methods

Option props

OptGroup props

Semantic DOM

root

popup.root

主题变量（Design Token）

FAQ

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

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

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

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

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

何时使用

用法升级 5.11.0+

代码演示

100000 Items

API

Select props

Select Methods

Option props

OptGroup props

Semantic DOM

root

popup.root

主题变量（Design Token）

FAQ

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

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

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

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

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

Select
选择器

Select
选择器

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

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

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

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

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

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

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

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