使用import { Cascader } from 'antd'; |
文档贡献者
通用属性参考：通用属性
<Cascader options={options} onChange={onChange} />
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| allowClear | 支持清除 | boolean | { clearIcon?: ReactNode } | true | 5.8.0: 支持对象形式 |
是否在选中项后清空搜索框，只在 multiple 为 true 时有效 | boolean | true | 5.9.0 | |
是否带边框，请使用 variant 替代 | boolean | true | - | |
| 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 | - | |
自定义浮层类名，使用 classNames.popup.root 替换 | string | - | 4.23.0 | |
自定义浮层类名，请使用 classNames.popup.root 替代 | string | - | - | |
自定义下拉框内容，请使用 popupRender 替换 | (menus: ReactNode) => ReactNode | - | 4.4.0 | |
| popupRender | 自定义下拉框内容 | (menus: ReactNode) => ReactNode | - | |
下拉菜单的 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 | - | |
| loadingIcon | 自定义的加载图标 | ReactNode | - | |
| 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 |
是否显示箭头图标，请使用 suffixIcon={null} 替代 | boolean | true | - | |
| showSearch | 在选择框中显示搜索框 | boolean | Object | false | |
| size | 输入框大小 | large | medium | small | medium | |
| 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 | - | |
显示/隐藏浮层的回调，请使用 onOpenChange 替换 | (value) => void | - | 4.17.0 | |
| onOpenChange | 显示/隐藏浮层的回调 | (value) => void | - | |
显示或隐藏浮层的回调，请使用 onOpenChange 替代 | (value) => void | - | - | |
| multiple | 支持多选节点 | boolean | - | 4.17.0 |
| removeIcon | 自定义的多选框清除图标 | ReactNode | - | |
| showCheckedStrategy | 定义选中项回填的方式（仅在 multiple 为 true 时生效）。Cascader.SHOW_CHILD: 只显示选中的子节点。Cascader.SHOW_PARENT: 只显示父节点（当父节点下所有子节点都选中时）。 | Cascader.SHOW_PARENT | Cascader.SHOW_CHILD | Cascader.SHOW_PARENT | 4.20.0 |
设置搜索的值，需要与 showSearch 配合使用 | string | - | 4.17.0 | |
| 监听搜索，返回输入的值 | (search: string) => void | - | 4.17.0 | |
下拉菜单列的样式，请使用 styles.popup.listItem 替换 | CSSProperties | - | ||
下拉菜单列的样式，请使用 styles.popup.listItem 替换 | CSSProperties | - | ||
| optionRender | 自定义渲染下拉选项 | (option: Option) => React.ReactNode | - | 5.16.0 |
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 |
| searchIcon | 自定义的搜索图标 | ReactNode | - | 6.3.0 |
interface Option {value: string | number;label?: React.ReactNode;disabled?: boolean;children?: Option[];// 标记是否为叶子节点，设置了 `loadData` 时有效// 设为 `false` 时会强制标记为父节点，即使当前节点没有 children，也会显示展开图标isLeaf?: boolean;}
| 名称 | 描述 | 版本 |
|---|---|---|
| blur() | 移除焦点 | |
| focus() | 获取焦点 |
注意，如果需要获得中国省市区数据，可以参考 china-division。
| 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 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| colorBgContainer | 组件的容器背景色，例如：默认按钮、输入框等。务必不要将其与 `colorBgElevated` 混淆。 | string | #ffffff |
| colorBgContainerDisabled | 控制容器在禁用状态下的背景色。 | string | rgba(0,0,0,0.04) |
| colorBorder | 默认使用的边框颜色, 用于分割不同的元素，例如：表单的分割线、卡片的分割线等。 | string | #d9d9d9 |
| colorHighlight | 控制页面元素高亮时的颜色。 | string | #ff4d4f |
| colorIcon | 控制弱操作图标的颜色，例如 allowClear 或 Alert 关闭按钮。 * | string | rgba(0,0,0,0.45) |
| colorPrimary | 品牌色是体现产品特性和传播理念最直观的视觉元素之一。在你完成品牌主色的选取之后，我们会自动帮你生成一套完整的色板，并赋予它们有效的设计语义 | string | #1677ff |
| colorPrimaryBorder | 主色梯度下的描边用色，用在 Slider 等组件的描边上。 | string | #91caff |
| colorPrimaryHover | 主色梯度下的悬浮态。 | string | #4096ff |
| colorSplit | 用于作为分割线的颜色，此颜色和 colorBorderSecondary 的颜色一致，但是用的是透明色。 | string | rgba(5,5,5,0.06) |
| colorText | 最深的文本色。为了符合W3C标准，默认的文本颜色使用了该色，同时这个颜色也是最深的中性色。 | string | rgba(0,0,0,0.88) |
| colorTextDisabled | 控制禁用状态下的字体颜色。 | string | rgba(0,0,0,0.25) |
| colorWhite | 不随主题变化的纯白色 | string | #fff |
| borderRadiusSM | SM号圆角，用于组件小尺寸下的圆角，如 Button、Input、Select 等输入类控件在 small size 下的圆角 | number | 4 |
| controlInteractiveSize | 控制组件的交互大小。 | number | 16 |
| controlItemBgHover | 控制组件项在鼠标悬浮时的背景颜色。 | string | rgba(0,0,0,0.04) |
| fontFamily | Ant Design 的字体家族中优先使用系统默认的界面字体，同时提供了一套利于屏显的备用字体库，来维护在不同平台以及浏览器的显示下，字体始终保持良好的易读性和可读性，体现了友好、稳定和专业的特性。 | string | -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji' |
| fontSize | 设计系统中使用最广泛的字体大小，文本梯度也将基于该字号进行派生。 | number | 14 |
| fontSizeIcon | 控制选择器、级联选择器等中的操作图标字体大小。正常情况下与 fontSizeSM 相同。 | number | 12 |
| fontSizeLG | 大号字体大小 | number | 16 |
| lineHeight | 文本行高 | number | 1.5714285714285714 |
| lineType | 用于控制组件边框、分割线等的样式，默认是实线 | string | solid |
| lineWidth | 用于控制组件边框、分割线等的宽度 | number | 1 |
| lineWidthBold | 描边类组件的默认线宽，如 Button、Input、Select 等输入类控件。 | number | 2 |
| lineWidthFocus | 控制线条的宽度，当组件处于聚焦态时。 | number | 3 |
| marginXS | 控制元素外边距，小尺寸。 | number | 8 |
| motionDurationFast | 动效播放速度，快速。用于小型元素动画交互 | string | 0.1s |
| motionDurationMid | 动效播放速度，中速。用于中型元素动画交互 | string | 0.2s |
| motionDurationSlow | 动效播放速度，慢速。用于大型元素如面板动画交互 | string | 0.3s |
| motionEaseInBack | 预设动效曲率 | string | |
| motionEaseOutBack | 预设动效曲率 | string | |
| paddingXS | 控制元素的特小内间距。 | number | 8 |
| paddingXXS | 控制元素的极小内间距。 | number | 4 |