代码演示
如何引入
基本用法
最简单的用法,默认只可以选叶子节点。
多选
version: >= 1.28.0
设置
multiple
,可以进行多选。可搜索的
通过设置
默认搜索结果只会展示叶子结点的路径,想要显示更多的结果,可以设置
filterTreeNode
属性可支持搜索功能。默认对 label
值进行搜索,可通过 treeNodeFilterProp
更改。默认搜索结果只会展示叶子结点的路径,想要显示更多的结果,可以设置
filterLeafOnly
为 false
。可搜索的多选
version: >= 1.28.0
支持多选和搜索同时使用时,在这种场景下,可以通过按下 BackSpace 键来删除对应的已选项目。
限制标签展示数量
version: >= 1.28.0
在多选的场景中,利用 maxTagCount 可以限制展示的标签数量,超出部分将以 +N 的方式展示。
使用 showRestTagsPopover 可以设置在超出 maxTagCount 后,hover +N 是否显示 Popover,默认为 false。并且,还可以在 restTagsPopoverProps 属性中配置 Popover。
限制选中数量
version: >= 1.28.0
在多选的场景中,利用 max 可以限制多选选中的数量。超出 max 后将触发 onExceed 回调。
选择即改变
在单选的情况下,还可以通过设置
changeOnSelect
,允许选中父级选项。自定义显示
可以通过
displayProp
设置回填选项显示的属性值,默认为 label
。可以通过设置
displayRender
可以设定返回格式。单选 (
multiple=false
) 时, displayRender((labelPath: string[]) => ReactNode)
, 其中 labelPath 是由 label 构成的 path 数组。多选 (
multiple=true
) 时, displayRender((item: Entity, index: number) => ReactNode)
, 其中 item 为节点的相关数据。自定义分隔符
版本: >=2.2.0
可以使用
separator
设置分隔符, 包括:搜索时显示在下拉框的内容以及单选时回显到 Trigger 的内容的分隔符。禁用
严格禁用
version: >= 1.32.0
可以使用 disableStrictly 来开启严格禁用。开启严格禁用后,当节点是 disabled 的时候,则不能通过子级或者父级的关系改变选中状态。
以下面的 demo 为例,节点"宁波"开启了严格禁用,因此,当我们改变其父节点"浙江省"的选中状态时,也不会影响到节点"宁波"的选中状态。
展示子菜单的时机
version: >= 1.29.0
可以使用
showNext
设置展开 Dropdown 子菜单的触发时机,可选: click
(默认)、hover
。在顶部/底部渲染附加项
我们在级联选择器的顶部、底部分别预留了插槽,你可以通过
topSlot
或 bottomSlot
来设置。受控
传入
value
时即为受控组件,可以配合 onChange
使用。自动合并 value
版本: >=1.28.0
在多选(multiple=true)场景中,当我们选中祖先节点时,如果希望 value 不包含它对应的子孙节点,则可以通过
autoMergeValue
来设置,默认为 true。当 autoMergeValue 和 leafOnly 同时开启时,后者优先级更高。仅叶子节点
版本: >=2.2.0
在多选时,可以通过开启 leafOnly 来设置 value 只包含叶子节点,即显示的 Tag 和 onChange 的参数 value 只包含 value。
动态更新数据
异步加载数据
可以使用 loadData 实现异步加载数据
v>=1.8.0
不能与搜索同时使用
不能与搜索同时使用
超长列表
当你的数据结构层级特别深时,Cascader下拉菜单可能会超出屏幕,此时我们建议为下拉菜单设置 overflow-x: auto 以及一个合适的 width 宽度( 建议以N+0.5列的宽度为准,最右侧显示半列,以给用户一种右侧尚有待展开项,可以水平方向滚动的视觉暗示)
自定义 Trigger
如果默认的触发器样式满足不了你的需求,可以用
triggerRender
自定义选择框的展示triggerRender 入参如下
API 参考
Cascader
属性 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
arrowIcon | 自定义右侧下拉箭头 Icon,当 showClear 开关打开且当前有选中值时,hover 会优先显示 clear icon | ReactNode | 1.15.0 | |
autoAdjustOverflow | 是否自动调整下拉框展开方向,用于边缘遮挡时自动调整展开方向 | boolean | true | - |
autoMergeValue | 设置自动合并 value。具体而言是,开启后,当某个父节点被选中时,value 将不包括该节点的子孙节点。不支持动态切换 | boolean | true | 1.28.0 |
bottomSlot | 底部插槽 | ReactNode | - | 1.27.0 |
changeOnSelect | 是否允许选择非叶子节点 | boolean | false | - |
className | 选择框的 className 属性 | string | - | - |
defaultOpen | 设置是否默认打开下拉菜单 | boolean | false | - |
defaultValue | 指定默认选中的条目 | string|number| TreeNode\ | (string|number|TreeNode)[] | - |
disabled | 是否禁用 | boolean | false | - |
displayProp | 设置回填选项显示的属性值 | string | label | - |
displayRender | 设置回填格式 | (selected: string[] | Entity, idx?: number) => ReactNode | selected => selected.join(' / ') | - |
dropdownClassName | 下拉菜单的 className 属性 | string | - | - |
dropdownStyle | 下拉菜单的样式 | object | - | - |
emptyContent | 当搜索无结果时展示的内容 | ReactNode | 暂无数据 | - |
filterLeafOnly | 搜索结果是否只展示叶子结点路径 | boolean | true | 1.26.0 |
filterTreeNode | 设置筛选,默认用 treeNodeFilterProp 的值作为要筛选的 TreeNode 的属性值 | ((inputValue: string, treeNodeString: string) => boolean) | boolean | false | - |
getPopupContainer | 指定父级 DOM,下拉框将会渲染至该 DOM 中,自定义需要设置 position: relative | () => HTMLElement | () => document.body | - |
insetLabel | 前缀标签别名,主要用于 Form | ReactNode | - | 0.28.0 |
leafOnly | 多选时设置 value 只包含叶子节点,即显示的 Tag 和 onChange 的 value 参数只包含叶子节点。不支持动态切换 | boolean | false | 2.2.0 |
loadData | 异步加载数据,需要返回一个Promise | (selectOptions: TreeNode[]) => Promise< void > | - | 1.8.0 |
max | 多选时,限制多选选中的数量,超出 max 后将触发 onExceed 回调 | number | - | 1.28.0 |
maxTagCount | 多选时,标签的最大展示数量,超出后将以 +N 形式展示 | number | - | 1.28.0 |
motion | 设置下拉框弹出的动画 | boolean|object | true | - |
mouseEnterDelay | 鼠标移入后,延迟显示下拉框的时间,单位毫秒 | number | 50 | - |
mouseLeaveDelay | 鼠标移出后,延迟消失下拉框的时间,单位毫秒 | number | 50 | - |
multiple | 设置多选 | boolean | false | 1.28.0 |
placeholder | 选择框默认文字 | string | - | - |
position | 方向,可选值:top ,topLeft ,topRight ,left ,leftTop ,leftBottom ,right ,rightTop ,rightBottom ,bottom ,bottomLeft ,bottomRight | string | "bottom" | 2.16.0-beta.0 |
prefix | 前缀标签 | ReactNode | - | 0.28.0 |
preventScroll | 指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法 | boolean | ||
restTagsPopoverProps | Popover 的配置属性,可以控制 position、zIndex、trigger 等,具体参考Popover | PopoverProps | {} | 1.28.0 |
searchPlaceholder | 搜索框默认文字 | string | - | - |
separator | 自定义分隔符,包括:搜索时显示在下拉框的内容以及单选时回显到 Trigger 的内容的分隔符 | string | ' / ' | 2.2.0 |
showClear | 是否展示清除按钮 | boolean | false | 0.35.0 |
showNext | 设置展开 Dropdown 子菜单的方式,可选: click 、hover | string | click | 1.29.0 |
showRestTagsPopover | 当超过 maxTagCount,hover 到 +N 时,是否通过 Popover 显示剩余内容 | boolean | false | 1.28.0 |
size | 选择框大小,可选 large ,small ,default | string | default | - |
stopPropagation | 是否阻止下拉框上的点击事件冒泡 | boolean | true | - |
disableStrictly | 设置是否开启严格禁用。开启后,当节点是 disabled 的时候,则不能通过子级或者父级的关系改变选中状态 | boolean | false | 1.32.0 |
style | 选择框的样式 | CSSProperties | - | - |
suffix | 后缀标签 | ReactNode | - | 0.28.0 |
topSlot | 顶部插槽 | ReactNode | - | 1.27.0 |
treeData | 展示数据,具体属性参考 TreeNode | TreeNode[] | [] | - |
treeNodeFilterProp | 搜索时输入项过滤对应的 treeNode 属性 | string | label | - |
triggerRender | 自定义触发器渲染方法 | (triggerRenderData: object) => ReactNode | - | 0.34.0 |
validateStatus | trigger 的校验状态,仅影响展示样式。可选: default、error、warning | string | default | - |
value | (受控)选中的条目 | string|number| TreeNode\ | (string|number|TreeNode)[] | - |
zIndex | 下拉菜单的 zIndex | number | 1030 | - |
enableLeafClick | 多选时,是否启动点击叶子节点选项触发勾选 | boolean | false | 2.2.0 |
onBlur | 失焦 Cascader 的回调 | (e: MouseEvent) => void | - | - |
onChange | 选中树节点时调用此函数,默认返回选中项 path 的 value 数组 | (value: string|number| TreeNode\ | (string|number|TreeNode)[]) => void | - |
onChangeWithObject | 是否将选中项 option 的其他属性作为回调。设为 true 时,onChange 的入参类型会从 string/number 变为 TreeNode。此时如果是受控,也需要把 value 设置成 TreeNode 类型,且必须含有 value 的键值,defaultValue 同理 | boolean | false | 1.16.0 |
onClear | showClear 为 true 时,点击清空按钮触发的回调 | () => void | - | 1.29.0 |
onDropdownVisibleChange | 下拉框切换时的回调 | (visible: boolean) => void | - | 0.35.0 |
onExceed | 多选时,超出 max 后触发的回调 | (checkedItem: Entity[]) => void | - | 1.28.0 |
onFocus | 聚焦 Cascader 的回调 | (e: MouseEvent) => void | - | - |
onListScroll | 下拉面板滚动的回调 | (e: React.Event, panel: { panelIndex: number; activeNode: TreeNode; } ) => void | - | 1.15.0 |
onLoad | 节点加载完毕时触发的回调 | (newLoadedKeys: Set< string >, data: TreeNode) => void | - | 1.8.0 |
onSearch | 文本框值变化时回调 | (value: string) => void | - | - |
onSelect | 被选中时调用,返回选中项的 value | (value: string | number | (string \ | number)[]) => void | - |
TreeNode
属性 | 说明 | 类型 | 默认值 |
---|---|---|---|
children | 子节点 | TreeNode[] | - |
disabled | 不可选状态 >=0.35.0 | boolean | - |
isLeaf | 叶子节点 | boolean | - |
label | 展示的文本(必填) | ReactNode | - |
loading | 正在加载 | boolean | - |
value | 属性值(必填) | string|number | - |
Accessibility
ARIA
- Cascader 支持传入
aria-label
、aria-describedby
、aria-errormessage
、aria-invalid
、aria-labelledby
、aria-required
来表示该 Cascader 的相关信息; - Cascader 支持通过按下 Enter 键来选中选项、清空选项、展开下拉框