zent
Version:
一套前端设计语言和基于React的实现
96 lines (76 loc) • 10.3 kB
Markdown
---
title: Cascader
subtitle: 级联选择
path: component/cascader
group: 信息录入
---
## Cascader 级联选择
可支持多级面板选取单个或多个值的选择器，最终录入对应值
### API
`Cascader` 包含 `MenuCascader` 及 `TabsCascader`，它们大部分 API 是共用的。
### 共用的 API
| 参数 | 说明 | 类型 | 是否必填 | 默认值 | 备选值 |
| ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------ |
| value | 级联的选中值 | `CascaderValue[]` | 否 | `[]` | |
| maxLine | 数据显示几行 | `number` | 否 | `null` | |
| lineHeight | 每行的行高，乘以maxLine即为显示面板的高度，用于解决自定义renderValue时高度不适配 | `number` | 否 | `22` | |
| options | 可选项数据源 | `ICascaderItem[]` | 是 | `[]` | |
| onChange | 选择完成后的回调 | `(value: CascaderValue[], selectedOptions: ICascaderItem[], meta: ICascaderChangeMeta) => void` | 是 | - | |
| loadOptions | 动态加载级联的数据 | `(selectedOptions: ICascaderItem[], meta: ICascaderLoadMeta) => Promise<void>` | 否 | - | |
| changeOnSelect | 是否选择即时触发改变 | `boolean` | 否 | `false` | `true` |
| placeholder | 输入框占位文本 | `string` | 否 | `请选择` | |
| className | 自定义额外类名 | `string` | 否 | | |
| popupClassName | popover 自定义类名 | `string` | 否 | | |
| disabled | 是否禁用 | `boolean` | 否 | `false` | `true` |
| clearable | 显示清除按钮 | `boolean` | 否 | `false` | `true` |
| visible | 和 `onVisibleChange` 一起使用时 `Cascader` 的打开关闭状态完全由外部控制 | `boolean` | 否 | | |
| onVisibleChange | 配合 `visible` 一起使用 | `(visible: boolean) => void` | 否 | | |
| renderValue | 渲染选中中的一个选项值 | `(selectedOptions: ICascaderItem[]) => string` | 否 | | |
| renderItemContent | 自定义渲染选项内容 | `(node: ICascaderItem) => ReactNode` | 否 | `node.label` | |
| getItemTooltip | 自定义选项的 tooltip | `(node: ICascaderItem) => string` | 否 | `node.label` | |
| renderList | 自定义渲染选项列表 | `(nodes: ICascaderItem[], renderItem: (node: ICascaderItem, style: CSSProperties) => ReactNode) => ReactNode` | 否 | | |
- 对于 `MenuCascader` `changeOnSelect` 仅在单选模式且子菜单展开方式为 `click` 时才生效。
#### ICascaderItem
```ts
interface ICascaderItem {
value: string | number;
label: string;
children?: ICascaderItem[];
disabled?: boolean;
loadChildrenOnExpand?: boolean; // 展开下一级时触发加载数据
loadChildrenOnScroll?: boolean; // 滚动时触发加载数据
}
```
#### Meta 参数
`ICascaderChangeMeta` 和 `ICascaderLoadMeta` 用于区分触发 `onChange` 和 `loadOptions` 的场景，使用时根据不同触发场景坑需要做不同逻辑处理。例如 `loadOptions` 可能是由于展开下一级或者滚动时触发的。
### MenuCascader
| 参数 | 说明 | 类型 | 是否必填 | 默认值 | 备选值 |
| -------------------- | -------------------------------------- | ------------------------------------------------------- | -------- | ------- | ------- |
| multiple | 是否支持多选 | `boolean` | 否 | `false` | `true` |
| multipleType | 多选类型 | `normal` `checkbox` | 否 | `normal` | `checkbox` |
| expandTrigger | 次级菜单的展开方式 | `string` | 否 | `click` | `hover` |
| scrollable | 是否支持滚动加载 | `boolean` | 否 | `false` | `true` |
| loadChildrenOnScroll | 第一级数据是否还有更多数据 | `boolean` | 否 | `false` | `true` |
| searchable | 是否显示搜索框 | `boolean` | 否 | `false` | `true` |
| async | 是否异步搜索 | `boolean` | 否 | `false` | `true` |
| asyncFilter | 根据关键词异步搜索 | `(keyword: string) => Promise<Array<ICascaderItem[]>>` | 否 | - | |
| filter | 根据关键词进行过滤 | `(keyword: string, path: ICascaderItem[]) => boolean` | 否 | - | |
| highlight | 根据关键词高亮每一项 | `(keyword: string, path: ICascaderItem[]) => ReactNode` | 否 | - | |
| limit | 搜索结果展示数量 | `number` | 否 | `50` | |
| renderTags | 自定义标签列表整体的展示 | `(props: ICascaderTagsProps) => ReactNode` | 否 | | |
| simplifySelection | 多选时合并展示同级节点，参考下面的说明 | `boolean` | `否` | `false` | `true` |
| simplifySelectionMode| 多选时合并展示同级节点时，是否排除disabled项的干扰 | `string` | `否` | `excludeDisabled` | `includeDisabled` |
- 当 `multiple` 为 `true` 时，`onChange` 中的 `value` 及 `selectedOptions` 为二维数组
- `renderTags` 仅当多选模式下有效
- 组件参数 `scrollable` 与节点的 `loadChildrenOnScroll` 属性组合可判断它的子节点是否需要滚动加载更多数据；第一个层级由于无父节点，使用 `props` 上的 `loadChildrenOnScroll` 参数
- `simplifySelection` 仅当 `multiple` 为 `true` 时生效。举例来说，开启后当四川省下所有的市都被选中时，输入框中仅展示四川省，不会展开各个具体的市。另外，多选模式下 `onChange` 的 `meta` 参数中会多一个 `simplify` 方法，可以用来合并选中的选项。
### TabsCascader
| 参数 | 说明 | 类型 | 是否必填 | 默认值 | 备选值 |
| ----- | ---------------------- | ------------- | -------- | ------ | ------ |
| title | 弹层中每一级的标题文案 | `ReactNode[]` | 否 | `[]` | |
### Options 处理函数
`Cascader` 实现了部分常用的操作 `options` 的函数，这些函数没有在 `zent` 里直接导出，如需使用需要从 `zent/es/cascader/public-options-fns` 引入。函数具体说明文档参考各自的文档注释，编辑器有提示。
- `clone(options: ICascaderItem[]): ICascaderItem[]`
- `insertPath(options: ICascaderItem[], path: ICascaderItem[]): ICascaderItem[]`
- `getNode(options: ICascaderItem[], path: ICascaderItem[]): ICascaderItem | null`
- `merge(options: ICascaderItem[], another: ICascaderItem[]): ICascaderItem[]`