zent
Version:
一套前端设计语言和基于React的实现
94 lines (74 loc) • 9.29 kB
Markdown
---
title: Cascader
path: component/cascader
group: Data Entry
---
## Cascader
Cascader is used for cascade operation, e.g. cascade location selection.
### API
`Cascader` contains `MenuCascader` and `TabsCascader`, most of their APIS are shared.
### Shared APIS
| Props | Description | Type | Required | Default | Alternatives |
| ----------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | -------- | --------------- | ------------ |
| value | Selected value | `CascaderValue[]` | No | `[]` | |
| maxLine | tags show lines | `number` | No | `null` | |
| lineHeight | each line tag height | `number` | No | `22` | |
| options | Optional data source | `ICascaderItem[]` | Yes | `[]` | |
| onChange | Callback when data changes | `(value: CascaderValue[], selectedOptions: ICascaderItem[], meta: ICascaderChangeMeta) => void` | No | - | |
| loadOptions | Function to load data dynamicly, must return a Promise | `(selectedOptions: ICascaderItem[], meta: ICascaderLoadMeta) => Promise<void>` | No | - | |
| changeOnSelect | Trigger onChange on each selection | `boolean` | No | `false` | `true` |
| placeholder | Placeholder text of input box | `string` | No | `Please choose` | |
| className | Custom classname | `string` | No | | |
| popupClassName | Custom classname of popover | `string` | No | | |
| disabled | Disable cascader | `boolean` | No | `false` | `true` |
| clearable | Show clear button | `boolean` | No | `false` | `true` |
| visible | Use with `onVisibleChange` to control open/close | `boolean` | No | | |
| onVisibleChange | Use with `visible` | `(visible: boolean) => void` | No |
| renderValue | Render selected option value | `(selectedOptions: ICascaderItem[]) => string` | No | | |
| renderItemContent | Customize rendering of item content | `(node: ICascaderItem) => ReactNode` | No | `node.label` | |
| getItemTooltip | Customize item tooltip | `(node: ICascaderItem) => string` | No | `node.label` | |
| renderList | Customize rendering of item list | `(nodes: ICascaderItem[], renderItem: (node: ICascaderItem, style: CSSProperties) => ReactNode) => ReactNode` | No | | |
#### ICascaderItem
```ts
interface ICascaderItem {
value: string | number;
label: string;
children?: ICascaderItem[];
disabled?: boolean;
loadChildrenOnExpand?: boolean; // Load children when expanding next level
loadChildrenOnScroll?: boolean; // Load children when scrolling beyound bottom
}
```
#### Meta object
`onChange` and `loadOptions` has a `meta` parameter, you can use it to distinguish between different actions that trigger `onChange` or `loadOptions`.
### MenuCascader
| Props | Description | Type | Required | Default | Alternatives |
| -------------------- | ------------------------------------------- | ------------------------------------------------------- | -------- | ------- | ------------ |
| multiple | Multiple | `boolean` | No | `false` | `true` |
| multipleType | Multiple type | `normal` `checkbox` | No | `normal`| `checkbox` |
| expandTrigger | Secondary menu expand trigger type | `string` | No | `click` | `hover` |
| scrollable | Can scroll load data dynamicly | `boolean` | No | `false` | `true` |
| loadChildrenOnScroll | Load children when scrolling in first level | `boolean` | No | `false` | `true` |
| searchable | Can search | `boolean` | No | `false` | `true` |
| async | Can async search | `boolean` | No | `false` | `true` |
| asyncFilter | Async filter by keyword | `(keyword: string) => Promise<Array<ICascaderItem[]>>` | No | - | |
| filter | Filter options by keyword | `(keyword: string, path: ICascaderItem[]) => boolean` | No | - | |
| highlight | Highlight options by keyword | `(keyword: string, path: ICascaderItem[]) => ReactNode` | No | - | |
| limit | Limit search result count | `number` | No | `50` | |
| renderTags | Render tag list | `(props: ICascaderTagsProps) => ReactNode` | No | | |
| simplifySelection | Merge similar selections | `boolean` | `否` | `false` | `true` |
| simplifySelectionMode| Merge similar selections, with disabled options | `string` | `否` | `excludeDisabled` | `includeDisabled` |
- When `multiple` is `true`，`onChange` parameters such as `value` and `selectedOptions` are two dimensional arrays
- `renderTags` is only available in multi select mode
- Use `scrollable` and `loadChildrenOnScroll` to control automatically loading data when scrolling to bottom
- `simplifySelection` only works in `multiple` mode. There's also an extra `simplify` method in `meta` parameter for `onChange` in `multiple` mode
### TabsCascader
| Props | Description | Type | Required | Default | Alternatives |
| ----- | ------------- | ------------- | -------- | ------- | ------------ |
| title | Title of tabs | `ReactNode[]` | No | `[]` | |
### Options manipulate functions
`Cascader` implements a few functions for manipulating `options`, these functions are not exported directly from `zent`, you need to manually import them from `zent/es/cascader/public-options-fns`. Check doc comments for detailed explaination for each function.
- `clone(options: ICascaderItem[]): ICascaderItem[]`
- `insertPath(options: ICascaderItem[], path: ICascaderItem[]): ICascaderItem[]`
- `getNode(options: ICascaderItem[], path: ICascaderItem[]): ICascaderItem | null`
- `merge(options: ICascaderItem[], another: ICascaderItem[]): ICascaderItem[]`