Console Components

指南组件文档国内文档镜像 Github

文档Tags：

select

Select 选择器

Guide

何时使用

Select

如果你不期望用户输入的值生效而仅仅是选择，那么使用 Select. 同时可以使用 Select 的 showSearch 属性进行过滤。

AutoComplete

AutoComplete 会保留用户输入的值，本质上是 Input 组件，扩展了 autocomplete 的能力，所以 Input 组件的属性可以直接透传。

常见问题

出现类似的 flatternChildren 的 warning

Select 默认使用 value 作为菜单项的 key，如果没有设置 key 值，则使用默认的序列 index 作为 key 值，确保这些值不会发生重复。

dataSource 的使用

Select 同时支持 children 和在 props 中传入 dataSource 作为数据源, 如果同时设置, 则以 children 为准.

注意：1. Select 默认使用 value 作为渲染的菜单项的 key 值，所以 value 不能重复, 否则无法渲染下拉菜单。2. value 不允许出现 null/undefined/object/array 类型数值

定制弹出层

参见示例中的弹层定制。唯一需要注意的是 overlay 的元素记得透传 props. 这是因为 Overlay 的弹层的动画是依靠 className 实现的，如果不透传 props 则会造成无法监听到动画播放结束的事件。

基本使用

简单

Jack

APIs

Select

参数	说明	类型	默认值
size	选择器尺寸可选值: 'small', 'medium', 'large'	Enum	'medium'
value	当前值，用于受控模式	any	-
defaultValue	初始的默认值	any	-
placeholder	没有值的时候的占位符	String	-
autoWidth	下拉菜单是否与选择器对齐	Boolean	true
label	自定义内联 label	ReactNode	-
hasClear	是否有清除按钮（单选模式有效）	Boolean	-
state	校验状态可选值: 'error', 'loading'	Enum	-
readOnly	是否只读，只读模式下可以展开弹层但不能选	Boolean	-
disabled	是否禁用选择器	Boolean	-
visible	当前弹层是否显示	Boolean	-
defaultVisible	弹层初始化是否显示	Boolean	-
onVisibleChange	弹层显示或隐藏时触发的回调签名: Function(visible: Boolean, type: String) => void 参数: visible: {Boolean} 弹层是否显示 type: {String} 触发弹层显示或隐藏的来源 fromContent 表示由Dropdown内容触发； fromTrigger 表示由trigger的点击触发； docClick 表示由document的点击触发	Function	func.noop
popupContainer	弹层挂载的容器节点	any	-
popupClassName	弹层的 className	any	-
popupStyle	弹层的内联样式	Object	-
popupProps	添加到弹层上的属性	Object	{}
followTrigger	是否跟随滚动	Boolean	-
popupContent	自定义弹层的内容	ReactNode	-
menuProps	添加到菜单上的属性	Object	-
filterLocal	是否使用本地过滤，在数据源为远程的时候需要关闭此项	Boolean	true
filter	本地过滤方法，返回一个 Boolean 值确定是否保留签名: Function(key: String, item: Object) => Boolean 参数: key: {String} 搜索关键字 item: {Object} 渲染节点的item 返回值: {Boolean} 是否匹配	Function	filter
defaultHighlightKey	默认高亮的 key，不要和 autoHighlightFirstItem 同时使用	String	null
highlightKey	高亮 key，不要和 autoHighlightFirstItem 同时使用，用于受控模式	String	-
onToggleHighlightItem	键盘上下键切换菜单高亮选项的回调签名: Function() => void	Function	func.noop
autoHighlightFirstItem	自动高亮第一个元素	Boolean	true
useVirtual	是否开启虚拟滚动模式	Boolean	-
dataSource	传入的数据源，可以动态渲染子项，详见 dataSource的使用	Array<Object/Boolean/Number/String>	-
itemRender	渲染 MenuItem 内容的方法签名: Function(item: Object, searchValue: String) => ReactNode 参数: item: {Object} 渲染节点的item searchValue: {String} 搜索关键字（如果开启搜索）返回值: {ReactNode} item node	Function	-
mode	选择器模式可选值: 'single', 'multiple', 'tag'	Enum	'single'
notFoundContent	弹层内容为空的文案	ReactNode	-
isPreview	是否为预览态	Boolean	-
renderPreview	预览态模式下渲染的内容签名: Function(value: number) => void 参数: value: {number} 评分值	Function	-
showDataSourceChildren	是否展示 dataSource 中 children	Boolean	-
onChange	Select发生改变时触发的回调签名: Function(value: mixed, actionType: String, item: mixed) => void 参数: value: {mixed} 选中的值 actionType: {String} 触发的方式, 'itemClick', 'enter', 'tag' item: {mixed} 选中的值的对象数据 (useDetailValue=false有效)	Function	-
hasBorder	是否有边框	Boolean	-
hasArrow	是否有下拉箭头	Boolean	true
showSearch	展开后是否能搜索（tag 模式下固定为true）	Boolean	false
onSearch	当搜索框值变化时回调签名: Function(value: String) => void 参数: value: {String} 数据	Function	func.noop
onSearchClear	当搜索框值被(选择、弹窗关闭)导致清空时候的回调签名: Function(actionType: String) => void 参数: actionType: {String} 触发的方式, 'select'(选择清空), 'popupClose'(弹窗关闭清空)	Function	func.noop
hasSelectAll	多选模式下是否有全选功能	Boolean/String	-
fillProps	填充到选择框里的值的 key	String	-
useDetailValue	value 使用对象类型 `{value, label}`, 同时 onChange 第一个参数返回也修改为 dataSource 中的对象	Boolean	-
cacheValue	dataSource 变化的时是否保留已选的内容	Boolean	true
valueRender	渲染 Select 展现内容的方法签名: Function(item: Object) => ReactNode 参数: item: {Object} 渲染节点的item 返回值: {ReactNode} 展现内容	Function	item => `item.label	item.value`
searchValue	受控搜索值，一般不需要设置	String	-
tagInline	是否一行显示，仅在 mode 为 multiple 的时候生效	Boolean	false
tagClosable	tag 是否可关闭	Boolean	true
maxTagCount	最多显示多少个 tag	Number	-
maxTagPlaceholder	隐藏多余 tag 时显示的内容，在 maxTagCount 生效时起作用签名: Function(selectedValues: object, totalValues: object) => void 参数: selectedValues: {object} 当前已选中的元素 totalValues: {object} 总待选元素	Function	-
hiddenSelected	选择后是否立即隐藏菜单 (mode=multiple/tag 模式生效)	Boolean	-
onRemove	tag 删除回调签名: Function(item: object) => void 参数: item: {object} 渲染节点的item	Function	func.noop
onFocus	焦点事件签名: Function() => void	Function	func.noop
onBlur	失去焦点事件签名: Function() => void	Function	func.noop
popupAutoFocus	展开下拉菜单时是否自动焦点到弹层	Boolean	false

