> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/cascader.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Cascader 级联选择

逐级选择地区、分类等有层级关系的选项。


## 基础用法

[](#)
`children` 定义子选项。展开父项后选择末级选项，确认完整路径；`disabled` 禁用整个分支。


项目分类

选择项目分类

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/basic.tsx"
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [
  {
    value: 'design',
    label: '设计',
    children: [
      { value: 'interface', label: '界面设计' },
      { value: 'brand', label: '品牌设计' },
    ],
  },
  {
    value: 'engineering',
    label: '工程',
    children: [
      { value: 'frontend', label: '前端开发' },
      { value: 'backend', label: '后端开发' },
    ],
  },
  { value: 'archived', label: '归档分类', disabled: true },
];

export function CascaderBasic() {
  return (
    <Form layout="vertical">
      <FormField label="项目分类">
        <Cascader options={options} placeholder="选择项目分类" />
      </FormField>
    </Form>
  );
}
```

展开代码


## 示例

### 受控路径

`value` 是从根节点到选中节点的值数组，`onChange` 同时返回完整的选项对象路径。清除时，两者都为空数组。展开父项只改变待选路径；返回已提交路径所属的一级分支时，会恢复下级选择。


收货地区

浙江 / 杭州 / 西湖区

选中路径：["zhejiang","hangzhou","xihu"]

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/controlled.tsx"
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      {
        value: 'hangzhou',
        label: '杭州',
        children: [
          { value: 'xihu', label: '西湖区' },
          { value: 'yuhang', label: '余杭区' },
        ],
      },
      { value: 'ningbo', label: '宁波', children: [{ value: 'haishu', label: '海曙区' }] },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京', children: [{ value: 'gulou', label: '鼓楼区' }] },
      { value: 'suzhou', label: '苏州', children: [{ value: 'gusu', label: '姑苏区' }] },
    ],
  },
  { value: 'archived', label: '归档地区', disabled: true },
];

export function CascaderControlled() {
  const [value, setValue] = useState<string[]>(['zhejiang', 'hangzhou', 'xihu']);
  return (
    <Form layout="vertical">
      <FormField label="收货地区">
        <Cascader options={regions} value={value} onChange={setValue} />
      </FormField>
      <Text role="status" tone="muted">
        选中路径：{JSON.stringify(value)}
      </Text>
    </Form>
  );
}
```

展开代码

### 搜索

`showSearch` 按完整路径展示匹配结果。搜索只覆盖已提供或已加载的选项，不会自动请求远程数据。


地区

选择地区

search.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/search.tsx"
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京' },
      { value: 'suzhou', label: '苏州' },
    ],
  },
];

export function CascaderSearch() {
  return (
    <Form layout="vertical">
      <FormField label="地区">
        <Cascader options={regions} placeholder="选择地区" showSearch />
      </FormField>
    </Form>
  );
}
```

展开代码

### 多选

`multiple` 模式的 `value` 为 `string[][]`，每项是一条完整路径。再次选择同一路径会取消选择，选择后浮层保持打开。


地区

浙江 / 杭州江苏 / 南京

选中路径数：2

multiple.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/multiple.tsx"
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京' },
      { value: 'suzhou', label: '苏州' },
    ],
  },
];

export function CascaderMultiple() {
  const [value, setValue] = useState<string[][]>([
    ['zhejiang', 'hangzhou'],
    ['jiangsu', 'nanjing'],
  ]);
  return (
    <Form layout="vertical">
      <FormField label="地区">
        <Cascader multiple options={regions} value={value} onChange={setValue} />
      </FormField>
      <Text role="status" tone="muted">
        选中路径数：{value.length}
      </Text>
    </Form>
  );
}
```

展开代码

### 单行多选

`tagWrap={false}` 将标签保留在一行，超出空间的选项折叠为 `+N`；也可通过 `maxTagCount` 限制可见标签数。打开浮层可查看和修改全部选择。


产品团队

产品团队 / 产品体验设计产品团队 / 前端开发产品团队 / 移动端开发+3

single-line.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/single-line.tsx"
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [
  {
    value: 'product',
    label: '产品团队',
    children: [
      { value: 'design', label: '产品体验设计' },
      { value: 'web', label: '前端开发' },
      { value: 'mobile', label: '移动端开发' },
    ],
  },
];

