Ant Design

⌘ K

6.0.0-alpha.3

Cascader
级联选择

级联选择框。

使用import { Cascader } from "antd";

反馈

components/cascader 提交问题待解决

文档

编辑此页

文档贡献者

AutoComplete自动完成 Checkbox多选框

Ant Design

⌘ K

6.0.0-alpha.3

Cascader
级联选择

级联选择框。

使用import { Cascader } from "antd";

反馈

components/cascader 提交问题待解决

文档

编辑此页

文档贡献者

AutoComplete自动完成 Checkbox多选框

何时使用

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

代码演示

API

通用属性参考：通用属性

jsx

<Cascader options={options} onChange={onChange} />

参数	说明	类型	默认值	版本
allowClear	支持清除	boolean \| { clearIcon?: ReactNode }	true	5.8.0: 支持对象形式
~~autoClearSearchValue~~	是否在选中项后清空搜索框，只在 `multiple` 为 `true` 时有效	boolean	true	5.9.0
autoFocus	自动获取焦点	boolean	false
changeOnSelect	单选时生效（multiple 下始终都可以选择），点选每级菜单选项值都会发生变化。	boolean	false
className	自定义类名	string	-
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-
defaultOpen	是否默认展示浮层	boolean	-
defaultValue	默认的选中项	string[] \| number[]	[]
disabled	禁用	boolean	false
displayRender	选择后展示的渲染函数	(label, selectedOptions) => ReactNode	label => label.join(`/`)	`multiple`: 4.18.0
tagRender	自定义 tag 内容 render，仅在多选时生效	({ label: string, onClose: function, value: string }) => ReactNode	-
~~popupClassName~~	自定义浮层类名，使用 `classNames.popup.root` 替换	string	-	4.23.0
~~dropdownRender~~	自定义下拉框内容，请使用 `popupRender` 替换	(menus: ReactNode) => ReactNode	-	4.4.0
popupRender	自定义下拉框内容	(menus: ReactNode) => ReactNode	-
~~dropdownStyle~~	下拉菜单的 style 属性，使用 `styles.popup.root` 替换	CSSProperties	-
expandIcon	自定义次级菜单展开图标	ReactNode	-	4.4.0
expandTrigger	次级菜单的展开方式，可选 'click' 和 'hover'	string	`click`
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	当下拉列表为空时显示的内容	ReactNode	`Not Found`
open	控制浮层显隐	boolean	-	4.17.0
options	可选项数据源	Option[]	-
placeholder	输入框占位文本	string	-
placement	浮层预设位置	`bottomLeft` `bottomRight` `topLeft` `topRight`	`bottomLeft`	4.17.0
prefix	自定义前缀	ReactNode	-	5.22.0
showSearch	在选择框中显示搜索框	boolean \| Object	false
size	输入框大小	`large` \| `middle` \| `small`	-
status	设置校验状态	'error' \| 'warning'	-	4.19.0
styles	用于自定义组件内部各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-
suffixIcon	自定义的选择框后缀图标	ReactNode	-
value	指定选中项	string[] \| number[]	-
variant	形态变体	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.0
onChange	选择完成后的回调	(value, selectedOptions) => void	-
~~onDropdownVisibleChange~~	显示/隐藏浮层的回调，请使用 `onOpenChange` 替换	(value) => void	-	4.17.0
onOpenChange	显示/隐藏浮层的回调	(value) => void	-
multiple	支持多选节点	boolean	-	4.17.0
showCheckedStrategy	定义选中项回填的方式。`Cascader.SHOW_CHILD`: 只显示选中的子节点。`Cascader.SHOW_PARENT`: 只显示父节点（当父节点下所有子节点都选中时）。	`Cascader.SHOW_PARENT` \| `Cascader.SHOW_CHILD`	`Cascader.SHOW_PARENT`	4.20.0
removeIcon	自定义的多选框清除图标	ReactNode	-
~~searchValue~~	设置搜索的值，需要与 `showSearch` 配合使用	string	-	4.17.0
~~onSearch~~	监听搜索，返回输入的值	(search: string) => void	-	4.17.0
~~dropdownMenuColumnStyle~~	下拉菜单列的样式，请使用 `popupMenuColumnStyle` 替换	CSSProperties	-
popupMenuColumnStyle	下拉菜单列的样式	CSSProperties	-
optionRender	自定义渲染下拉选项	(option: Option) => React.ReactNode	-	5.16.0

