Cascader级联选择器

适用于分类、组织、区域等树形数据的逐级选择。一个 Cascader 字段默认保存从父节点到叶子节点的值路径，例如 ['north', 'beijing', 'chaoyang']。

如果希望大区、站点分别保存到两个字段，并用上级值请求下级选项，请使用 表单多级联动。

需求	关键配置	绑定值形态
完整路径	默认 emitPath: true	单个路径数组
只提交选中节点	emitPath: false	单个节点值
多选路径	multiple: true	路径数组组成的数组
可选择父节点	checkStrictly: true	取决于是否启用 emitPath
只显示末级文字	showAllLevels: false	不改变绑定值结构

提示

节点值应唯一且类型一致。显示层级由 showAllLevels 控制，提交路径由 emitPath 控制；只想缩短输入框文字时，不必改变提交值。

复制示例中的结果组件与本地演示数据，见 示例辅助文件。

基础用法

效果预览可直接操作下方示例

设置 type: 'cascader'，用 dicData 提供包含 children 的树形字典。展开并选择叶子节点；expandTrigger 可设置子级展开方式，默认为 hover。

正在加载示例…

<template>
  <avue-form :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dicData = [{
  value: 'zhinan',
  label: '指南',
  children: [{
    value: 'shejiyuanze',
    label: '设计原则',
    children: [{
      value: 'yizhi',
      label: '一致'
    }, {
      value: 'fankui',
      label: '反馈'
    }]
  }]
}];

const option = ref({
  column: [{
    label: '级联',
    prop: 'cascader',
    type: 'cascader',
    dicData: dicData
  }, {
    label: '级联',
    prop: 'cascader1',
    type: 'cascader',
    expandTrigger: 'click',
    dicData: dicData
  }]
});
</script>

默认值

效果预览可直接操作下方示例

column.value 提供初始化默认值。路径中的每个值都必须能在对应层级字典中找到；编辑已有数据时，可直接给 v-model 对应字段赋值。

正在加载示例…

<template>
  <avue-form :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dicData = [
  {
    value: 'zhinan',
    label: '指南',
    children: [
      {
        value: 'shejiyuanze',
        label: '设计原则',
        children: [
          { value: 'yizhi', label: '一致' },
          { value: 'fankui', label: '反馈' }
        ]
      }
    ]
  }
];

const option = ref({
  column: [
    {
      label: '级联',
      prop: 'cascader',
      type: 'cascader',
      value: ['zhinan', 'shejiyuanze', 'yizhi'],
      dicData: dicData
    }
  ]
});
</script>

多选

效果预览可直接操作下方示例

multiple: true 开启多选；collapseTags 折叠标签，maxCollapseTags 设置可见标签数量，collapseTagsTooltip 显示折叠标签的提示。勾选多个叶子节点，观察标签的展开与折叠。

正在加载示例…

<template>
  <avue-form v-model="form"
             :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dic = [
  {
    value: 'zhinan',
    label: '指南',
    children: [
      {
        value: 'shejiyuanze',
        label: '设计原则',
        children: [
          { value: 'yizhi', label: '一致' },
          { value: 'fankui', label: '反馈' }
        ]
      }
    ]
  }
];

const form = ref({
  cascader: [["zhinan", "shejiyuanze", "yizhi"], ["zhinan", "shejiyuanze", "fankui"]]
});

const option = ref({
  column: [
    {
      label: '级联',
      prop: 'cascader',
      type: 'cascader',
      dicData: dic,
      multiple: true
    },
    {
      label: '级联',
      prop: 'cascader',
      type: 'cascader',
      dicData: dic,
      collapseTags: true,
      maxCollapseTags: 3,
      collapseTagsTooltip: true,
      multiple: true
    }
  ]
});
</script>

禁用状态

效果预览可直接操作下方示例

在字段上设置 disabled: true 会禁用整个选择器，已有值仍可回显。

正在加载示例…

<template>
  <avue-form :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dicData = [
  {
    value: 'zhinan',
    label: '指南',
    children: [
      {
        value: 'shejiyuanze',
        label: '设计原则',
        children: [
          {
            value: 'yizhi',
            label: '一致'
          },
          {
            value: 'fankui',
            label: '反馈'
          }
        ]
      }
    ]
  }
];

const option = ref({
  column: [
    {
      label: '级联',
      prop: 'cascader',
      type: 'cascader',
      dicData: dicData,
      disabled: true
    }
  ]
});
</script>

禁用选项

效果预览可直接操作下方示例

