Cascader 级联选择器
代码演示
基础用法
选项卡风格
进阶
带初始值
自定义 keys
使用次级标题
选择任意一项
Cascader Props
| 名称 | 类型 | 默认值 | 描述 | 必传 |
|---|---|---|---|---|
| checkStrictly | Boolean | false | 父子节点选中状态不再关联，可各自选中或取消 | N |
| closeBtn | Boolean / Slot / Function | true | 关闭按钮。TS 类型：boolean \| TNode。通用类型定义 | N |
| header | Slot / Function | - | 头部。TS 类型：TNode。通用类型定义 | N |
| keys | Object | - | 用来定义 value / label / children / disabled 在 options 中对应的字段别名。TS 类型：CascaderKeysType type CascaderKeysType = TreeKeysType。通用类型定义。详细类型定义 | N |
| middleContent | Slot / Function | - | 中间内容。TS 类型：TNode。通用类型定义 | N |
| options | Array | [] | 可选项数据源。TS 类型：Array<CascaderOption> | N |
| placeholder | String / Slot / Function | '选择选项' | 未选中时的提示文案。TS 类型：string \| TNode。通用类型定义 | N |
| subTitles | Array | [] | 每级展示的次标题。TS 类型：Array<string> | N |
| theme | String | step | 展示风格。可选项：step/tab | N |
| title | String / Slot / Function | - | 标题。TS 类型：string \| TNode。通用类型定义 | N |
| value | String / Number | - | 选项值。支持语法糖 v-model 或 v-model:value | N |
| defaultValue | String / Number | - | 选项值。非受控属性 | N |
| visible | Boolean | false | 是否展示 | N |
| onChange | Function | TS 类型：(value: string \| number, selectedOptions: CascaderOption[]) => void值发生变更时触发 | N | |
| onClose | Function | TS 类型：(trigger: CascaderTriggerSource) => void关闭时触发。详细类型定义。 type CascaderTriggerSource = 'overlay' \| 'close-btn' \| 'finish' | N | |
| onPick | Function | TS 类型：(context: { value: string \| number, label: string, index: number, level: number }) => void选择后触发 | N |
Cascader Events
| 名称 | 参数 | 描述 |
|---|---|---|
| change | (value: string \| number, selectedOptions: CascaderOption[]) | 值发生变更时触发 |
| close | (trigger: CascaderTriggerSource) | 关闭时触发。详细类型定义。type CascaderTriggerSource = 'overlay' \| 'close-btn' \| 'finish' |
| pick | (context: { value: string \| number, label: string, index: number, level: number }) | 选择后触发 |
CSS Variables
组件提供了下列 CSS 变量，可用于自定义样式。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --td-cascader-active-color | @brand-color | - |
| --td-cascader-border-color | @border-color | - |
| --td-cascader-disabled-color | @font-gray-4 | - |
| --td-cascader-options-height | 320px | - |
| --td-cascader-options-title-color | @font-gray-3 | - |
| --td-cascader-step-arrow-color | @font-gray-3 | - |
| --td-cascader-step-dot-size | 8px | - |
| --td-cascader-step-height | 44px | - |
| --td-cascader-title-color | @font-gray-1 | - |
| --td-cascder-title-font-size | 18px | - |
何时使用
当一组选项由递进层级构成，且每个层级有大量的选项需要用户逐级选择时使用。
组件搭配使用
级联选择器与索引组合使用，当每个层级选项较多时，配合索引有利于用户快速找到目标选项。
常见用法
在表单中，级联选择器可放置于表单内容需要的顺序中，通常用于地址信息的选择和填写。
推荐/慎用示例
级联选择器的层级不宜超过4层，层级过多时应调整数据结构或改用其他交互方式。
在多层级中，各层级选项的归属关系应具备逻辑相关性，数据层级由大到小，避免归属关系混乱。
相似组件
| 组件名 | 何时使用 |
|---|---|
| 选择器 | 当需要在有限的空间展示大量选项供用户选择，或者一组选项由递进层级构成需要用户逐级选择时使用。 |