export function CascaderSingleLine() {
  return (
    <Form layout="vertical">
      <FormField label="产品团队">
        <Cascader
          multiple
          tagWrap={false}
          options={options}
          defaultValue={[
            ['product', 'design'],
            ['product', 'web'],
            ['product', 'mobile'],
          ]}
        />
      </FormField>
    </Form>
  );
}
```

展开代码

### 禁用与只读

`disabled` 禁止交互；`readOnly` 保留触发控件的聚焦能力，但不允许打开浮层、清除或修改值。


禁用

设计 / 界面设计

只读

设计 / 界面设计

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/states.tsx"
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [
  {
    value: 'design',
    label: '设计',
    children: [
      { value: 'interface', label: '界面设计' },
      { value: 'brand', label: '品牌设计' },
    ],
  },
  {
    value: 'engineering',
    label: '工程',
    children: [
      { value: 'frontend', label: '前端开发' },
      { value: 'backend', label: '后端开发' },
    ],
  },
  { value: 'archived', label: '归档分类', disabled: true },
];

const value = ['design', 'interface'];

export function CascaderStates() {
  return (
    <Form layout="vertical">
      <FormField label="禁用">
        <Cascader options={options} value={value} disabled />
      </FormField>
      <FormField label="只读">
        <Cascader options={options} value={value} readOnly />
      </FormField>
    </Form>
  );
}
```

展开代码

### 选择中间层

[](#)
`changeOnSelect` 允许提交中间层级的路径。选择仍有子项的节点时，浮层保持打开，可以继续向下选择。


地区

请选择

选中路径：[]

intermediate.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/intermediate.tsx"
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京' },
      { value: 'suzhou', label: '苏州' },
    ],
  },
];

export function CascaderIntermediate() {
  const [value, setValue] = useState<string[]>([]);
  return (
    <Form layout="vertical">
      <FormField label="地区">
        <Cascader changeOnSelect options={regions} value={value} onChange={setValue} />
      </FormField>
      <Text role="status" tone="muted">
        选中路径：{JSON.stringify(value)}
      </Text>
    </Form>
  );
}
```

展开代码

### 异步加载

为尚无 `children` 的节点设置 `isLeaf={false}`，展开时由 `loadData` 返回子选项。保持 `options` 和 `loadData` 的引用稳定，节点值在整棵树中唯一。

请求应响应 `AbortSignal`：更换选项、加载函数、`cacheKey` 或卸载时会取消旧请求，关闭浮层不会取消。通过 `onLoadError` 提供失败反馈，再次展开节点可重试。


远程分类

展开分类

lazy.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/lazy.tsx"
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [{ value: 'remote', label: '远程分类', isLeaf: false }];

function waitForChildren(signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    if (signal.aborted) {
      reject(new DOMException('Aborted', 'AbortError'));
      return;
    }
    const onAbort = () => {
      clearTimeout(timer);
      reject(new DOMException('Aborted', 'AbortError'));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener('abort', onAbort);
      resolve();
    }, 400);
    signal.addEventListener('abort', onAbort, { once: true });
  });
}

async function loadData(option: CascaderOption, signal: AbortSignal): Promise<CascaderOption[]> {
  await waitForChildren(signal);
  return [{ value: `${option.value}-child`, label: '已加载项', isLeaf: true }];
}

export function CascaderLazy() {
  return (
    <Form layout="vertical">
      <FormField label="远程分类">
        <Cascader options={options} loadData={loadData} placeholder="展开分类" />
      </FormField>
    </Form>
  );
}
```

展开代码

### 刷新缓存

数据版本变化时更新 `cacheKey`，清空已加载的子选项并取消旧请求。此例保持选项和加载函数不变；刷新后重新展开分类，加载新版本。


远程分类

展开分类

刷新数据

缓存版本：v1; 加载版本：未加载

cache.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/cache.tsx"
import { Button, Cascader, type CascaderOption, Flex, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useCallback, useRef, useState } from 'react';

const options: CascaderOption[] = [{ value: 'remote', label: '远程分类', isLeaf: false }];

function waitForChildren(signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    if (signal.aborted) {
      reject(new DOMException('Aborted', 'AbortError'));
      return;
    }
    const onAbort = () => {
      clearTimeout(timer);
      reject(new DOMException('Aborted', 'AbortError'));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener('abort', onAbort);
      resolve();
    }, 400);
    signal.addEventListener('abort', onAbort, { once: true });
  });
}

