级联选择

级联选择框。

何时使用

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

代码演示

• 基本 · basic
• 默认值 · default-value
• 可以自定义显示 · custom-trigger
• 移入展开 · hover
• 禁用选项 · disabled-option
• 选择即改变 · change-on-select
• 多选 · multiple
• 自定义回填方式 · showCheckedStrategy
• 大小 · size
• 自定义已选项 · custom-render
• 搜索 · search
• 动态加载选项 · lazy
• 自定义字段名 · fields-name
• 前后缀 · suffix
• 扩展菜单 · custom-dropdown
• 弹出位置 · placement
• 形态变体 · variant
• 自定义状态 · status
• 自定义语义结构的样式和类 · style-class
• 面板使用 · panel

API

通用属性参考：通用属性

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

showSearch

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

Option

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

方法

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

Semantic DOM

语义说明来源: vendor/.dumi/theme/common/SelectSemanticTemplate.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

声明来源: vendor/components/cascader/style/index.ts

import type { CSSProperties } from 'react';

import { genCompactItemStyle } from '../../style/compact-item';

import type { FullToken, GenerateStyle, GlobalToken } from '../../theme/internal';

import { genStyleHooks } from '../../theme/internal';

import getColumnsStyle from './columns';

export interface ComponentToken {
  /**
   * @desc 选择器宽度
   * @descEN Width of Cascader
   */
  controlWidth: number | string;
  /**
   * @desc 选项宽度
   * @descEN Width of item
   */
  controlItemWidth: number | string;
  /**
   * @desc 下拉菜单高度
   * @descEN Height of dropdown
   */
  dropdownHeight: number | string;
  /**
   * @desc 选项选中时背景色
   * @descEN Background color of selected item
   */
  optionSelectedBg: string;
  /**
   * @desc 选项选中时文本颜色
   * @descEN Text color when option is selected
   */
  optionSelectedColor: string;
  /**
   * @desc 选项选中时字重
   * @descEN Font weight of selected item
   */
  optionSelectedFontWeight: CSSProperties['fontWeight'];
  /**
   * @desc 选项内间距
   * @descEN Padding of menu item
   */
  optionPadding: CSSProperties['padding'];
  /**
   * @desc 选项菜单（单列）内间距
   * @descEN Padding of menu item (single column)
   */
  menuPadding: CSSProperties['padding'];
}

export type CascaderToken = FullToken<'Cascader'>;

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

• vendor/components/cascader/Panel.tsx
• vendor/components/cascader/hooks/useIcons.tsx
• vendor/components/cascader/index.tsx
• vendor/components/cascader/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。