Select
选择器

下拉选择器。
使用import{ Select }from"antd";

何时使用

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

5.11.0 用法升级

// >=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
Lucy
Lucy
Lucy

基本使用。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

使用 filterOption 自定义搜索。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code


a1

三种大小的选择框,当 size 分别为 largesmall 时,输入框高度为 40px24px ,默认高度为 32px

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
lucy

OptGroup 进行选项分组。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
User
Lucy
Lucy
Lucy

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.22.0

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Zhejiang
Hangzhou

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Lucy (101)

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

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
custom dropdown render

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Outlined
Filled
Borderless

可选 outlined filled borderless 三种形态。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
No option match

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

100000 Items

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code


HangZhou #310000

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

API

通用属性参考:通用属性

Select props

参数说明类型默认值版本
allowClear自定义清除按钮boolean | { clearIcon?: ReactNode }false5.8.0: 支持对象类型
autoClearSearchValue是否在选中项后清空搜索框,只在 modemultipletags 时有效booleantrue
autoFocus默认获取焦点booleanfalse
defaultActiveFirstOption是否默认高亮第一个选项booleantrue
defaultOpen是否默认展开下拉菜单boolean-
defaultValue指定默认选中的条目string | string[] |
number | number[] |
LabeledValue | LabeledValue[]
-
disabled是否禁用booleanfalse
popupClassName下拉菜单的 className 属性string-4.23.0
popupMatchSelectWidth下拉菜单和选择器同宽。默认将设置 min-width,当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动boolean | numbertrue5.5.0
dropdownRender自定义下拉框内容(originNode: ReactNode) => ReactNode-
dropdownStyle下拉菜单的 style 属性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 } 的格式booleanfalse
listHeight设置弹窗滚动高度number256
loading加载中状态booleanfalse
maxCount指定可选中的最多 items 数量,仅在 modemultipletags 时生效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当下拉列表为空时显示的内容ReactNodeNot Found
open是否展开下拉菜单boolean-
optionFilterProp搜索时过滤对应的 option 属性,如设置为 children 表示对内嵌内容进行搜索。若通过 options 属性配置选项内容,建议设置 optionFilterProp="label" 来对内容进行搜索。stringvalue
optionLabelProp回填到选择框的 Option 的属性值,默认是 Option 的子元素。比如在子元素需要高亮效果时,此值可以设为 value示例stringchildren
options数据化配置选项内容,相比 jsx 定义会获得更好的渲染性能{ label, value }[]-
optionRender自定义渲染下拉选项(option: FlattenOptionData<BaseOptionType> , info: { index: number }) => React.ReactNode-5.11.0
placeholder选择框默认文本string-
placement选择框弹出的位置bottomLeft bottomRight topLeft topRightbottomLeft
prefix自定义前缀ReactNode-5.22.0
removeIcon自定义的多选框清除图标ReactNode-
searchValue控制搜索文本string-
showSearch配置是否可搜索boolean单选为 false,多选为 true
size选择框大小large | middle | smallmiddle
status设置校验状态'error' | 'warning'-4.19.0
suffixIcon自定义的选择框后缀图标。以防止图标被用于其他交互,替换的图标默认不会响应展开、收缩事件,可以通过添加 pointer-events: none 样式透传。ReactNode<DownOutlined />
tagRender自定义 tag 内容 render,仅在 modemultipletags 时生效(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 | filledoutlined5.13.0
virtual设置 false 时关闭虚拟滚动booleantrue4.1.0
onBlur失去焦点时回调function-
onChange选中 option,或 input 的 value 变化时,调用此函数function(value, option:Option | Array<Option>)-
onClear清除内容时回调function-4.6.0
onDeselect取消选中时调用,参数为选中项的 value (或 key) 值,仅在 multipletags 模式下生效function(value: string | number | LabeledValue)-
onDropdownVisibleChange展开下拉菜单的回调(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

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

OptGroup props

参数说明类型默认值版本
keyKeystring-
label组名React.ReactNode-
classNameOption 器类名string-
title选项上的原生 title 提示string-

主题变量(Design Token)

组件 Token如何定制?

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

全局 Token如何定制?

FAQ

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

这一般是 options 中的 labelvalue 不同导致的,你可以通过 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} />

注意:listItemHeightlistHeight 为内部属性,如无必要,请勿修改该值。

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

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

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