export function CascaderCache() {
  const [version, setVersion] = useState(1);
  const [loadedVersion, setLoadedVersion] = useState<number | null>(null);
  const versionRef = useRef(1);
  const loadData = useCallback(async (option: CascaderOption, signal: AbortSignal) => {
    const requestVersion = versionRef.current;
    await waitForChildren(signal);
    setLoadedVersion(requestVersion);
    return [{ value: `${option.value}-child`, label: `已加载项 v${requestVersion}`, isLeaf: true }];
  }, []);

  return (
    <Form layout="vertical">
      <FormField label="远程分类">
        <Cascader options={options} loadData={loadData} cacheKey={version} placeholder="展开分类" />
      </FormField>
      <Flex align="start">
        <Button
          onClick={() => {
            versionRef.current += 1;
            setVersion(versionRef.current);
            setLoadedVersion(null);
          }}
        >
          刷新数据
        </Button>
      </Flex>
      <Text role="status" tone="muted">
        缓存版本：v{version}; 加载版本：{loadedVersion === null ? '未加载' : `v${loadedVersion}`}
      </Text>
    </Form>
  );
}
```

展开代码

### 浮层宽度

`popupWidth="auto"` 按内容定宽，`popupMaxWidth` 限制最大宽度；省略时默认与触发控件等宽。其他浮层配置见[共享浮层参数](https://ifhover.github.io/leaf-ui/api/popup-options.md)。


地区

选择地区

popup.tsx

复制代码

```tsx lineNumbers file="../../src/examples/cascader/popup.tsx"
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: '浙江',
    children: [
      { value: 'hangzhou', label: '杭州' },
      { value: 'ningbo', label: '宁波' },
    ],
  },
  {
    value: 'jiangsu',
    label: '江苏',
    children: [
      { value: 'nanjing', label: '南京' },
      { value: 'suzhou', label: '苏州' },
    ],
  },
];

export function CascaderPopup() {
  return (
    <Form layout="vertical">
      <FormField label="地区">
        <Cascader options={regions} placeholder="选择地区" popupWidth="auto" popupMaxWidth={320} />
      </FormField>
    </Form>
  );
}
```

展开代码

设置 `name` 后，以 JSON 数组字符串提交路径，空值提交为空字符串。非受控值支持表单重置，受控值需同步重置应用状态；标签和错误信息见 [Form](https://ifhover.github.io/leaf-ui/components/form.md)。内置文案配置见 [ConfigProvider](https://ifhover.github.io/leaf-ui/components/config-provider.md)。


## API

### Cascader API

其余原生 `button` 属性和 `aria-*` 透传至触发按钮；`className` / `style` 作用于外层容器。

| 属性                  | 类型                                                                                                                                                                                   | 默认值         | 说明                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------- |
| `options`           | `readonly `[`CascaderOption`](#cascaderoption)`[]`                                                                                                                                   | 必填          | 层级选项列表                                                      |
| `value`             | `readonly string[] \| readonly (readonly string[])[]`                                                                                                                                | —           | 受控路径；省略时使用内部非受控值。                                           |
| `defaultValue`      | `readonly string[] \| readonly (readonly string[])[]`                                                                                                                                | `[]`        | 非受控模式的初始路径；支持表单重置。                                          |
| `onChange`          | `((value: string[], selectedOptions: `[`CascaderOption`](#cascaderoption)`[]) => void) \| ((value: string[][], selectedOptions: `[`CascaderOption`](#cascaderoption)`[][]) => void)` | —           | 单选返回路径和对应选项，多选返回路径数组和对应选项数组；选择、取消或清除时触发，清除的两参数均为空数组。        |
| `multiple`          | `false \| true`                                                                                                                                                                      | `false`     | 启用多选；value 和回调的类型随之变化。                                      |
| `placeholder`       | `string`                                                                                                                                                                             | `'请选择'`     | 未选择时的提示文字                                                   |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                                               | `'md'`      | 选择器尺寸                                                       |
| `status`            | `'error' \| 'warning'`                                                                                                                                                               | —           | 校验状态                                                        |
| `disabled`          | `boolean`                                                                                                                                                                            | `false`     | 禁用交互。                                                       |
| `readOnly`          | `boolean`                                                                                                                                                                            | —           | 锁定业务值，禁止输入、选择、清除和删除。                                        |
| `allowClear`        | `boolean`                                                                                                                                                                            | `true`      | 清除后返回两个空数组                                                  |
| `showSearch`        | `boolean`                                                                                                                                                                            | —           | 启用搜索输入。                                                     |
| `changeOnSelect`    | `boolean`                                                                                                                                                                            | —           | 允许选择中间层级。                                                   |
| `tagWrap`           | `boolean`                                                                                                                                                                            | `true`      | 允许多选标签换行；false 单行显示并自动折叠溢出项。                                |
| `maxTagCount`       | `number \| 'responsive'`                                                                                                                                                             | —           | 最多展示的标签数；responsive 根据可用宽度自动折叠。                             |
| `displayRender`     | `(labels: ReactNode[], selectedOptions: `[`CascaderOption`](#cascaderoption)`[]) => ReactNode`                                                                                       | —           | 自定义每条已选路径的显示内容，参数为该路径的标签和选项。                                |
| `optionRender`      | `(option: `[`CascaderOption`](#cascaderoption)`) => ReactNode`                                                                                                                       | —           | 自定义选项内容。                                                    |
| `loadData`          | `(option: `[`CascaderOption`](#cascaderoption)`, signal: AbortSignal) => Promise<readonly `[`CascaderOption`](#cascaderoption)`[]>`                                                  | —           | 展开 isLeaf 为 false 且未提供 children 的节点时请求子项；使用 signal 处理取消。    |
| `onLoadError`       | `(error: unknown, option: `[`CascaderOption`](#cascaderoption)`) => void`                                                                                                            | —           | 加载失败时调用，可展示重试提示。                                            |
| `cacheKey`          | `string \| number`                                                                                                                                                                   | —           | 数据版本改变时清空懒加载缓存，并取消旧请求。                                      |
| `open`              | `boolean`                                                                                                                                                                            | —           | 受控的展开状态。                                                    |
| `defaultOpen`       | `boolean`                                                                                                                                                                            | `false`     | 非受控模式的初始展开状态。                                               |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                                            | —           | 面板展开或收起                                                     |
| `popupWidth`        | `number \| string`                                                                                                                                                                   | `'trigger'` | 浮层宽度；trigger 与触发控件等宽，auto 按内容定宽（可比控件窄），数字为固定像素值，也支持 CSS 长度。 |
| `popupMaxWidth`     | `number \| string`                                                                                                                                                                   | —           | 可选的浮层最大宽度；未设置时不额外限制，仍受可视区域限制。                               |
| `name`              | `string`                                                                                                                                                                             | —           | 原生 FormData 的字段名；非空值提交 JSON 路径，空值提交空字符串。                    |
| `form`              | `string`                                                                                                                                                                             | —           | 关联的原生表单 ID。                                                 |
| `required`          | `boolean`                                                                                                                                                                            | `false`     | 要求整体值非空，复合控件只校验一次。                                          |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`                 | —           | 浮层相对触发控件的位置。                                                |
| `popupClassName`    | `string`                                                                                                                                                                             | —           | 浮层的自定义类名。                                                   |
| `popupStyle`        | `CSSProperties`                                                                                                                                                                      | —           | 浮层的自定义样式。                                                   |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                                      | —           | 包装或补充面板内容，保留传入的内容以维持交互。                                     |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                                  | —           | 返回浮层的挂载容器，也可返回 ShadowRoot。                                  |
| `ref`               | `Ref<HTMLButtonElement>`                                                                                                                                                             | —           | 触发按钮引用                                                      |