showSearch

showSearch 为对象时，其中的字段：

参数	说明	类型	默认值	版本
autoClearSearchValue	是否在选中项后清空搜索框，只在 `multiple` 为 `true` 时有效	boolean	true	5.9.0
filter	接收 `inputValue` `path` 两个参数，当 `path` 符合筛选条件时，应返回 true，反之则返回 false	function(inputValue, path): boolean	-
limit	搜索结果展示数量	number \| false	50
matchInputWidth	搜索结果列表是否与输入框同宽（效果）	boolean	true
render	用于渲染 filter 后的选项	function(inputValue, path): ReactNode	-
sort	用于排序 filter 后的选项	function(a, b, inputValue)	-
searchValue	设置搜索的值，需要与 `showSearch` 配合使用	string	-	4.17.0
onSearch	监听搜索，返回输入的值	(search: string) => void	-	4.17.0

Option

typescript

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

方法

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

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

Semantic DOM

prefix

contributors / thinkasany

root
根元素，包含相对定位、行内 flex 布局、光标样式、过渡动画、边框等选择器容器的基础样式
prefix
前缀元素，包含前缀内容的布局和样式
input
输入框元素，包含搜索输入框的样式、光标控制、字体继承等搜索相关样式，去除了边框样式
suffix
后缀元素，包含后缀内容的布局和样式，如清除按钮、箭头图标等
popup.root
弹出菜单元素，包含弹出层的定位、层级、背景、边框、阴影等弹出容器样式
popup.list
弹出菜单列表元素，包含选项列表的布局、滚动、最大高度等列表容器样式
popup.listItem
弹出菜单条目元素，包含选项项的内边距、悬浮效果、选中状态、禁用状态等选项交互样式

主题变量（Design Token）

组件 Token如何定制？

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

全局 Token如何定制？

何时使用

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

代码演示

Please select

基本

省市区级联。

Unselect Change city

可以自定义显示

切换按钮和结果分开。

禁用选项

通过指定 options 里的 disabled 字段。

多选

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

大小

不同大小的级联选择器。

Please select

搜索

可以直接搜索选项并选择。

Cascader[showSearch] 暂不支持服务端搜索，更多信息见 #5547

Please select

自定义字段名

自定义字段名。

Please select

形态变体

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

5.13.0

🏠

Object styles

✅

Function styles

自定义语义结构的样式和类

通过 classNames 和 styles 传入对象/函数可以自定义 Cascader 的语义化结构样式。

6.0.0

Zhejiang / Hangzhou / West Lake

默认值

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

移入展开

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

选择即改变

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

自定义回填方式

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

Zhejiang / Hangzhou / West Lake (752100)

自定义已选项

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

动态加载选项

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

注意：loadData 与 showSearch 无法一起使用。

Please select

前后缀

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

5.22.0

topLefttopRightbottomLeftbottomRight

Please select

弹出位置

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

Error

Warning multiple

自定义状态

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

暂无数据

面板使用

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

>= 5.10.0

API

通用属性参考：通用属性

jsx

<Cascader options={options} onChange={onChange} />

