CascaderSelect 级联选择

开发指南

何时使用

级联选择由选择器和级联组成。把级联组件以弹层的方式隐藏,多用于表单场景。

基本使用

展示基本的单选用法。

Expand trigger type:

展开触发行为

展示可通过 expandTriggerType 来设置不同的展开触发行为,支持 click 和 hover,默认值为 click。

多选

展示基本的多选用法。

设置是否只能选择叶子项

展示受控单选以及是否选择即改变。

设置父子节点选中是否关联

展示受控多选以及是否开启严格受控父子节点选中不再关联的用法。

自定义样式

可以通过 displayRender 来定制单选时展示的结果,可以通过 listStyle,listClassName 来定制组件宽高。

异步加载数据

展示动态获取数据的用法。

渲染 DataSource 中不存在的 value

CascaderSelect:

无障碍

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

API

CascaderSelect

参数说明类型默认值
size选择框大小

可选值:
'small', 'medium', 'large'
Enum'medium'
placeholder选择框占位符String-
disabled是否禁用Booleanfalse
hasArrow是否有下拉箭头Booleantrue
hasBorder是否有边框Booleantrue
hasClear是否有清除按钮Booleanfalse
label自定义内联 labelReactNode-
readOnly是否只读,只读模式下可以展开弹层但不能选Boolean-
dataSource数据源,结构可参考下方说明Array<Object>[]
defaultValue(非受控)默认值String/Array<String>null
value(受控)当前值String/Array<String>-
onChange选中值改变时触发的回调函数

签名:
Function(value: String/Array, data: Object/Array, extra: Object) => void
参数:
value: {String/Array} 选中的值,单选时返回单个值,多选时返回数组
data: {Object/Array} 选中的数据,包括 value 和 label,单选时返回单个值,多选时返回数组,父子节点选中关联时,同时选中,只返回父节点
extra: {Object} 额外参数
extra.selectedPath: {Array} 单选时选中的数据的路径
extra.checked: {Boolean} 多选时当前的操作是选中还是取消选中
extra.currentData: {Object} 多选时当前操作的数据
extra.checkedData: {Array} 多选时所有被选中的数据
extra.indeterminateData: {Array} 多选时半选的数据
Function-
defaultExpandedValue默认展开值,如果不设置,组件内部会根据 defaultValue/value 进行自动设置Array<String>-
expandTriggerType展开触发的方式

可选值:
'click', 'hover'
Enum'click'
useVirtual是否开启虚拟滚动Booleanfalse
multiple是否多选Booleanfalse
changeOnSelect是否选中即发生改变, 该属性仅在单选模式下有效Booleanfalse
canOnlyCheckLeaf是否只能勾选叶子项的checkbox,该属性仅在多选模式下有效Booleanfalse
checkStrictly父子节点是否选中不关联Booleanfalse
listStyle每列列表样式对象Object-
listClassName每列列表类名String-
displayRender选择框单选时展示结果的自定义渲染函数

签名:
Function(label: Array) => ReactNode
参数:
label: {Array} 选中路径的文本数组
返回值:
{ReactNode} 渲染在选择框中的内容
Function单选时:labelPath => labelPath.join(' / ');多选时:labelPath => labelPathlabelPath.length - 1
itemRender渲染 item 内容的方法

签名:
Function(item: Object) => ReactNode
参数:
item: {Object} 渲染节点的item
返回值:
{ReactNode} item node
Function-
showSearch是否显示搜索框Booleanfalse
filter自定义搜索函数

签名:
Function(searchValue: String, path: Array) => Boolean
参数:
searchValue: {String} 搜索的关键字
path: {Array} 节点路径
返回值:
{Boolean} 是否匹配
Function根据路径所有节点的文本值模糊匹配
resultRender搜索结果自定义渲染函数

签名:
Function(searchValue: String, path: Array) => ReactNode
参数:
searchValue: {String} 搜索的关键字
path: {Array} 匹配到的节点路径
返回值:
{ReactNode} 渲染的内容
Function按照节点文本 a / b / c 的模式渲染
resultAutoWidth搜索结果列表是否和选择框等宽Booleantrue
notFoundContent无数据时显示内容ReactNode'Not Found'
loadData异步加载数据函数

签名:
Function(data: Object) => void
参数:
data: {Object} 当前点击异步加载的数据
Function-
header自定义下拉框头部ReactNode-
footer自定义下拉框底部ReactNode-
defaultVisible初始下拉框是否显示Booleanfalse
visible当前下拉框是否显示Boolean-
onVisibleChange下拉框显示或关闭时触发事件的回调函数

签名:
Function(visible: Boolean, type: String) => void
参数:
visible: {Boolean} 是否显示
type: {String} 触发显示关闭的操作类型, fromTrigger 表示由trigger的点击触发; docClick 表示由document的点击触发
Function() => {}
popupStyle下拉框自定义样式对象Object-
popupClassName下拉框样式自定义类名String-
popupContainer下拉框挂载的容器节点String/Function-
popupProps透传到 Popup 的属性对象Object{}
followTrigger是否跟随滚动Boolean-

dataSource数据结构

const dataSource = [{
    value: '2974',
    label: '西安',
    children: [
        { value: '2975', label: '西安市', disabled: true },
        { value: '2976', label: '高陵县', checkboxDisabled: true },
        { value: '2977', label: '蓝田县' },
        { value: '2978', label: '户县' },
        { value: '2979', label: '周至县' },
        { value: '4208', label: '灞桥区' },
        { value: '4209', label: '长安区' },
        { value: '4210', label: '莲湖区' },
        { value: '4211', label: '临潼区' },
        { value: '4212', label: '未央区' },
        { value: '4213', label: '新城区' },
        { value: '4214', label: '阎良区' },
        { value: '4215', label: '雁塔区' },
        { value: '4388', label: '碑林区' },
        { value: '610127', label: '其它区' }
    ]
}];

数组中 Item 的自定义属性也会被透传到 onChange 函数的 data 参数中。

ARIA and KeyBoard

按键说明
Up Arrow获取同级当前项前一项焦点
Down Arrow获取同级当前项后一项焦点
Left Arrow进入当前项的子元素,并获取第一个子元素为焦点
Right Arrow返回当前项的父元素并获取焦点
Enter打开目录或选择当前项
Esc关闭目录
SPACE选择当前项