import{At as e,E as t,Mt as n,Ot as r,Tt as i,Xt as a,dn as o,en as s,jt as c}from"./chunks/framework.ECw2lWOt.js";var l=JSON.parse(`{"title":"Cascader 级联选择器","description":"","frontmatter":{},"headers":[],"relativePath":"form-config/fields/cascader.md","filePath":"form-config/fields/cascader.md"}`),u={name:`form-config/fields/cascader.md`};function d(t,l,u,d,f,p){let m=s(`demo-block`);return a(),r(`div`,null,[l[7]||=i(`h1`,{id:`cascader-级联选择器`,tabindex:`-1`},[c(`Cascader 级联选择器 `),i(`a`,{class:`header-anchor`,href:`#cascader-级联选择器`,"aria-label":`Permalink to “Cascader 级联选择器”`},`​`)],-1),l[8]||=i(`p`,null,`当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。`,-1),l[9]||=i(`h2`,{id:`基础用法`,tabindex:`-1`},[c(`基础用法 `),i(`a`,{class:`header-anchor`,href:`#基础用法`,"aria-label":`Permalink to “基础用法”`},`​`)],-1),l[10]||=i(`p`,null,`有两种触发子菜单的方式`,-1),n(m,{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 输入框`}]}]}]}]},{source:o(()=>[...l[0]||=[i(`p`,null,`type为'cascader'`,-1)]]),_:1}),l[11]||=i(`h2`,{id:`禁用选项`,tabindex:`-1`},[c(`禁用选项 `),i(`a`,{class:`header-anchor`,href:`#禁用选项`,"aria-label":`Permalink to “禁用选项”`},`​`)],-1),l[12]||=i(`p`,null,`通过在数据源中设置 disabled 字段来声明该选项是禁用的`,-1),n(m,{type:`form`,config:[{type:`cascader`,name:`cascader`,text:`选项`,placeholder:`请选择`,disabled:!0,options:[]},{type:`cascader`,name:`cascader1`,text:`选项2`,placeholder:`请选择`,options:[{value:`zhinan`,label:`指南`,disabled:!0,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:!0,children:[{value:`layout`,label:`Layout 布局`},{value:`color`,label:`Color 色彩`}]},{value:`form`,label:`Form`,children:[{value:`checkbox`,label:`Checkbox 多选框`},{value:`input`,disabled:!0,label:`Input 输入框`}]}]}]}]},{source:o(()=>[...l[1]||=[i(`p`,null,` 本例中，options 指定的数组中的第一个元素含有 disabled: true 键值对，因此是禁用的。在默认情况下，Cascader 会检查数据中每一项的 disabled 字段是否为 true ，如果你的数据中表示禁用含义的字段名不为 disabled ，可以通过 disabled 属性来指定（详见下方 API 表格）。当然， value 、 label 和 children 这三个字段名也可以通过同样的方式指定。 `,-1)]]),_:1}),l[13]||=i(`h2`,{id:`多选`,tabindex:`-1`},[c(`多选 `),i(`a`,{class:`header-anchor`,href:`#多选`,"aria-label":`Permalink to “多选”`},`​`)],-1),l[14]||=i(`p`,null,[c(`可通过 `),i(`code`,null,`multiple = true`),c(` 来开启多选模式`)],-1),n(m,{type:`form`,config:[{type:`cascader`,name:`cascader`,text:`选项`,multiple:!0,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 输入框`}]}]}]}]},{source:o(()=>[...l[2]||=[i(`p`,null,` 在开启多选模式后，默认情况下会展示所有已选中的选项的Tag `,-1)]]),_:1}),l[15]||=i(`h2`,{id:`任意一级可选`,tabindex:`-1`},[c(`任意一级可选 `),i(`a`,{class:`header-anchor`,href:`#任意一级可选`,"aria-label":`Permalink to “任意一级可选”`},`​`)],-1),l[16]||=i(`p`,null,`在单选模式下，你只能选择叶子节点；而在多选模式下，勾选父节点真正选中的都是叶子节点。启用该功能后，可让父子节点取消关联，选择任意一级选项。`,-1),l[17]||=i(`p`,null,[c(`可通过 `),i(`code`,null,`checkStrictly = true`),c(` 来设置父子节点取消选中关联，从而达到选择任意一级选项的目的。`)],-1),n(m,{type:`form`,config:[{type:`cascader`,name:`cascader`,text:`选项`,placeholder:`请选择`,checkStrictly:!0,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 色彩`}]}]}]}]},{source:o(()=>[...l[3]||=[i(`p`,null,` 配置 checkStrictly 为 true，可选择任意一级选项 `,-1)]]),_:1}),l[18]||=i(`h2`,{id:`仅返回选中节点的值`,tabindex:`-1`},[c(`仅返回选中节点的值 `),i(`a`,{class:`header-anchor`,href:`#仅返回选中节点的值`,"aria-label":`Permalink to “仅返回选中节点的值”`},`​`)],-1),l[19]||=i(`p`,null,[c(`在选中节点改变时，默认返回由该节点所在的各级菜单的值所组成的数组。可通过 `),i(`code`,null,`emitPath = false`),c(` 设置仅返回该节点的值。`)],-1),n(m,{type:`form`,config:[{type:`cascader`,name:`cascader`,text:`选项`,placeholder:`请选择`,emitPath:!1,checkStrictly:!0,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 色彩`}]}]}]}]},{source:o(()=>[...l[4]||=[i(`p`,null,` 配置 emitPath 为 false，仅返回选中节点的值，而非完整路径数组 `,-1)]]),_:1}),l[20]||=i(`h2`,{id:`值分隔符`,tabindex:`-1`},[c(`值分隔符 `),i(`a`,{class:`header-anchor`,href:`#值分隔符`,"aria-label":`Permalink to “值分隔符”`},`​`)],-1),l[21]||=i(`p`,null,[c(`当需要将选中值以字符串形式存储时，可通过 `),i(`code`,null,`valueSeparator`),c(` 指定分隔符，组件会自动将数组转换为字符串存储，读取时也会自动还原。`)],-1),n(m,{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 布局`}]}]}]}]},{source:o(()=>[...l[5]||=[i(`p`,null,` 配置 valueSeparator 为 '/'，选中值将以 'zhinan/shejiyuanze/yizhi' 的字符串形式存储 `,-1)]]),_:1}),l[22]||=i(`h2`,{id:`远程选项`,tabindex:`-1`},[c(`远程选项 `),i(`a`,{class:`header-anchor`,href:`#远程选项`,"aria-label":`Permalink to “远程选项”`},`​`)],-1),l[23]||=i(`p`,null,`通过接口请求获取选项列表`,-1),n(m,{type:`form`,config:[{type:`cascader`,name:`cascader`,text:`选项`,placeholder:`请选择`,remote:!0,option:{url:`cascader/remote`,root:`data`,cache:!0,timeout:5e3,body:{query:``},item:e=>e}}]},{source:o(()=>[...l[6]||=[i(`p`,null,` 配置 remote 为 true，然后配置 option 对象，而不是 options 数组 `,-1)]]),_:1},8,[`config`]),l[24]||=e(`

同时在 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>;
  /** 额外的提示信息，和 extra 类似，着重强调时用这个显示，优先级高于extra*/
  extraTips?: 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;
  /** 标题下方的额外提示信息 */
  titleExtra?: string;
  /** 表单验证规则 */
  rules?: Rule[];
  extensible?: boolean;
  dynamicKey?: string;
  /** 是否需要显示\`展开更多配置\` */
  expand?: boolean;
  style?: Record<string, any>;
  fieldStyle?: Record<string, any>;
  labelPosition?: 'top' | 'left' | 'right';
  flat?: boolean;
  fixed?: boolean | 'left' | 'right';
  operateColWidth?: number | string;
}
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——
`,14)])}var f=t(u,[[`render`,d]]);export{l as __pageData,f as default};