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 类型数值

  1. children的方式

<Select>
  <Select.Option value="option1">option1</Select.Option>
  <Select.Option value="option2">option2</Select.Option>
  <Select.Option disabled>disabled</Select.Option>
</Select>;
  1. props的方式

const dataSource = [
  {label:'option1', value:'option1'},
  {label:'option2', value:'option2'},
  {label:'disabled', disabled:true},
];

<Select dataSource={dataSource} />

定制弹出层

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

基本使用

简单

自定义trigger

Select通过trigger自定义触发器

标签

标签模式,输入的内容可以作为选项

多选

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

hasSelectAll:


maxTagCount=2


maxTagPlaceholder


tagInline


maxTagPlaceholder


最大数量

多选模式

选择器

演示了 Select 的多种形态.

级联选择

使用 Select 构建级联选择框

分组

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

自定义 value

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

前后缀

Select 增加前后缀

对象数据

useDetailValuevalue 从字符串变成对象

自动完成

AutoComplete 继承了 Input 的能力,并在其基础上增加了 autoComplete 的功能。 对于设置为AutoComplete为 off 不生效对的情况,可以参考 MDN 中进行设置。

自动完成

AutoComplete 大小、disabled、清除

动态数据

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

图文展示

展示较为复杂的内容展示

自定义渲染

通过 itemRendervalueRender (仅 Select) 自定义渲染的节点内容。

弹层定制

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

    

无限滚动

select 配合无限滚动

Select:

无障碍

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

API

Select

参数说明类型默认值
trigger自定义弹层触发器-ReactElement
size选择器尺寸

可选值:
'xs',
'small', 'medium'
Enum'medium'
value当前值,用于受控模式any-
defaultValue初始的默认值any-
placeholder没有值的时候的占位符String-
autoWidth下拉菜单是否与选择器对齐Booleantrue
label自定义内联 labelReactNode-
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的点击触发
Functionfunc.noop
popupContainer弹层挂载的容器节点String/Function-
popupClassName弹层的 classNameany-
popupStyle弹层的内联样式Object-
popupProps添加到弹层上的属性Object{}
followTrigger是否跟随滚动Boolean-
popupContent自定义弹层的内容ReactNode-
filterLocal是否使用本地过滤,在数据源为远程的时候需要关闭此项Booleantrue
filter本地过滤方法,返回一个 Boolean 值确定是否保留

签名:
Function() => void
Functionfilter
onToggleHighlightItem键盘上下键切换菜单高亮选项的回调

签名:
Function() => void
Functionfunc.noop
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-
footer弹层底部内容,useVirtual为true时无效ReactNode-
onChangeSelect发生改变时触发的回调

签名:
Function(value: mixed, actionType: String, item: mixed) => void
参数:
value: {mixed} 选中的值
actionType: {String} 触发的方式, 'itemClick', 'enter', 'tag'
item: {mixed} 选中的值的对象数据 (useDetailValue=false有效)
Function-
hasBorder是否有边框Boolean-
hasArrow是否有下拉箭头Booleantrue
showSearch展开后是否能搜索(tag 模式下固定为true)Booleanfalse
onSearch当搜索框值变化时回调

签名:
Function(value: String) => void
参数:
value: {String} 数据
Functionfunc.noop
onSearchClear当搜索框值被清空时候的回调

签名:
Function(actionType: String) => void
参数:
actionType: {String} 触发的方式, 'select'(选择清空), 'popupClose'(弹窗关闭清空)
Functionfunc.noop
hasSelectAll多选模式下是否有全选功能Boolean/String-
fillProps填充到选择框里的值的 keyString-
useDetailValueonChange 返回的 value 使用 dataSource 的对象Boolean-
cacheValuedataSource 变化的时是否保留已选的内容Booleantrue
valueRender渲染 Select 展现内容的方法

签名:
Function(item: Object) => ReactNode
参数:
item: {Object} 渲染节点的item
返回值:
{ReactNode} 展现内容
Functionitem => item.label || item.value
searchValue受控搜索值,一般不需要设置String-
tagInline是否一行显示,仅在 mode 为 multiple 的时候生效Booleanfalse
maxTagCount最多显示多少个 tagNumber-
maxTagPlaceholder隐藏多余 tag 时显示的内容,在 maxTagCount 生效时起作用

签名:
Function(selectedValues: number, totalValues: number) => void
参数:
selectedValues: {number} 当前已选中的元素
totalValues: {number} 总待选元素
Function-
hiddenSelected选择后是否立即隐藏菜单 (mode=multiple/tag 模式生效)Boolean-
onRemovetag 删除回调

签名:
Function(item: object) => void
参数:
item: {object} 渲染节点的item
Functionfunc.noop
onFocus焦点事件

签名:
Function() => void
Functionfunc.noop
onBlur失去焦点事件

签名:
Function() => void
Functionfunc.noop

Select.AutoComplete

参数说明类型默认值
size选择器尺寸

可选值:
'xs',
'small', 'medium'
Enum'medium'
value当前值,用于受控模式String/Number-
defaultValue初始化的默认值String/Number-
placeholder没有值的时候的占位符String-
autoWidth下拉菜单是否与选择器对齐Booleantrue
label自定义内联 labelReactNode-
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的点击触发
Functionfunc.noop
popupContainer弹层挂载的容器节点String/Function-
popupClassName弹层的 classNameany-
popupStyle弹层的内联样式Object-
popupProps添加到弹层上的属性Object{}
followTrigger是否跟随滚动Boolean-
popupContent自定义弹层的内容ReactNode-
filterLocal是否使用本地过滤,在数据源为远程的时候需要关闭此项Booleantrue
filter本地过滤方法,返回一个 Boolean 值确定是否保留

签名:
Function() => void
Functionfilter
onToggleHighlightItem键盘上下键切换菜单高亮选项的回调

签名:
Function() => void
Functionfunc.noop
useVirtual是否开启虚拟滚动模式Boolean-
dataSource传入的数据源,可以动态渲染子项Array<Object/String>-
itemRender渲染 MenuItem 内容的方法

签名:
Function(item: Object) => ReactNode
参数:
item: {Object} 渲染节点的 item
返回值:
{ReactNode} item node
Function-
footer弹层底部内容,useVirtual为true时无效ReactNode-
onChangeSelect发生改变时触发的回调

签名:
Function(value: mixed, actionType: String, item: mixed) => void
参数:
value: {mixed} 选中的值
actionType: {String} 触发的方式, 'itemClick', 'enter', 'change'
item: {mixed} 选中的值的对象数据
Function-
fillProps填充到选择框里的值的 key,默认是 valueString'value'

Select.OptionGroup

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

Select.Option

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

ARIA and KeyBoard

按键说明
Up Arrow获取当前项前一项焦点
Down Arrow获取当前项后一项焦点
Enter打开列表或选择当前项
Esc关闭列表