Clarity Design · 协作产品 UI 设计语言

开发指南

何时使用

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

API

CascaderSelect

参数	说明	类型	默认值
size	选择框大小可选值: 'small', 'medium', 'large'	Enum	'medium'
placeholder	选择框占位符	String	-
disabled	是否禁用	Boolean	false
hasArrow	是否有下拉箭头	Boolean	true
hasBorder	是否有边框	Boolean	true
hasClear	是否有清除按钮	Boolean	false
label	自定义内联 label	ReactNode	-
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	是否开启虚拟滚动	Boolean	false
multiple	是否多选	Boolean	false
changeOnSelect	是否选中即发生改变, 该属性仅在单选模式下有效	Boolean	false
canOnlyCheckLeaf	是否只能勾选叶子项的checkbox，该属性仅在多选模式下有效	Boolean	false
checkStrictly	父子节点是否选中不关联	Boolean	false
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	是否显示搜索框	Boolean	false
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	搜索结果列表是否和选择框等宽	Boolean	true
notFoundContent	无数据时显示内容	ReactNode	'Not Found'
loadData	异步加载数据函数签名: Function(data: Object) => void 参数: data: {Object} 当前点击异步加载的数据	Function	-
header	自定义下拉框头部	ReactNode	-
footer	自定义下拉框底部	ReactNode	-
defaultVisible	初始下拉框是否显示	Boolean	false
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	选择当前项

CascaderSelect 级联选择

开发指南

何时使用

基本使用

展开触发行为

多选

设置是否只能选择叶子项

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

搜索

自定义样式

异步加载数据

渲染 DataSource 中不存在的 value

无障碍

API

CascaderSelect

dataSource数据结构

ARIA and KeyBoard