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

# Cascader

数据录入`@rockshin/tao-ui`

[API](#api)

通过搜索、多选或独立面板，从层级选项中选择完整路径。

每个示例都可以独立复制运行。带设备预览的示例可通过工具栏切换桌面与手机宽度。

尺寸支持 `small`、`medium`、`large`；兼容别名 `middle` 与 `medium` 使用相同尺寸。

窄于 576px 时自动使用底部抽屉；可用 `mobile` 强制选择展示方式，`mobileTitle` 指定抽屉标题。手机端单选即时提交，多选点击 Done 后提交，关闭则取消本次修改。桌面端 hover 时清除按钮替换箭头，触屏始终显示清除按钮。

## 示例


### 选择完整路径
选中值按顺序包含路径中的各级 value。
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'china',
        label: 'China',
        children: [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ],
      },
      {
        value: 'japan',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'germany',
        label: 'Germany',
        children: [{ value: 'berlin', label: 'Berlin' }],
      },
    ],
  },
];
export default function BasicCascader() {
  return (
    <Cascader
      aria-label="Location"
      options={options}
      defaultValue={['asia', 'china', 'shanghai']}
      allowClear
      style={{ width: '100%' }}
    />
  );
}
```

### 受控路径与展示
displayRender 可以缩短展示文字，同时在状态中保留完整路径。
```tsx preview
import { useState } from 'react';
import { Cascader } from '@rockshin/tao-ui';
const options = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'china',
        label: 'China',
        children: [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ],
      },
      {
        value: 'japan',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'germany',
        label: 'Germany',
        children: [{ value: 'berlin', label: 'Berlin' }],
      },
    ],
  },
];
export default function ControlledLocation() {
  const [value, setValue] = useState<string[]>(['asia', 'japan', 'tokyo']);
  return (
    <div>
      <Cascader
        multiple={false}
        options={options}
        value={value}
        onChange={setValue}
        displayRender={(labels) => labels.at(-1)}
        style={{ width: '100%' }}
      />
      <p>{value.join(' / ')}</p>
    </div>
  );
}
```

### 选择多条路径
多选模式提供联动复选框；SHOW\_CHILD 展示已选叶子路径。
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'china',
        label: 'China',
        children: [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ],
      },
      {
        value: 'japan',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'germany',
        label: 'Germany',
        children: [{ value: 'berlin', label: 'Berlin' }],
      },
    ],
  },
];
export default function MultipleLocations() {
  return (
    <Cascader
      options={options}
      multiple
      showCheckedStrategy={Cascader.SHOW_CHILD}
      defaultValue={[['asia', 'china', 'shanghai']]}
      maxTagCount="responsive"
      placeholder="Choose locations"
      style={{ width: '100%' }}
    />
  );
}
```

### 搜索路径中的各级文字
过滤函数检查整条路径的标签，选择搜索结果后返回完整路径。
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'china',
        label: 'China',
        children: [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ],
      },
      {
        value: 'japan',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'germany',
        label: 'Germany',
        children: [{ value: 'berlin', label: 'Berlin' }],
      },
    ],
  },
];
export default function SearchLocations() {
  return (
    <Cascader
      options={options}
      showSearch={{
        filter: (input, path) =>
          path.some((option) =>
            String(option.label).toLowerCase().includes(input.toLowerCase()),
          ),
      }}
      placeholder="Search country or city"
      style={{ width: '100%' }}
    />
  );
}
```

### 选择中间层级
changeOnSelect 允许选择中间路径；本例通过鼠标悬停展开下一列。
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'china',
        label: 'China',
        children: [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ],
      },
      {
        value: 'japan',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'germany',
        label: 'Germany',
        children: [{ value: 'berlin', label: 'Berlin' }],
      },
    ],
  },
];
export default function IntermediateLocation() {
  return (
    <Cascader
      options={options}
      changeOnSelect
      expandTrigger="hover"
      placeholder="Choose a continent, country or city"
      style={{ width: '100%' }}
    />
  );
}
```

### 映射自定义字段
通过字段映射直接使用已有业务数据。
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
export default function RegionFields() {
  return (
    <Cascader
      fieldNames={{ label: 'name', value: 'code', children: 'regions' }}
      options={[
        {
          code: 'cn',
          name: 'China',
          regions: [
            { code: 'sh', name: 'Shanghai' },
            { code: 'hz', name: 'Hangzhou' },
          ],
        },
      ]}
      placeholder="Choose a region"
      style={{ width: '100%' }}
    />
  );
}
```

### 按需加载下一列
此处用本地延迟模拟请求。未加载的父节点设置 isLeaf:false，加载后更新 options。
```tsx preview
import { useState } from 'react';
import { Cascader, type DefaultOptionType } from '@rockshin/tao-ui';
export default function AsyncLocations() {
  const [options, setOptions] = useState<DefaultOptionType[]>([
    { value: 'china', label: 'China', isLeaf: false },
  ]);
  return (
    <Cascader
      options={options}
      changeOnSelect
      loadData={async (selected) => {
        const target = selected.at(-1)!;
        target.loading = true;
        setOptions([...options]);
        await new Promise((resolve) => setTimeout(resolve, 500));
        target.loading = false;
        target.children = [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ];
        setOptions([...options]);
      }}
      placeholder="Load cities"
      style={{ width: '100%' }}
    />
  );
}
```

### 独立面板
Cascader.Panel 直接展示级联列，不使用输入触发器。
```tsx preview
import { Cascader } from '@rockshin/tao-ui';
const options = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'china',
        label: 'China',
        children: [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ],
      },
      {
        value: 'japan',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'germany',
        label: 'Germany',
        children: [{ value: 'berlin', label: 'Berlin' }],
      },
    ],
  },
];
export default function LocationPanel() {
  return (
    <Cascader.Panel
      options={options}
      defaultValue={['asia', 'china', 'shanghai']}
    />
  );
}
```

### 手机底部抽屉
在手机模式下通过底部抽屉选择三级路径，级联列超出可用宽度时可以横向滚动。
单选在选中路径时立即生效。使用 `multiple` 时，抽屉里的更改在点击「完成」后才应用。从 [0.0.49](https://rickyshin93.github.io/tao-ui/zh/guide/changelog.md) 起，组件会跳过确认前被移除或禁用的新选路径，保留此前已经提交且用户仍保留选中的路径。
```tsx preview="iframe-follow"
import { Cascader } from '@rockshin/tao-ui';
const options = [
  {
    value: 'asia',
    label: 'Asia',
    children: [
      {
        value: 'china',
        label: 'China',
        children: [
          { value: 'shanghai', label: 'Shanghai' },
          { value: 'hangzhou', label: 'Hangzhou' },
        ],
      },
      {
        value: 'japan',
        label: 'Japan',
        children: [{ value: 'tokyo', label: 'Tokyo' }],
      },
    ],
  },
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'germany',
        label: 'Germany',
        children: [{ value: 'berlin', label: 'Berlin' }],
      },
    ],
  },
];
export default function MobileLocation() {
  return (
    <div style={{ padding: 16 }}>
      <h3>Delivery location</h3>
      <Cascader
        aria-label="Delivery location"
        mobileTitle="Delivery location"
        size="middle"
        options={options}
        showSearch
        allowClear
        variant="filled"
        style={{ width: '100%' }}
      />
    </div>
  );
}
```

## API


### [#](#cascaderpanel)CascaderPanel



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |



### [#](#cascader)Cascader



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| mobile | Use a bottom drawer. Automatically enabled below 576px. | `boolean | undefined` | `-` |
| mobileTitle | Drawer title; defaults to the field label, then localized selection text. | `ReactNode` | `-` |

