--- title: Cascader - 级联选择器 nav: order: 1 title: 桌面组件 path: /design group: order: 3 title: 数据录入 path: /dataInput --- 定义：级联选择器适用于有清晰层级结构的数据集合，用户可以通过逐级查看并选择。一般而言，级联选择器包括：选择器和级联。 ## 单选级联选择器 提供单选的级联选择器，选取后展示每一层级所选的内容。 ## 多选级联选择器 提供多选的级联选择器，通过标签展示多选内容。 ## 移入展开 通过移入展开下级菜单，点击完成选择。 ## 可折叠选项多选选择器 多选情况下折叠选中项，超出该数值的选中项折叠。 ## 不同尺寸的级联选择器 提供大中小三种不同高度、宽度的选择器，以适应不同尺寸布局。 ## 只显示最后一级的级联选择器 可以仅在输入框中显示选中项最后一级的标签，而不是选中项所在的完整路径。 ## 禁用选项 通过指定 options 里的 disabled 字段。 ## 动态加载选项 使用 loadData 实现动态加载选项。 ## 省市区级联选择器 ## 搜索 可以直接搜索选项并选择。 ## API | 参数 | 说明 | 类型 | 默认值 | 版本 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- | ------------------ | | allowClear | 是否支持清除 | boolean | true | | | autoFocus | 自动获取焦点 | boolean | false | | | bordered | 是否有边框 | boolean | true | | | clearIcon | 自定义的选择框清空图标 | ReactNode | - | | | changeOnSelect | （单选时生效）当此项为 true 时，点选每级菜单选项值都会发生变化，具体见上面的演示 | boolean | false | | | className | 自定义类名 | string | - | | | defaultValue | 默认的选中项 | string[] \| number[] | [] | | | disabled | 禁用 | boolean | false | | | displayRender | 选择后展示的渲染函数 | (label, selectedOptions) => ReactNode | label => label.join(`/`) | `multiple`: 4.18.0 | | dropdownClassName | 自定义浮层类名 | string | - | 4.17.0 | | dropdownRender | 自定义下拉框内容 | (menus: ReactNode) => ReactNode | - | 4.4.0 | | expandIcon | 自定义次级菜单展开图标 | ReactNode | - | 4.4.0 | | expandTrigger | 次级菜单的展开方式，可选 'click' 和 'hover' | string | `click` | | | fieldNames | 自定义 options 中 label value children 的字段 | object | { label: `label`, value: `value`, children: `children` } | | | getPopupContainer | 菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。[示例](https://codepen.io/afc163/pen/zEjNOy?editors=0010) | function(triggerNode) | () => document.body | | | loadData | 用于动态加载选项，无法与 `showSearch` 一起使用 | (selectedOptions) => void | - | | | maxTagCount | 最多显示多少个 tag，响应式模式会对性能产生损耗 | number \| `responsive` | - | 4.17.0 | | maxTagPlaceholder | 隐藏 tag 时显示的内容 | ReactNode \| function(omittedValues) | - | 4.17.0 | | notFoundContent | 当下拉列表为空时显示的内容 | string | `Not Found` | | | open | 控制浮层显隐 | boolean | - | 4.17.0 | | options | 可选项数据源 | [Option](#Option)[] | - | | | placeholder | 输入框占位文本 | string | `请选择` | | | placement | 浮层预设位置 | `bottomLeft` `bottomRight` `topLeft` `topRight` | `bottomLeft` | 4.17.0 | | showSearch | 在选择框中显示搜索框 | boolean \| [Object](#showSearch) | false | | | size | 输入框大小 | `large` \| `middle` \| `small` | - | | | status | 设置校验状态 | 'error' \| 'warning' | - | 4.19.0 | | style | 自定义样式 | CSSProperties | - | | | suffixIcon | 自定义的选择框后缀图标 | ReactNode | - | | | tagRender | 自定义 tag 内容，多选时生效 | (props) => ReactNode | - | 4.17.0 | | value | 指定选中项 | string[] \| number[] | - | | | onChange | 选择完成后的回调 | (value, selectedOptions) => void | - | | | onDropdownVisibleChange | 显示/隐藏浮层的回调 | (value) => void | - | 4.17.0 | | multiple | 支持多选节点 | boolean | - | 4.17.0 | | removeIcon | 自定义的多选框清除图标 | ReactNode | - | | | searchValue | 设置搜索的值，需要与 `showSearch` 配合使用 | string | - | 4.17.0 | | onSearch | 监听搜索，返回输入的值 | (search: string) => void | - | 4.17.0 | | dropdownMenuColumnStyle | 下拉菜单列的样式 | CSSProperties | - | | | regionType | 区域下拉选择器类型（非必填） | `'province' \| 'city' \| 'country'` | - | | regionCodes | 区域下拉选择器类型支持的区域编码集合（非必填，默认支持全部区域） | string[] \| number[] | - | ### showSearch `showSearch` 为对象时，其中的字段： | 参数 | 说明 | 类型 | 默认值 | 版本 | | --------------- | --------------------------------------------------------------------------------------------- | ------------------------------------- | ------ | ---- | | filter | 接收 `inputValue` `path` 两个参数，当 `path` 符合筛选条件时，应返回 true，反之则返回 false | function(inputValue, path): boolean | - | | | limit | 搜索结果展示数量 | number \| false | 50 | | | matchInputWidth | 搜索结果列表是否与输入框同宽（[效果](https://github.com/ant-design/ant-design/issues/25779)） | boolean | true | | | render | 用于渲染 filter 后的选项 | function(inputValue, path): ReactNode | - | | | sort | 用于排序 filter 后的选项 | function(a, b, inputValue) | - | | ### Option ```typescript interface Option { value: string | number; label?: React.ReactNode; disabled?: boolean; children?: Option[]; // 标记是否为叶子节点，设置了 `loadData` 时有效 // 设为 `false` 时会强制标记为父节点，即使当前节点没有 children，也会显示展开图标 isLeaf?: boolean; } ``` ## 方法 | 名称 | 描述 | 版本 | | ------- | -------- | ---- | | blur() | 移除焦点 | | | focus() | 获取焦点 | |