参数	说明	类型	默认值	版本
allowClear	支持清除	boolean \| { clearIcon?: ReactNode }	true	5.8.0: 支持对象形式
~~autoClearSearchValue~~	是否在选中项后清空搜索框，只在 `multiple` 为 `true` 时有效	boolean	true	5.9.0
autoFocus	自动获取焦点	boolean	false
changeOnSelect	单选时生效（multiple 下始终都可以选择），点选每级菜单选项值都会发生变化。	boolean	false
className	自定义类名	string	-
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>	-
defaultOpen	是否默认展示浮层	boolean	-
defaultValue	默认的选中项	string[] \| number[]	[]
disabled	禁用	boolean	false
displayRender	选择后展示的渲染函数	(label, selectedOptions) => ReactNode	label => label.join(`/`)	`multiple`: 4.18.0
tagRender	自定义 tag 内容 render，仅在多选时生效	({ label: string, onClose: function, value: string }) => ReactNode	-
~~popupClassName~~	自定义浮层类名，使用 `classNames.popup.root` 替换	string	-	4.23.0
~~dropdownRender~~	自定义下拉框内容，请使用 `popupRender` 替换	(menus: ReactNode) => ReactNode	-	4.4.0
popupRender	自定义下拉框内容	(menus: ReactNode) => ReactNode	-
~~dropdownStyle~~	下拉菜单的 style 属性，使用 `styles.popup.root` 替换	CSSProperties	-
expandIcon	自定义次级菜单展开图标	ReactNode	-	4.4.0
expandTrigger	次级菜单的展开方式，可选 'click' 和 'hover'	string	`click`
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	当下拉列表为空时显示的内容	ReactNode	`Not Found`
open	控制浮层显隐	boolean	-	4.17.0
options	可选项数据源	Option[]	-
placeholder	输入框占位文本	string	-
placement	浮层预设位置	`bottomLeft` `bottomRight` `topLeft` `topRight`	`bottomLeft`	4.17.0
prefix	自定义前缀	ReactNode	-	5.22.0
showSearch	在选择框中显示搜索框	boolean \| Object	false
size	输入框大小	`large` \| `middle` \| `small`	-
status	设置校验状态	'error' \| 'warning'	-	4.19.0
styles	用于自定义组件内部各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>	-
suffixIcon	自定义的选择框后缀图标	ReactNode	-
value	指定选中项	string[] \| number[]	-
variant	形态变体	`outlined` \| `borderless` \| `filled` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.0
onChange	选择完成后的回调	(value, selectedOptions) => void	-
~~onDropdownVisibleChange~~	显示/隐藏浮层的回调，请使用 `onOpenChange` 替换	(value) => void	-	4.17.0
onOpenChange	显示/隐藏浮层的回调	(value) => void	-
multiple	支持多选节点	boolean	-	4.17.0
showCheckedStrategy	定义选中项回填的方式。`Cascader.SHOW_CHILD`: 只显示选中的子节点。`Cascader.SHOW_PARENT`: 只显示父节点（当父节点下所有子节点都选中时）。	`Cascader.SHOW_PARENT` \| `Cascader.SHOW_CHILD`	`Cascader.SHOW_PARENT`	4.20.0
removeIcon	自定义的多选框清除图标	ReactNode	-
~~searchValue~~	设置搜索的值，需要与 `showSearch` 配合使用	string	-	4.17.0
~~onSearch~~	监听搜索，返回输入的值	(search: string) => void	-	4.17.0
~~dropdownMenuColumnStyle~~	下拉菜单列的样式，请使用 `popupMenuColumnStyle` 替换	CSSProperties	-
popupMenuColumnStyle	下拉菜单列的样式	CSSProperties	-
optionRender	自定义渲染下拉选项	(option: Option) => React.ReactNode	-	5.16.0

showSearch

showSearch 为对象时，其中的字段：

参数	说明	类型	默认值	版本
autoClearSearchValue	是否在选中项后清空搜索框，只在 `multiple` 为 `true` 时有效	boolean	true	5.9.0
filter	接收 `inputValue` `path` 两个参数，当 `path` 符合筛选条件时，应返回 true，反之则返回 false	function(inputValue, path): boolean	-
limit	搜索结果展示数量	number \| false	50
matchInputWidth	搜索结果列表是否与输入框同宽（效果）	boolean	true
render	用于渲染 filter 后的选项	function(inputValue, path): ReactNode	-
sort	用于排序 filter 后的选项	function(a, b, inputValue)	-
searchValue	设置搜索的值，需要与 `showSearch` 配合使用	string	-	4.17.0
onSearch	监听搜索，返回输入的值	(search: string) => void	-	4.17.0

Option

typescript

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

方法

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

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

Semantic DOM

prefix

contributors / thinkasany

root
根元素，包含相对定位、行内 flex 布局、光标样式、过渡动画、边框等选择器容器的基础样式
prefix
前缀元素，包含前缀内容的布局和样式
input
输入框元素，包含搜索输入框的样式、光标控制、字体继承等搜索相关样式，去除了边框样式
suffix
后缀元素，包含后缀内容的布局和样式，如清除按钮、箭头图标等
popup.root
弹出菜单元素，包含弹出层的定位、层级、背景、边框、阴影等弹出容器样式
popup.list
弹出菜单列表元素，包含选项列表的布局、滚动、最大高度等列表容器样式
popup.listItem
弹出菜单条目元素，包含选项项的内边距、悬浮效果、选中状态、禁用状态等选项交互样式

主题变量（Design Token）

组件 Token如何定制？

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