输入类 · Cascader
级联选择
用于选择多级分类下的某个选项。

代码演示

如何引入

基本用法

最简单的用法,默认只可以选叶子节点。

多选

version: >= 1.28.0
设置 multiple,可以进行多选。

可搜索的

通过设置 filterTreeNode 属性可支持搜索功能。默认对 label 值进行搜索,可通过 treeNodeFilterProp 更改。 默认搜索结果只会展示叶子结点的路径,想要显示更多的结果,可以设置 filterLeafOnlyfalse

可搜索的多选

支持多选和搜索同时使用(version >= v1.28.0),在这种场景下,可以通过按下 BackSpace 键来删除对应的已选项目。
可以使用 filterSorter 对筛选后的数据进行排序, filterSorter 于 v2.28.0 开始提供。
如果想要自定义渲染搜索后的选项,可以使用 filterRender 实现整行的自定义渲染,filterRender 于 v2.28.0 开始提供,函数参数如下:
使用示例如下
如果搜索结果中存在大量 Option,可以通过设置 virtualizeInSearch 开启搜索结果面板的虚拟化来优化性能,virtualizeInSearch 自 v2.44.0 提供。virtualizeInSearch 是一个包含下列值的对象:
  • height: Option 列表高度值
  • width: Option 列表宽度值
  • itemSize: 每行 Option 的高度

限制标签展示数量

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

在顶部/底部渲染附加项

我们在级联选择器的顶部、底部分别预留了插槽,你可以通过 topSlotbottomSlot 来设置。

受控

