# cascader (w-cascader)

- **Import**: `WCascader` from `win-design-next`
- **Tag**: `<w-cascader>`
- **说明**: Cascader 级联选择器
- **分类**: data-entry
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/cascader.md`

## API

## Cascader API

### Attributes

| 属性名                           | 说明                                                                                                                                                           | 类型                                                                                                                                                                        | 默认值            |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| model-value / v-model            | 选中项绑定值                                                                                                                                                   | ^[string]/^[number]/^[object]`string[] \| number[] \| any`                                                                                                                  | —                 |
| options                          | 选项的数据源， `value` 和 `label` 可以通过 `CascaderProps` 自定义.                                                                                             | ^[object]`Record[]`                                                                                                                                                         | —                 |
| props                            | 配置选项, 请参阅下面 `CascaderProps` 表。                                                                                                                      | ^[object]`CascaderProps`                                                                                                                                                    | —                 |
| size                             | 尺寸                                                                                                                                                           | ^[enum]`'large' \| 'default' \| 'small'`                                                                                                                                    | —                 |
| placeholder                      | 输入框占位文本                                                                                                                                                 | ^[string]                                                                                                                                                                   | —                 |
| disabled                         | 是否禁用                                                                                                                                                       | ^[boolean]                                                                                                                                                                  | —                 |
| clearable                        | 是否支持清空选项                                                                                                                                               | ^[boolean]                                                                                                                                                                  | —                 |
| show-all-levels                  | 输入框中是否显示选中值的完整路径                                                                                                                               | ^[boolean]                                                                                                                                                                  | true              |
| collapse-tags                    | 多选模式下是否折叠 Tag                                                                                                                                         | ^[boolean]                                                                                                                                                                  | —                 |
| collapse-tags-tooltip            | 当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，`collapse-tags`属性必须设定为 true                                                        | ^[boolean]                                                                                                                                                                  | true              |
| separator                        | 用于分隔选项的字符                                                                                                                                             | ^[string]                                                                                                                                                                   | ' / '             |
| filterable                       | 该选项是否可以被搜索                                                                                                                                           | ^[boolean]                                                                                                                                                                  | —                 |
| filter-method                    | 自定义搜索逻辑，第一个参数是`node`，第二个参数是`keyword`，返回的布尔值表示是否保留该选项                                                                      | ^[Function]`(node: CascaderNode, keyword: string) => boolean`                                                                                                               | —                 |
| debounce                         | 搜索关键词正在输入时的去抖延迟，单位为毫秒                                                                                                                     | ^[number]                                                                                                                                                                   | 300               |
| before-filter                    | 过滤函数调用前，所要调用的钩子函数，该函数接收要过滤的值作为参数。 如果该函数的返回值是 `false` 或者是一个被拒绝的 `Promise`，那么接下来的过滤逻辑便不会执行。 | ^[Function]`(value: string) => boolean`                                                                                                                                     | —                 |
| popper-class                     | 弹出内容的自定义类名                                                                                                                                           | ^[string]                                                                                                                                                                   | ''                |
| teleported                       | 弹层是否使用 teleport                                                                                                                                          | ^[boolean]                                                                                                                                                                  | true              |
| tag-type                         | 标签类型                                                                                                                                                       | ^[enum]`'success' \| 'info' \| 'warning' \| 'error' \| 'danger'`                                                                                                            | info              |
| tag-effect                       | tag effect                                                                                                                                                     | ^[enum]`'light' \| 'dark' \| 'plain'`                                                                                                                                       | light             |
| validate-event                   | 输入时是否触发表单的校验                                                                                                                                       | ^[boolean]                                                                                                                                                                  | true              |
| max-collapse-tags                | 需要显示的 Tag 的最大数量 只有当 `collapse-tags` 设置为 true 时才会生效。                                                                                      | ^[number]                                                                                                                                                                   | 1                 |
| empty-values                     | 组件的空值配置 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations)                                                            | ^[array]                                                                                                                                                                    | —                 |
| value-on-clear                   | 清空选项的值 [参考 config-provider](/zh-CN/component/config-provider#empty-values-configurations)                                                              | ^[string] / ^[number] / ^[boolean] / ^[Function]                                                                                                                            | —                 |
| persistent                       | 当下拉框未被激活并且`persistent`设置为`false`，下拉框容器会被删除。                                                                                            | ^[boolean]                                                                                                                                                                  | true              |
| fallback-placements              | Tooltip 可用的 positions 请查看[popper.js 文档](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements)                                              | ^[arrary]`Placement[]`                                                                                                                                                      | —                 |
| placement                        | 下拉框出现的位置                                                                                                                                               | ^[enum]`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | bottom-start      |
| clear-icon ^(1.1.12)             | 自定义清除图标                                                                                                                                                 | ^[string] / ^[object]`Component`                                                                                                                                            | CircleCloseFilled |
| max-collapse-tags-tooltip-height | 最大高度                                                                                                                                                       | ^[string] / ^[number]                                                                                                                                                       | —                 |
| show-checked-strategy            | 多选模式下已选节点的展示策略。 当你想让显示更简洁时，使用 parent。 当你想显示每个子项时，使用 child。                                                          | ^[enum]`'parent' \| 'child'`                                                                                                                                                | child             |

### Events

| 事件名         | 说明                                     | 类型                                                        |
| -------------- | ---------------------------------------- | ----------------------------------------------------------- |
| change         | 当绑定值变化时触发的事件                 | ^[Function]`(value: CascaderValue) => void`                 |
| expand-change  | 当展开节点发生变化时触发                 | ^[Function]`(value: CascaderValue) => void`                 |
| blur           | 当失去焦点时触发                         | ^[Function]`(event: FocusEvent) => void`                    |
| focus          | 当获得焦点时触发                         | ^[Function]`(event: FocusEvent) => void`                    |
| clear          | 可清空的单选模式下用户点击清空按钮时触发 | ^[Function]`() => void`                                     |
| visible-change | 下拉框出现/隐藏时触发                    | ^[Function]`(value: boolean) => void`                       |
| remove-tag     | 在多选模式下，移除 Tag 时触发            | ^[Function]`(value: CascaderNode['valueByOption']) => void` |

### Slots

| 插槽名  | 说明                                                     | 作用域                              |
| ------- | -------------------------------------------------------- | ----------------------------------- |
| default | 自定义备选项的节点内容，分别为当前节点的 Node 对象和数据 | ^[object]`{ node: any, data: any }` |
| empty   | 无匹配选项时的内容                                       | —                                   |
| prefix  | 输入框头部内容                                           | —                                   |

### Exposes

| 属性名              | 说明                                                                            | 类型                                                            |
| ------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| getCheckedNodes     | 获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 `false` | ^[Function]`(leafOnly: boolean) => CascaderNode[] \| undefined` |
| cascaderPanelRef    | cascader 面板的 ref                                                             | ^[object]`ComputedRef`                                          |
| togglePopperVisible | 切换 popper 可见状态                                                            | ^[Function]`(visible?: boolean) => void`                        |
| contentRef          | cascader 内容的 ref                                                             | ^[object]`ComputedRef`                                          |
| presentText         | 选中的内容文本                                                                  | ^[object]`ComputedRef`                                          |
