mirror of
https://github.com/Tencent/tmagic-editor.git
synced 2026-01-28 21:18:10 +00:00
455 lines
11 KiB
Markdown
455 lines
11 KiB
Markdown
# Cascader 级联选择器
|
||
|
||
当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。
|
||
|
||
## 基础用法
|
||
|
||
有两种触发子菜单的方式
|
||
|
||
<demo-block type="form" :config="[{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
placeholder: '请选择',
|
||
options: [
|
||
{
|
||
value: 'zhinan',
|
||
label: '指南',
|
||
children: [{
|
||
value: 'shejiyuanze',
|
||
label: '设计原则',
|
||
children: [{
|
||
value: 'yizhi',
|
||
label: '一致'
|
||
}, {
|
||
value: 'fankui',
|
||
label: '反馈'
|
||
}]
|
||
}, {
|
||
value: 'daohang',
|
||
label: '导航',
|
||
children: [{
|
||
value: 'cexiangdaohang',
|
||
label: '侧向导航'
|
||
}, {
|
||
value: 'dingbudaohang',
|
||
label: '顶部导航'
|
||
}]
|
||
}]
|
||
},
|
||
{
|
||
value: 'zujian',
|
||
label: '组件',
|
||
children: [{
|
||
value: 'basic',
|
||
label: 'Basic',
|
||
children: [{
|
||
value: 'layout',
|
||
label: 'Layout 布局'
|
||
}, {
|
||
value: 'color',
|
||
label: 'Color 色彩'
|
||
}]
|
||
}, {
|
||
value: 'form',
|
||
label: 'Form',
|
||
children: [{
|
||
value: 'checkbox',
|
||
label: 'Checkbox 多选框'
|
||
}, {
|
||
value: 'input',
|
||
label: 'Input 输入框'
|
||
}]
|
||
}]
|
||
}
|
||
]
|
||
}]"><template #source><p>type为'cascader'</p></template></demo-block>
|
||
|
||
## 禁用选项
|
||
|
||
通过在数据源中设置 disabled 字段来声明该选项是禁用的
|
||
|
||
<demo-block type="form" :config="[{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
placeholder: '请选择',
|
||
disabled: true,
|
||
options: [
|
||
]
|
||
}, {
|
||
type: 'cascader',
|
||
name: 'cascader1',
|
||
text: '选项2',
|
||
placeholder: '请选择',
|
||
options: [
|
||
{
|
||
value: 'zhinan',
|
||
label: '指南',
|
||
disabled: true,
|
||
children: [{
|
||
value: 'shejiyuanze',
|
||
label: '设计原则',
|
||
children: [{
|
||
value: 'yizhi',
|
||
label: '一致'
|
||
}, {
|
||
value: 'fankui',
|
||
label: '反馈'
|
||
}]
|
||
}, {
|
||
value: 'daohang',
|
||
label: '导航',
|
||
children: [{
|
||
value: 'cexiangdaohang',
|
||
label: '侧向导航'
|
||
}, {
|
||
value: 'dingbudaohang',
|
||
label: '顶部导航'
|
||
}]
|
||
}]
|
||
},
|
||
{
|
||
value: 'zujian',
|
||
label: '组件',
|
||
children: [{
|
||
value: 'basic',
|
||
label: 'Basic',
|
||
disabled: true,
|
||
children: [{
|
||
value: 'layout',
|
||
label: 'Layout 布局'
|
||
}, {
|
||
value: 'color',
|
||
label: 'Color 色彩'
|
||
}]
|
||
}, {
|
||
value: 'form',
|
||
label: 'Form',
|
||
children: [{
|
||
value: 'checkbox',
|
||
label: 'Checkbox 多选框'
|
||
}, {
|
||
value: 'input',
|
||
disabled: true,
|
||
label: 'Input 输入框'
|
||
}]
|
||
}]
|
||
}
|
||
]
|
||
}]">
|
||
<template #source>
|
||
<p>
|
||
本例中，options 指定的数组中的第一个元素含有 disabled: true 键值对，因此是禁用的。在默认情况下，Cascader 会检查数据中每一项的 disabled 字段是否为 true ，如果你的数据中表示禁用含义的字段名不为 disabled ，可以通过 disabled 属性来指定（详见下方 API 表格）。当然， value 、 label 和 children 这三个字段名也可以通过同样的方式指定。
|
||
</p>
|
||
</template>
|
||
</demo-block>
|
||
|
||
## 多选
|
||
|
||
可通过 `multiple = true` 来开启多选模式
|
||
|
||
<demo-block type="form" :config="[{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
multiple: true,
|
||
placeholder: '请选择',
|
||
options: [
|
||
{
|
||
value: 'zhinan',
|
||
label: '指南',
|
||
children: [{
|
||
value: 'shejiyuanze',
|
||
label: '设计原则',
|
||
children: [{
|
||
value: 'yizhi',
|
||
label: '一致'
|
||
}, {
|
||
value: 'fankui',
|
||
label: '反馈'
|
||
}]
|
||
}, {
|
||
value: 'daohang',
|
||
label: '导航',
|
||
children: [{
|
||
value: 'cexiangdaohang',
|
||
label: '侧向导航'
|
||
}, {
|
||
value: 'dingbudaohang',
|
||
label: '顶部导航'
|
||
}]
|
||
}]
|
||
},
|
||
{
|
||
value: 'zujian',
|
||
label: '组件',
|
||
children: [{
|
||
value: 'basic',
|
||
label: 'Basic',
|
||
children: [{
|
||
value: 'layout',
|
||
label: 'Layout 布局'
|
||
}, {
|
||
value: 'color',
|
||
label: 'Color 色彩'
|
||
}]
|
||
}, {
|
||
value: 'form',
|
||
label: 'Form',
|
||
children: [{
|
||
value: 'checkbox',
|
||
label: 'Checkbox 多选框'
|
||
}, {
|
||
value: 'input',
|
||
label: 'Input 输入框'
|
||
}]
|
||
}]
|
||
}
|
||
]
|
||
}]">
|
||
<template #source>
|
||
<p>
|
||
在开启多选模式后，默认情况下会展示所有已选中的选项的Tag
|
||
</p>
|
||
</template>
|
||
</demo-block>
|
||
|
||
## 任意一级可选
|
||
|
||
在单选模式下，你只能选择叶子节点；而在多选模式下，勾选父节点真正选中的都是叶子节点。启用该功能后，可让父子节点取消关联，选择任意一级选项。
|
||
|
||
可通过 `checkStrictly = true` 来设置父子节点取消选中关联，从而达到选择任意一级选项的目的。
|
||
|
||
<demo-block type="form" :config="[{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
placeholder: '请选择',
|
||
checkStrictly: true,
|
||
options: [
|
||
{
|
||
value: 'zhinan',
|
||
label: '指南',
|
||
children: [{
|
||
value: 'shejiyuanze',
|
||
label: '设计原则',
|
||
children: [{
|
||
value: 'yizhi',
|
||
label: '一致'
|
||
}, {
|
||
value: 'fankui',
|
||
label: '反馈'
|
||
}]
|
||
}]
|
||
},
|
||
{
|
||
value: 'zujian',
|
||
label: '组件',
|
||
children: [{
|
||
value: 'basic',
|
||
label: 'Basic',
|
||
children: [{
|
||
value: 'layout',
|
||
label: 'Layout 布局'
|
||
}, {
|
||
value: 'color',
|
||
label: 'Color 色彩'
|
||
}]
|
||
}]
|
||
}
|
||
]
|
||
}]">
|
||
<template #source>
|
||
<p>
|
||
配置 checkStrictly 为 true，可选择任意一级选项
|
||
</p>
|
||
</template>
|
||
</demo-block>
|
||
|
||
## 仅返回选中节点的值
|
||
|
||
在选中节点改变时，默认返回由该节点所在的各级菜单的值所组成的数组。可通过 `emitPath = false` 设置仅返回该节点的值。
|
||
|
||
<demo-block type="form" :config="[{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
placeholder: '请选择',
|
||
emitPath: false,
|
||
checkStrictly: true,
|
||
options: [
|
||
{
|
||
value: 'zhinan',
|
||
label: '指南',
|
||
children: [{
|
||
value: 'shejiyuanze',
|
||
label: '设计原则',
|
||
children: [{
|
||
value: 'yizhi',
|
||
label: '一致'
|
||
}, {
|
||
value: 'fankui',
|
||
label: '反馈'
|
||
}]
|
||
}]
|
||
},
|
||
{
|
||
value: 'zujian',
|
||
label: '组件',
|
||
children: [{
|
||
value: 'basic',
|
||
label: 'Basic',
|
||
children: [{
|
||
value: 'layout',
|
||
label: 'Layout 布局'
|
||
}, {
|
||
value: 'color',
|
||
label: 'Color 色彩'
|
||
}]
|
||
}]
|
||
}
|
||
]
|
||
}]">
|
||
<template #source>
|
||
<p>
|
||
配置 emitPath 为 false，仅返回选中节点的值，而非完整路径数组
|
||
</p>
|
||
</template>
|
||
</demo-block>
|
||
|
||
## 值分隔符
|
||
|
||
当需要将选中值以字符串形式存储时，可通过 `valueSeparator` 指定分隔符，组件会自动将数组转换为字符串存储，读取时也会自动还原。
|
||
|
||
<demo-block type="form" :config="[{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
placeholder: '请选择',
|
||
valueSeparator: '/',
|
||
options: [
|
||
{
|
||
value: 'zhinan',
|
||
label: '指南',
|
||
children: [{
|
||
value: 'shejiyuanze',
|
||
label: '设计原则',
|
||
children: [{
|
||
value: 'yizhi',
|
||
label: '一致'
|
||
}]
|
||
}]
|
||
},
|
||
{
|
||
value: 'zujian',
|
||
label: '组件',
|
||
children: [{
|
||
value: 'basic',
|
||
label: 'Basic',
|
||
children: [{
|
||
value: 'layout',
|
||
label: 'Layout 布局'
|
||
}]
|
||
}]
|
||
}
|
||
]
|
||
}]">
|
||
<template #source>
|
||
<p>
|
||
配置 valueSeparator 为 '/'，选中值将以 'zhinan/shejiyuanze/yizhi' 的字符串形式存储
|
||
</p>
|
||
</template>
|
||
</demo-block>
|
||
|
||
## 远程选项
|
||
|
||
通过接口请求获取选项列表
|
||
|
||
<demo-block type="form" :config="[{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
placeholder: '请选择',
|
||
remote: true,
|
||
option: {
|
||
url: 'cascader/remote',
|
||
root: 'data',
|
||
cache: true,
|
||
timeout: 5000,
|
||
body: { query: '' },
|
||
item: (data) => data
|
||
}
|
||
}]">
|
||
<template #source>
|
||
<p>
|
||
配置 remote 为 true，然后配置 option 对象，而不是 options 数组
|
||
</p>
|
||
</template>
|
||
</demo-block>
|
||
|
||
同时在 `src/main.ts` 中需要自定义实现请求：
|
||
|
||
```typescript
|
||
app.use(MagicForm, {
|
||
request: async (options: any) => {
|
||
// 自定义请求实现
|
||
},
|
||
});
|
||
```
|
||
|
||
## 动态选项
|
||
|
||
options 支持传入函数，可根据表单其他字段动态生成选项列表
|
||
|
||
```typescript
|
||
{
|
||
type: 'cascader',
|
||
name: 'cascader',
|
||
text: '选项',
|
||
options: (mForm, { model, formValue }) => {
|
||
// 根据表单值动态返回选项
|
||
return [
|
||
{ value: 'a', label: '选项A', children: [] }
|
||
];
|
||
}
|
||
}
|
||
```
|
||
|
||
## Cascader Attributes
|
||
|
||
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|
||
|------|------|------|--------|--------|
|
||
| name | 绑定值 | string | — | — |
|
||
| text | 表单标签 | string | — | — |
|
||
| placeholder | 输入框占位文本 | string | — | — |
|
||
| disabled | 是否禁用 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | false |
|
||
| multiple | 是否多选 | boolean | — | false |
|
||
| emitPath | 在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值 | boolean | — | true |
|
||
| checkStrictly | 是否严格的遵守父子节点不互相关联 | boolean / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | false |
|
||
| valueSeparator | 合并成字符串时的分隔符 | string / [FilterFunction](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — |
|
||
| popperClass | 弹出内容的自定义类名 | string | — | — |
|
||
| remote | 是否为远程搜索 | boolean | — | false |
|
||
| options | 选项数据源 | Array / Function | — | — |
|
||
| option | 远程选项配置 | Object | — | — |
|
||
| onChange | 值变化时触发的函数 | [OnChangeHandler](https://github.com/Tencent/tmagic-editor/blob/master/packages/form-schema/src/base.ts) | — | — |
|
||
|
||
## options item
|
||
|
||
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|
||
|------|------|------|--------|--------|
|
||
| value | 选项的值 | any | — | — |
|
||
| label | 选项的标签 | string | — | — |
|
||
| children | 子选项 | Array | — | — |
|
||
|
||
## option（远程配置）
|
||
|
||
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|
||
|------|------|------|--------|--------|
|
||
| url | 请求地址 | string | — | — |
|
||
| root | 响应数据的根路径 | string | — | — |
|
||
| cache | 是否缓存请求结果 | boolean | — | false |
|
||
| timeout | 请求超时时间（毫秒） | number | — | — |
|
||
| body | 请求体 | Object / Function | — | — |
|
||
| item | 数据转换函数，将响应数据转换为选项格式 | Function | — | — |
|