Cascader 级联选择器
当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。
基础用法
有两种触发子菜单的方式
type为'cascader'
显示配置
禁用选项
通过在数据源中设置 disabled 字段来声明该选项是禁用的
本例中，options 指定的数组中的第一个元素含有 disabled: true 键值对，因此是禁用的。在默认情况下，Cascader 会检查数据中每一项的 disabled 字段是否为 true ，如果你的数据中表示禁用含义的字段名不为 disabled ，可以通过 disabled 属性来指定（详见下方 API 表格）。当然， value 、 label 和 children 这三个字段名也可以通过同样的方式指定。
显示配置
多选
可通过 multiple = true 来开启多选模式
在开启多选模式后，默认情况下会展示所有已选中的选项的Tag
显示配置
任意一级可选
在单选模式下，你只能选择叶子节点；而在多选模式下，勾选父节点真正选中的都是叶子节点。启用该功能后，可让父子节点取消关联，选择任意一级选项。
可通过 checkStrictly = true 来设置父子节点取消选中关联，从而达到选择任意一级选项的目的。
配置 checkStrictly 为 true，可选择任意一级选项
显示配置
仅返回选中节点的值
在选中节点改变时，默认返回由该节点所在的各级菜单的值所组成的数组。可通过 emitPath = false 设置仅返回该节点的值。
配置 emitPath 为 false，仅返回选中节点的值，而非完整路径数组
显示配置
值分隔符
当需要将选中值以字符串形式存储时，可通过 valueSeparator 指定分隔符，组件会自动将数组转换为字符串存储，读取时也会自动还原。
配置 valueSeparator 为 '/'，选中值将以 'zhinan/shejiyuanze/yizhi' 的字符串形式存储
显示配置
远程选项
通过接口请求获取选项列表
配置 remote 为 true，然后配置 option 对象，而不是 options 数组
显示配置
同时在 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 | — | false |
| multiple | 是否多选 | boolean | — | false |
| emitPath | 在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值 | boolean | — | true |
| checkStrictly | 是否严格的遵守父子节点不互相关联 | boolean / FilterFunction | — | false |
| valueSeparator | 合并成字符串时的分隔符 | string / FilterFunction | — | — |
| popperClass | 弹出内容的自定义类名 | string | — | — |
| remote | 是否为远程搜索 | boolean | — | false |
| options | 选项数据源 | Array / Function | — | — |
| option | 远程选项配置 | Object | — | — |
| onChange | 值变化时触发的函数 | OnChangeHandler | — | — |
查看 FilterFunction / OnChangeHandler 及关联类型定义
ts
export type FilterFunction<T = boolean> = (
mForm: FormState | undefined,
data: {
model: FormValue;
values: FormValue;
parent?: FormValue;
formValue: FormValue;
prop: string;
config: any;
index?: number;
getFormValue: (prop: string) => any;
},
) => T;ts
export type OnChangeHandler = (mForm: FormState | undefined, value: any, data: OnChangeHandlerData) => any;ts
export interface OnChangeHandlerData {
model: FormValue;
values?: Readonly<FormValue> | null;
parent?: FormValue;
formValue?: FormValue;
config: Readonly<any>;
prop: string;
changeRecords: ChangeRecord[];
setModel: (prop: string, value: any) => void;
setFormValue: (prop: string, value: any) => void;
}ts
export interface ChangeRecord {
propPath?: string;
value: any;
}ts
export type FormValue = Record<string | number, any>;配置类型
查看 CascaderConfig 配置类型定义
ts
export interface CascaderConfig extends FormItem, Input {
type: 'cascader';
remote?: boolean;
/** 在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值，默认 true */
emitPath?: boolean;
/** 是否多选，默认 false */
multiple?: boolean;
/** 是否严格的遵守父子节点不互相关联，默认 false */
checkStrictly?: boolean | FilterFunction<boolean>;
/** 弹出内容的自定义类名 */
popperClass?: string;
/** 合并成字符串时的分隔符 */
valueSeparator?: string | FilterFunction<string>;
options?:
| ((
mForm: FormState | undefined,
data: {
model: Record<any, any>;
prop: string;
formValue: Record<any, any>;
},
) => CascaderOption[])
| CascaderOption[];
option?: {
url: string;
cache?: boolean;
timeout?: number;
body?: Record<string, any> | RemoteSelectOptionBodyFunction;
root: 'string';
item: (optionsData: Record<string, any>) => CascaderOption[];
};
}ts
export interface FormItem {
/** vnode的key值，默认是遍历数组时的index */
__key?: string | number;
/** 表单域标签的的宽度，例如 '50px'。支持 auto。 */
labelWidth?: string | number;
/** label 标签的title属性 */
labelTitle?: string;
className?: string;
/** 字段名 */
name?: string | number;
/** 额外的提示信息，和 help 类似，当提示文案同时出现时，可以使用这个。 */
extra?: string | FilterFunction<string>;
/** 配置提示信息 */
tooltip?: ToolTipConfigType | FilterFunction<ToolTipConfigType>;
/** 是否置灰 */
disabled?: boolean | FilterFunction;
/** 使用表单中的值作为key，例如配置了text，则使用model.text作为key */
key?: string;
/** 是否显示 */
display?: boolean | 'expand' | FilterFunction<boolean | 'expand'>;
/** 值发生改变时调用的方法 */
onChange?: OnChangeHandler;
/** label 标签的文本 */
text?: string | FilterFunction<string>;
/** 右侧感叹号 */
tip?: string;
filter?: 'number' | OnChangeHandler;
/** 是否去除首尾空格 */
trim?: boolean;
/** 默认值 */
defaultValue?: any | DefaultValueFunction;
/** 表单验证规则 */
rules?: Rule[];
extensible?: boolean;
dynamicKey?: string;
/** 是否需要显示`展开更多配置` */
expand?: boolean;
style?: Record<string, any>;
fieldStyle?: Record<string, any>;
labelPosition?: 'top' | 'left' | 'right';
}ts
export interface Input {
/** 输入框没有内容时显示的文案 */
placeholder?: string;
}options item
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| value | 选项的值 | any | — | — |
| label | 选项的标签 | string | — | — |
| children | 子选项 | Array | — | — |
option（远程配置）
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| url | 请求地址 | string | — | — |
| root | 响应数据的根路径 | string | — | — |
| cache | 是否缓存请求结果 | boolean | — | false |
| timeout | 请求超时时间（毫秒） | number | — | — |
| body | 请求体 | Object / Function | — | — |
| item | 数据转换函数，将响应数据转换为选项格式 | Function | — | — |