Select.AutoComplete

参数	说明	类型	默认值
size	选择器尺寸可选值: 'small', 'medium', 'large'	Enum	'medium'
value	当前值，用于受控模式	String/Number	-
defaultValue	初始化的默认值	String/Number	-
placeholder	没有值的时候的占位符	String	-
autoWidth	下拉菜单是否与选择器对齐	Boolean	true
label	自定义内联 label	ReactNode	-
hasClear	是否有清除按钮（单选模式有效）	Boolean	-
state	校验状态可选值: 'error', 'loading'	Enum	-
readOnly	是否只读，只读模式下可以展开弹层但不能选	Boolean	-
disabled	是否禁用选择器	Boolean	-
visible	当前弹层是否显示	Boolean	-
defaultVisible	弹层初始化是否显示	Boolean	-
onVisibleChange	弹层显示或隐藏时触发的回调签名: Function(visible: Boolean, type: String) => void 参数: visible: {Boolean} 弹层是否显示 type: {String} 触发弹层显示或隐藏的来源 fromContent 表示由Dropdown内容触发； fromTrigger 表示由trigger的点击触发； docClick 表示由document的点击触发	Function	func.noop
popupContainer	弹层挂载的容器节点	any	-
popupClassName	弹层的 className	any	-
popupStyle	弹层的内联样式	Object	-
popupProps	添加到弹层上的属性	Object	{}
followTrigger	是否跟随滚动	Boolean	-
popupContent	自定义弹层的内容	ReactNode	-
menuProps	添加到菜单上的属性	Object	-
filterLocal	是否使用本地过滤，在数据源为远程的时候需要关闭此项	Boolean	true
filter	本地过滤方法，返回一个 Boolean 值确定是否保留签名: Function(key: String, item: Object) => Boolean 参数: key: {String} 搜索关键字 item: {Object} 渲染节点的item 返回值: {Boolean} 是否匹配	Function	filter
defaultHighlightKey	默认高亮的 key，不要和 autoHighlightFirstItem 同时使用	String	null
highlightKey	高亮 key，不要和 autoHighlightFirstItem 同时使用，用于受控模式	String	-
onToggleHighlightItem	键盘上下键切换菜单高亮选项的回调签名: Function() => void	Function	func.noop
autoHighlightFirstItem	自动高亮第一个元素	Boolean	true
useVirtual	是否开启虚拟滚动模式	Boolean	-
dataSource	传入的数据源，可以动态渲染子项	Array<Object/String>	-
itemRender	渲染 MenuItem 内容的方法签名: Function(item: Object) => ReactNode 参数: item: {Object} 渲染节点的 item 返回值: {ReactNode} item node	Function	-
isPreview	是否为预览态	Boolean	-
renderPreview	预览态模式下渲染的内容签名: Function(value: number) => void 参数: value: {number} 评分值	Function	-
onChange	Select发生改变时触发的回调签名: Function(value: mixed, actionType: String, item: mixed) => void 参数: value: {mixed} 选中的值 actionType: {String} 触发的方式, 'itemClick', 'enter', 'change' item: {mixed} 选中的值的对象数据	Function	-
fillProps	填充到选择框里的值的 key，默认是 value	String	'value'

