tmagic-editor/docs/form-config/fields/cascader.md

Cascader 级联选择器

当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。

基础用法

有两种触发子菜单的方式

<template #source>

type为'cascader'

禁用选项

通过在数据源中设置 disabled 字段来声明该选项是禁用的

<template #source>

本例中，options 指定的数组中的第一个元素含有 disabled: true 键值对，因此是禁用的。在默认情况下，Cascader 会检查数据中每一项的 disabled 字段是否为 true ，如果你的数据中表示禁用含义的字段名不为 disabled ，可以通过 disabled 属性来指定（详见下方 API 表格）。当然， value 、 label 和 children 这三个字段名也可以通过同样的方式指定。

多选

可通过 multiple = true 来开启多选模式

<template #source>

在开启多选模式后，默认情况下会展示所有已选中的选项的Tag

任意一级可选

在单选模式下，你只能选择叶子节点；而在多选模式下，勾选父节点真正选中的都是叶子节点。启用该功能后，可让父子节点取消关联，选择任意一级选项。

可通过 checkStrictly = true 来设置父子节点取消选中关联，从而达到选择任意一级选项的目的。

<template #source>

配置 checkStrictly 为 true，可选择任意一级选项

仅返回选中节点的值

在选中节点改变时，默认返回由该节点所在的各级菜单的值所组成的数组。可通过 emitPath = false 设置仅返回该节点的值。

<template #source>

配置 emitPath 为 false，仅返回选中节点的值，而非完整路径数组

值分隔符

当需要将选中值以字符串形式存储时，可通过 valueSeparator 指定分隔符，组件会自动将数组转换为字符串存储，读取时也会自动还原。

<template #source>

配置 valueSeparator 为 '/'，选中值将以 'zhinan/shejiyuanze/yizhi' 的字符串形式存储

远程选项

通过接口请求获取选项列表

<template #source>

配置 remote 为 true，然后配置 option 对象，而不是 options 数组

同时在 src/main.ts 中需要自定义实现请求：

app.use(MagicForm, {
  request: async (options: any) => {
    // 自定义请求实现
  },
});

动态选项

options 支持传入函数，可根据表单其他字段动态生成选项列表

{
  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	—	—

::: details 查看 FilterFunction / OnChangeHandler 及关联类型定义 <<< @/../packages/form-schema/src/base.ts#FilterFunction{ts}

<<< @/../packages/form-schema/src/base.ts#OnChangeHandler{ts}

<<< @/../packages/form-schema/src/base.ts#OnChangeHandlerData{ts}

<<< @/../packages/form-schema/src/base.ts#ChangeRecord{ts}

<<< @/../packages/form-schema/src/base.ts#FormValue{ts} :::

配置类型

::: details 查看 CascaderConfig 配置类型定义 <<< @/../packages/form-schema/src/base.ts#CascaderConfig{ts}

<<< @/../packages/form-schema/src/base.ts#FormItem{ts}

<<< @/../packages/form-schema/src/base.ts#Input{ts}

:::

options item

参数	说明	类型	可选值	默认值
value	选项的值	any	—	—
label	选项的标签	string	—	—
children	子选项	Array	—	—

option（远程配置）

参数	说明	类型	可选值	默认值
url	请求地址	string	—	—
root	响应数据的根路径	string	—	—
cache	是否缓存请求结果	boolean	—	false
timeout	请求超时时间（毫秒）	number	—	—
body	请求体	Object / Function	—	—
item	数据转换函数，将响应数据转换为选项格式	Function	—	—