在字典节点上设置 disabled: true 只禁用该选项。适用于停用分类或暂不可选的组织节点。

正在加载示例…

<template>
  <avue-form :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dicData = [{
  value: 'zhinan',
  label: '指南',
  children: [{
    value: 'shejiyuanze',
    label: '设计原则',
    children: [{
      disabled: true,
      value: 'yizhi',
      label: '一致'
    }, {
      value: 'fankui',
      label: '反馈'
    }]
  }]
}];

const option = ref({
  column: [
    {
      label: '级联',
      prop: 'cascader',
      type: 'cascader',
      dicData: dicData
    }
  ]
});
</script>

下拉框样式

弹层通常挂载在页面外层，使用唯一的 popperClass 限定样式范围，避免影响其他级联选择器。

.popperClass .el-cascader-node {
  background-color: rgba(0, 0, 0, .2);
}

效果预览可直接操作下方示例

popperClass 指定当前弹层的 class 名称。自定义颜色时保留可读的选中、禁用和悬浮状态。

正在加载示例…

<template>
  <avue-form :option="option"
             v-model="form"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dicData = [
  {
    value: 'zhinan',
    label: '指南',
    children: [
      {
        value: 'shejiyuanze',
        label: '设计原则',
        children: [
          { value: 'yizhi', label: '一致' },
          { value: 'fankui', label: '反馈' }
        ]
      }
    ]
  }
];

const form = ref({});
const option = ref({
  column: [
    {
      label: '级联',
      prop: 'cascader',
      type: 'cascader',
      popperClass: 'popperClass',
      dicData: dicData
    }
  ]
});
</script>

网络字典

效果预览可直接操作下方示例

dicUrl 返回完整树形字典，props 映射 name、code 和 children；本例在本地模拟接口，以保证无需外部服务即可操作。选择服务点后可看到完整的路径值。

正在加载示例…

<template>
  <avue-form v-model="form" :option="option" />
  <form-demo-result :value="result" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';
import { regions, useDictionaryMock } from '../_shared/useDictionaryMock';

const form = ref({ location: ['north', 'beijing', 'chaoyang'] });
const { baseUrl } = useDictionaryMock(() => ({ data: { items: regions } }));
const result = computed(() => ({ location: form.value.location }));
const option = {
  menuBtn: false,
  column: [{
    label: '服务点', prop: 'location', type: 'cascader', span: 24,
    props: { label: 'name', value: 'code', children: 'children', res: 'data.items' },
    dicUrl: baseUrl + '/regions',
  }],
};
</script>

如果接口一次只返回某一层的数据，应使用下面的懒加载模式，而不是把只有顶层的数组当作完整树。接口响应格式见 表单数据字典。

仅显示最后一级

效果预览可直接操作下方示例

showAllLevels: false 仅缩短输入框中的文字。选择叶子节点后，结果区仍显示包含父级的完整路径。

正在加载示例…

<template>
  <avue-form v-model="form" :option="option" />
  <form-demo-result :value="result" hint="输入框仅显示末级文字，提交值仍包含完整路径。" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';
import { regions } from '../_shared/useDictionaryMock';

const form = ref({ location: ['north', 'beijing', 'chaoyang'] });
const result = computed(() => ({ location: form.value.location }));
const option = {
  menuBtn: false,
  column: [{
    label: '服务点', prop: 'location', type: 'cascader', span: 24,
    props: { label: 'name', value: 'code' }, dicData: regions, showAllLevels: false,
  }],
};
</script>

选中单节点

效果预览可直接操作下方示例

emitPath: false 只提交选中节点的值。下面选择同一个服务点，对比默认路径数组与末级编码；修改 emitPath 后，也要相应调整编辑回显的数据结构。

正在加载示例…

<template>
  <avue-form v-model="form" :option="option" />
  <form-demo-result :value="result" hint="选择同一服务点，对比数组路径与单个节点编码。" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';
import { regions } from '../_shared/useDictionaryMock';

const form = ref({ path: ['north', 'beijing', 'chaoyang'], code: 'chaoyang' });
const result = computed(() => ({ path: form.value.path, code: form.value.code }));
const option = {
  menuBtn: false,
  labelWidth: 110,
  column: [
    { label: '完整路径', prop: 'path', type: 'cascader', span: 24,
      props: { label: 'name', value: 'code' }, dicData: regions },
    { label: '末级编码', prop: 'code', type: 'cascader', span: 24, emitPath: false,
      props: { label: 'name', value: 'code' }, dicData: regions },
  ],
};
</script>

