---
nav: 组件
title: Cascader
subtitle: 级联选择
group: 表单组件
---

## 介绍

用于在多层级数据中进行选择，常用于省市区、组织架构选择。

## 引入

```ts
import { Cascader } from 'sard'
```

## 代码演示

### 基础使用

通过 `v-model` 绑定当前值，通过 `options` 配置选项数据。

@code('${DEMO_PATH}/cascader/demo/Basic.vue')

### 选择即改变

设置 `change-on-select` 属性，允许只选中父级选项。

@code('${DEMO_PATH}/cascader/demo/ChangeOnSelect.vue')

### 异步加载

通过监听 `@select` 事件，获取当前选中的选项，将异步获取的数据作为 `children` 属性值， 再把组件的 `options` 更新一下，使组件重新渲染。如果选项的 `children` 是需要用户点击时再通过接口获取的， 此选项的 `children` 需初始化为空数组。

@code('${DEMO_PATH}/cascader/demo/Async.vue')

### 自定义面板上方内容

使用 `top` 插槽可以在面板顶部展示当前面板的一些信息。

@code('${DEMO_PATH}/cascader/demo/OptionTop.vue')

### 禁选选项

禁用的选项不可点击。

@code('${DEMO_PATH}/cascader/demo/Disabled.vue')

## API

### CascaderProps

| 属性                              | 描述                      | 类型                               | 默认值           |
| --------------------------------- | ------------------------- | ---------------------------------- | ---------------- |
| root-class                        | 组件根元素类名            | string                             | -                |
| root-style                        | 组件根元素样式            | StyleValue                         | -                |
| model-value (v-model)             | 选中项的值                | string \| number                   | -                |
| options                           | 可选项数据源              | CascaderOption[]                   | []               |
| field-keys                        | 自定义 `options` 中的字段 | CascaderFieldKeys                  | defaultFieldKeys |
| hint-text                         | 未选中时的提示文案        | string                             | '请选择'         |
| label-render                      | 自定义可选项渲染          | (option: CascaderOption) => string | -                |
| change-on-select <sup>1.14+</sup> | 点击每级选项都会触发变化  | boolean                            | false            |

### CascaderSlots

| 插槽 | 描述               | 属性                 |
| ---- | ------------------ | -------------------- |
| top  | 自定义面板上方内容 | { tabIndex: number } |

### CascaderEmits

| 事件                     | 描述                   | 类型                                                                 |
| ------------------------ | ---------------------- | -------------------------------------------------------------------- |
| update:model-value       | 全部选项选择完成后触发 | (value: string \| number, selectedOptions: CascaderOption[]) => void |
| change <sup>1.9.2+</sup> | 全部选项选择完成后触发 | (value: string \| number, selectedOptions: CascaderOption[]) => void |
| select                   | 选中某一项时触发       | (option: CascaderOption, tabIndex: number) => void                   |

### CascaderOption

```ts
interface CascaderOption {
  label?: string
  value?: string | number
  disabled?: boolean
  children?: CascaderOption[]
  [key: PropertyKey]: any
}
```

### CascaderFieldKeys

```ts
interface CascaderFieldKeys {
  label?: string
  value?: string
  disabled?: string
  children?: string
}
```

### defaultFieldKeys

```ts
const defaultFieldKeys: CascaderFieldKeys = {
  label: 'label',
  value: 'value',
  disabled: 'disabled',
  children: 'children',
}
```

## 主题定制

### CSS 变量

@code('./variables.scss#variables')