选择器 Select - Ant Design

何时使用

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

用法升级 5.11.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>
);

代码演示

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

主题变量（Design 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

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-` 属性？