--- 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` | 否 | - | | | 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>` | 否 | - | | | 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[]`