传入 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 iconReactNode-1.15.0
autoAdjustOverflow是否自动调整下拉框展开方向,用于边缘遮挡时自动调整展开方向booleantrue-
autoMergeValue设置自动合并 value。具体而言是,开启后,当某个父节点被选中时,value 将不包括该节点的子孙节点。不支持动态切换booleantrue1.28.0
bottomSlot底部插槽ReactNode-1.27.0
borderless无边框模式 >=2.33.0boolean
changeOnSelect是否允许选择非叶子节点booleanfalse-
className选择框的 className 属性string--
clearIcon可用于自定义清除按钮, showClear为true时有效ReactNode-2.25.0
defaultOpen设置是否默认打开下拉菜单booleanfalse-
defaultValue指定默认选中的条目string|number|CascaderData|(string|number|CascaderData)[]--
disabled是否禁用booleanfalse-
displayProp设置回填选项显示的属性值stringlabel-
displayRender设置回填格式(selected: string[] | Entity, idx?: number) => ReactNodeselected => selected.join('/')-
dropdownMargin下拉菜单计算溢出时的增加的冗余值,详见issue#549,作用同 Tooltip marginobject|number-2.25.0
dropdownClassName下拉菜单的 className 属性string--
dropdownStyle下拉菜单的样式object--
emptyContent当搜索无结果时展示的内容ReactNode暂无数据-
filterLeafOnly搜索结果是否只展示叶子结点路径booleantrue1.26.0
filterRender自定义渲染筛选后的选项(props: FilterRenderProps) => ReactNode;-2.28.0
filterSorter对筛选后的选项进行排序(first: CascaderData, second: CascaderData, inputValue: string) => number-2.28.0
filterTreeNode设置筛选,默认用 treeNodeFilterProp 的值作为要筛选的 TreeNode 的属性值, data 参数自 v2.28.0 开始提供((inputValue: string, treeNodeString: string, data?: CascaderData) => boolean) | booleanfalse-
getPopupContainer指定父级 DOM,下拉框将会渲染至该 DOM 中,自定义需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。() => HTMLElement() => document.body-
insetLabel前缀标签别名,主要用于 FormReactNode-0.28.0
leafOnly多选时设置 value 只包含叶子节点,即显示的 Tag 和 onChange 的 value 参数只包含叶子节点。不支持动态切换booleanfalse2.2.0
loadData异步加载数据,需要返回一个Promise(selectOptions: CascaderData[]) => Promise< void >-1.8.0
max多选时,限制多选选中的数量,超出 max 后将触发 onExceed 回调number-1.28.0
maxTagCount多选时,标签的最大展示数量,超出后将以 +N 形式展示number-1.28.0
motion设置下拉框弹出的动画booleantrue-
mouseEnterDelay鼠标移入后,延迟显示下拉框的时间,单位毫秒number50-
mouseLeaveDelay鼠标移出后,延迟消失下拉框的时间,单位毫秒number50-
multiple设置多选booleanfalse1.28.0
placeholder选择框默认文字string--
position方向,可选值:top,topLeft,topRight,left,leftTop,leftBottom,right,rightTop,rightBottom,bottom,bottomLeft,bottomRightstringbottom2.16.0
prefix前缀标签ReactNode-0.28.0
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean-2.15.0
restTagsPopoverPropsPopover 的配置属性,可以控制 position、zIndex、trigger 等,具体参考PopoverPopoverProps{}1.28.0
searchPlaceholder搜索框默认文字string--
searchPosition设置搜索框的位置,可选: triggercustomstringtrigger2.54.0
separator自定义分隔符,包括:搜索时显示在下拉框的内容以及单选时回显到 Trigger 的内容的分隔符string/2.2.0
showClear是否展示清除按钮booleanfalse0.35.0
showNext设置展开 Dropdown 子菜单的方式,可选: clickhoverstringclick1.29.0
showRestTagsPopover当超过 maxTagCount,hover 到 +N 时,是否通过 Popover 显示剩余内容booleanfalse1.28.0
size选择框大小,可选 largesmalldefaultstringdefault-
stopPropagation是否阻止下拉框上的点击事件冒泡booleantrue-
disableStrictly设置是否开启严格禁用。开启后,当节点是 disabled 的时候,则不能通过子级或者父级的关系改变选中状态booleanfalse1.32.0
style选择框的样式CSSProperties--
suffix后缀标签ReactNode-0.28.0
topSlot顶部插槽ReactNode-1.27.0
treeData展示数据,具体属性参考 CascaderDataCascaderData[][]-
treeNodeFilterProp搜索时输入项过滤对应的 CascaderData 属性stringlabel-
triggerRender自定义触发器渲染方法(props: TriggerRenderProps) => ReactNode-0.34.0
validateStatustrigger 的校验状态,仅影响展示样式。可选: default、error、warningstringdefault-
value(受控)选中的条目string|number|CascaderData|(string|number|CascaderData)[]--
virtualizeInSearch搜索列表虚拟化,用于大量树节点的情况,由 height, width, itemSize 组成Object--
zIndex下拉菜单的 zIndexnumber1030-
enableLeafClick多选时,是否启动点击叶子节点选项触发勾选booleanfalse2.2.0
onBlur失焦 Cascader 的回调(e: MouseEvent) => void--
onChange选中树节点时调用此函数,默认返回选中项 path 的 value 数组(value: string|number| CascaderData(string|number|CascaderData)[]) => void-
onChangeWithObject是否将选中项 option 的其他属性作为回调。设为 true 时,onChange 的入参类型会从 string/number 变为 TreeNode。此时如果是受控,也需要把 value 设置成 CascaderData 类型,且必须含有 value 的键值,defaultValue 同理booleanfalse1.16.0
onClearshowClear 为 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: CascaderData; } ) => void-1.15.0
onLoad节点加载完毕时触发的回调(newLoadedKeys: Set< string >, data: CascaderData) => void-1.8.0
onSearch文本框值变化时回调(value: string) => void--
onSelect被选中时调用,返回选中项的 value(value: string | number | (string | number)[]) => void--

CascaderData

属性说明类型默认值
children子节点CascaderData[]-
disabled不可选状态 >=0.35.0boolean-
isLeaf叶子节点boolean-
label展示的文本(必填)ReactNode-
loading正在加载boolean-
value属性值(必填)string|number-

Methods

绑定在组件实例上的方法,可以通过 ref 调用实现某些特殊交互
方法说明版本
close调用时可以手动关闭下拉列表v2.30.0
open调用时可以手动展开下拉列表v2.30.0
focus调用时可以手动聚焦v2.34.0
blur调用时可以手动失焦v2.34.0
search(value: string)手动触发搜索,需同时设置 filterTreeNode 开启搜索,searchPosition 为 custom 自定义展示搜素框v2.54.0

Accessibility

ARIA

  • Cascader 支持传入 aria-labelaria-describedbyaria-errormessagearia-invalidaria-labelledbyaria-required 来表示该 Cascader 的相关信息;
  • Cascader 支持通过按下 Enter 键来选中选项、清空选项、展开下拉框

文案规范

  • 选择器选项
    • 如果没有默认选项,就使用“Select”做占位文案
    • 选项要按首字母顺序或者其他有逻辑的排列顺序,使用户更好地找到选项
    • 使用语句书写规范(首字母大写,其余小写),避免在句尾使用逗号和分号
    • 清晰表达出选项所表示的选择目的

设计变量