Cascader
级联选择

级联选择框。
使用import{ Cascader }from"antd";

何时使用

  • 需要从一组相关联的数据集合进行选择,例如省市区,公司层级,事物分类等。
  • 从一个较大的数据集合中进行选择时,用多级分类进行分隔,方便选择。
  • 比起 Select 组件,可以在同一个浮层中完成选择,有较好的体验。

代码演示

Please select

省市区级联。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Unselect Change city

切换按钮和结果分开。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

通过指定 options 里的 disabled 字段。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

一次性选择多个选项。通过添加 disableCheckbox 属性,选择具体某一个checkbox禁用 。可以通过类名修改禁用的样式。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code






不同大小的级联选择器。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select

自定义字段名。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select

使用 dropdownRender 对下拉菜单进行自由扩展。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select
Please select
Please select
Please select

Cascader 形态变体,可选 outlined filled borderless underlined 四种形态。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
暂无数据
暂无数据

适用于一些需要内嵌适用的场景。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
>= 5.10.0
Zhejiang / Hangzhou / West Lake

默认值通过数组的方式指定。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

通过移入展开下级菜单,点击完成选择。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

这种交互允许只选中父级选项。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code


通过设置 showCheckedStrategy 选择回填方式。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Zhejiang / Hangzhou / West Lake (752100)

例如给最后一项加上邮编链接。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

使用 loadData 实现动态加载选项。

注意:loadDatashowSearch 无法一起使用。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select


Please select


Please select


Please select


Please select

通过 prefix 自定前缀,通过 suffixIcon 自定义选择框后缀图标,通过 expandIcon 自定义次级菜单展开图标。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.22.0


Please select

可以通过 placement 手动指定弹出的位置。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Error
Warning multiple

使用 status 为 Cascader 添加状态,可选 error 或者 warning

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code

API

通用属性参考:通用属性

<Cascader options={options} onChange={onChange} />
参数说明类型默认值版本
allowClear支持清除boolean | { clearIcon?: ReactNode }true5.8.0: 支持对象形式
autoClearSearchValue是否在选中项后清空搜索框,只在 multipletrue 时有效booleantrue5.9.0
autoFocus自动获取焦点booleanfalse
changeOnSelect单选时生效(multiple 下始终都可以选择),点选每级菜单选项值都会发生变化。booleanfalse
className自定义类名string-
defaultValue默认的选中项string[] | number[][]
disabled禁用booleanfalse
displayRender选择后展示的渲染函数(label, selectedOptions) => ReactNodelabel => label.join(/)multiple: 4.18.0
tagRender自定义 tag 内容 render,仅在多选时生效({ label: string, onClose: function, value: string }) => ReactNode-
popupClassName自定义浮层类名string-4.23.0
dropdownRender自定义下拉框内容(menus: ReactNode) => ReactNode-4.4.0
expandIcon自定义次级菜单展开图标ReactNode-4.4.0
expandTrigger次级菜单的展开方式,可选 'click' 和 'hover'stringclick
fieldNames自定义 options 中 label value children 的字段object{ label: label, value: value, children: children }
getPopupContainer菜单渲染父节点。默认渲染到 body 上,如果你遇到菜单滚动定位问题,试试修改为滚动的区域,并相对其定位。示例function(triggerNode)() => document.body
loadData用于动态加载选项,无法与 showSearch 一起使用(selectedOptions) => void-
maxTagCount最多显示多少个 tag,响应式模式会对性能产生损耗number | responsive-4.17.0
maxTagPlaceholder隐藏 tag 时显示的内容ReactNode | function(omittedValues)-4.17.0
maxTagTextLength最大显示的 tag 文本长度number-4.17.0
notFoundContent当下拉列表为空时显示的内容ReactNodeNot Found
open控制浮层显隐boolean-4.17.0
options可选项数据源Option[]-
placeholder输入框占位文本string-
placement浮层预设位置bottomLeft bottomRight topLeft topRightbottomLeft4.17.0
prefix自定义前缀ReactNode-5.22.0
showSearch在选择框中显示搜索框boolean | Objectfalse
size输入框大小large | middle | small-
status设置校验状态'error' | 'warning'-4.19.0
style自定义样式CSSProperties-
suffixIcon自定义的选择框后缀图标ReactNode-
value指定选中项string[] | number[]-
variant形态变体outlined | borderless | filled | underlinedoutlined5.13.0 | underlined: 5.24.0
onChange选择完成后的回调(value, selectedOptions) => void-
onDropdownVisibleChange显示/隐藏浮层的回调(value) => void-4.17.0
multiple支持多选节点boolean-4.17.0
showCheckedStrategy定义选中项回填的方式。Cascader.SHOW_CHILD: 只显示选中的子节点。Cascader.SHOW_PARENT: 只显示父节点(当父节点下所有子节点都选中时)。Cascader.SHOW_PARENT | Cascader.SHOW_CHILDCascader.SHOW_PARENT4.20.0
removeIcon自定义的多选框清除图标ReactNode-
searchValue设置搜索的值,需要与 showSearch 配合使用string-4.17.0
onSearch监听搜索,返回输入的值(search: string) => void-4.17.0
dropdownMenuColumnStyle下拉菜单列的样式CSSProperties-
optionRender自定义渲染下拉选项(option: Option) => React.ReactNode-5.16.0

showSearch

showSearch 为对象时,其中的字段:

参数说明类型默认值版本
filter接收 inputValue path 两个参数,当 path 符合筛选条件时,应返回 true,反之则返回 falsefunction(inputValue, path): boolean-
limit搜索结果展示数量number | false50
matchInputWidth搜索结果列表是否与输入框同宽(效果booleantrue
render用于渲染 filter 后的选项function(inputValue, path): ReactNode-
sort用于排序 filter 后的选项function(a, b, inputValue)-

Option

interface Option {
value: string | number;
label?: React.ReactNode;
disabled?: boolean;
children?: Option[];
// 标记是否为叶子节点,设置了 `loadData` 时有效
// 设为 `false` 时会强制标记为父节点,即使当前节点没有 children,也会显示展开图标
isLeaf?: boolean;
}

方法

名称描述版本
blur()移除焦点
focus()获取焦点

注意,如果需要获得中国省市区数据,可以参考 china-division

主题变量(Design Token)

组件 Token如何定制?

Token 名称描述类型默认值
controlItemWidth选项宽度string | number111
controlWidth选择器宽度string | number184
dropdownHeight下拉菜单高度string | number180
menuPadding选项菜单(单列)内间距undefined | Padding<string | number>4
optionPadding选项内间距undefined | Padding<string | number>5px 12px
optionSelectedBg选项选中时背景色string#e6f4ff
optionSelectedColor选项选中时文本颜色stringrgba(0,0,0,0.88)
optionSelectedFontWeight选项选中时字重undefined | FontWeight600

全局 Token如何定制?