Select.OptionGroup

参数	说明	类型	默认值
label	设置分组的文案	ReactNode	-

Select.Option

参数	说明	类型	默认值
value	选项值	any	-
disabled	是否禁用	Boolean	-

Demo

多选

多选模式, 通过 `showSearch` 可以开启搜索, 但搜索值不可用作选项

最大数量

多选模式

hasSelectAll:

maxTagCount=2:

Lucy King

Lily King

已选择 3/5 项

maxTagPlaceholder:

Lucy King

Lily King

3/5

tagInline:

已选择 3/5 项

Lucy King

Lily King

FALSE

maxTagPlaceholder:

3/5

Lucy King

Lily King

FALSE

选择器

演示了 Select 的多种形态

mode: size: showSearch: hasArrow: hasBorder:

级联选择

使用 Select 构建级联选择框

分组

使用 OptionGroup 针对选项进行分组，也可以使用原生的 html 标签 optgroup

自定义 value

Select 的 value 可以是任意非空类型的值，但是要保证 toString() 后是唯一的。

搜索框

使用 `showSearch` 显示搜索框，如果需要动态更新 dataSource，需要关闭 filterLocal

前后缀

Select 增加前后缀

size:GB

对象数据

`useDetailValue` 把 `value` 从字符串变成对象

Lucy King

自动完成

`AutoComplete` 继承了 `Input` 的能力，并在其基础上增加了 autoComplete 的功能。对于设置为`AutoComplete`为off不生效对的情况，可以参考 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/Security/Securing_your_site/Turning_off_form_autocompletion]) 中进行设置。

自动完成大小

`AutoComplete` 大小、disabled、清除

size: disabled: hasClear:

动态数据

使用动态数据填充 AutoComplete, 设置 `filterLocal` 为 false

图文展示

展示较为复杂的内容展示

自定义渲染

通过 `itemRender` 和 `valueRender` (仅 Select) 自定义渲染的节点内容。

弹层定制

通过 popupContent 定制 Select 弹层， Select 使用 popupContent 中渲染出的 item 的 value 作为菜单项的key，如果没有提供或者自定义渲染 key 请使用 valueRender

虚拟滚动

select 配合虚拟滚动

option0 option50

无障碍

当聚焦在组件上时，通过`aria-labelledby`对组件进行描述。关于键盘操作请参考`ARIA and KeyBoard`。

Jack

Select 选择器
Guide
Select
AutoComplete
dataSource 的使用
基本使用
APIs
Select
Select.AutoComplete
Select.OptionGroup
Select.Option
Demo