### CascaderOption

级联选项的数据结构，子选项通过 `children` 组织。

| 属性            | 类型                                                 | 默认值     | 说明                              |
| ------------- | -------------------------------------------------- | ------- | ------------------------------- |
| `value`       | `string`                                           | 必填      | 选项值；静态数据同层唯一，异步加载的节点须全树唯一以区分缓存。 |
| `label`       | `ReactNode`                                        | 必填      | 选项的显示内容。                        |
| `searchLabel` | `string`                                           | —       | 复杂 label 的搜索纯文本。                |
| `isLeaf`      | `boolean`                                          | —       | 明确指定是否为叶子节点；配合懒加载使用。            |
| `disabled`    | `boolean`                                          | `false` | 禁用该选项及其所有子级。                    |
| `children`    | `readonly `[`CascaderOption`](#cascaderoption)`[]` | —       | 子选项列表。                          |

### CascaderFieldNames

通过 `mapCascaderOptions(records, fields)` 将业务数据转换为 `CascaderOption[]`，再传给 `options`。`CascaderFieldNames` 描述映射字段，不是 `Cascader` 的属性。

```ts
import { mapCascaderOptions } from '@ifhover/leaf-ui';

const records = [{ id: 'design', name: '设计', nodes: [{ id: 'interface', name: '界面设计' }] }];
const options = mapCascaderOptions(records, {
  value: 'id',
  label: 'name',
  children: 'nodes',
});
```

| 属性         | 类型       | 默认值 | 说明               |
| ---------- | -------- | --- | ---------------- |
| `value`    | `string` | —   | 选项值在业务对象中的字段名。   |
| `label`    | `string` | —   | 显示文字在业务对象中的字段名。  |
| `children` | `string` | —   | 子节点数组在业务对象中的字段名。 |
| `disabled` | `string` | —   | 禁用状态在业务对象中的字段名。  |
| `isLeaf`   | `string` | —   | 叶子标记在业务对象中的字段名。  |