任意一级

效果预览可直接操作下方示例

checkStrictly: true 取消父子节点的选中关联，可以单独选择父级节点。常用于允许选择整个组织或某个具体部门的业务。

正在加载示例…

<template>
  <avue-form :option="option"></avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dic = [{
  value: 'zhinan',
  label: '指南',
  children: [{
    value: 'shejiyuanze',
    label: '设计原则',
    children: [{
      value: 'yizhi',
      label: '一致'
    }, {
      value: 'fankui',
      label: '反馈'
    }]
  }]
}];

const option = ref({
  column: [{
    label: '级联',
    prop: 'cascader',
    type: 'cascader',
    dicData: dic,
    checkStrictly: true
  }]
});
</script>

搜索

效果预览可直接操作下方示例

设置 filterable: true，输入“北京”或“西湖”筛选服务点。默认搜索节点标签与父级标签；选中结果后，下方展示绑定路径。

正在加载示例…

<template>
  <avue-form v-model="form" :option="option" />
  <form-demo-result :value="result" hint="输入“北京”可匹配其下所有服务点；输入“西湖”匹配具体服务点。" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';
import { regions } from '../_shared/useDictionaryMock';

const form = ref({ location: [] });
const result = computed(() => ({ location: form.value.location }));
const option = {
  menuBtn: false,
  column: [{
    label: '服务点', prop: 'location', type: 'cascader', span: 24,
    props: { label: 'name', value: 'code' }, dicData: regions,
    filterable: true, placeholder: '输入北京或西湖搜索',
  }],
};
</script>

搜索范围还受 showAllLevels 影响：仅显示最后一级时，默认只按末级标签匹配。懒加载场景只能搜索已加载的节点；跨全量数据搜索需要业务接口支持。

自定义模版

效果预览可直接操作下方示例

使用字段 prop 名称加 Type 的插槽定制选项内容，例如追加数量信息。字段绑定值与字典结构保持原配置。

正在加载示例…

<template>
  <avue-form :option="option">
    <template #cascader-type="{ node, data }">
      <span>{{ (data || {}).label }}</span>
      <span v-if="!node.isLeaf"> ({{ ((data || {}).children || []).length }}) </span>
    </template>
  </avue-form>
</template>

<script setup>
import { ref } from 'vue';

const dic = [
  {
    value: 'zhinan',
    label: '指南',
    children: [
      {
        value: 'shejiyuanze',
        label: '设计原则',
        children: [
          { value: 'yizhi', label: '一致' },
          { value: 'fankui', label: '反馈' }
        ]
      }
    ]
  }
];

const option = ref({
  column: [
    {
      label: '级联',
      prop: 'cascader',
      type: 'cascader',
      dicData: dic
    }
  ]
});
</script>

懒加载

设置 lazy: true 后，通过 lazyLoad(node, resolve) 按层提供子节点。根节点的 level 为 0；返回项用 leaf: true 标识末级，避免继续加载。

效果预览可直接操作下方示例

依次展开大区、站点、服务点，观察加载记录只包含已展开的层级。此处同步返回固定数据；接入接口时在请求成功后调用 resolve(list)，失败或无数据时调用 resolve([])，让加载状态结束。

正在加载示例…

<template>
  <avue-form v-model="form" :option="option" />
  <form-demo-result title="当前值与按层加载记录" :value="result" />
</template>

<script setup>
import { computed, ref } from 'vue';
import FormDemoResult from '../_shared/FormDemoResult.vue';
import { getRegionChildren, regionOptions } from '../_shared/useDictionaryMock';

const form = ref({ location: [] });
const loads = ref([]);
const result = computed(() => ({ location: form.value.location, loads: loads.value }));
const option = {
  menuBtn: false,
  column: [{
    label: '服务点', prop: 'location', type: 'cascader', span: 24,
    props: { label: 'name', value: 'code' }, lazy: true,
    lazyLoad(node, resolve) {
      const level = node.level;
      const parentCode = node.data?.code || '';
      const list = level === 0 ? regionOptions : getRegionChildren(parentCode);
      loads.value = [{ level, parentCode: parentCode || '根节点', count: list.length }, ...loads.value].slice(0, 8);
      resolve(list.map((item) => ({ ...item, leaf: level >= 2 })));
    },
  }],
};
</script>

异步请求应处理失败并避免组件卸载后继续更新示例状态。每次加载调用一次 resolve，不要漏掉空数据分支。