企业官网建设流程全解析

写这种级联组件的动态加载，最怕的不是不会写，而是写了之后各种莫名其妙的问题：数据不显示、选不中、控制台报错、请求被发出去好几次。我在项目里被 el-cascader 折磨过好几轮，后来把动态加载的机制和常见的报错场景理清楚之后，再做类似需求就顺手多了。这篇文章就把我实际用 Element 的 el-cascader 做动态加载的完整思路、代码、以及排错过程整理出来，希望能帮你省下几个加班的夜晚。

如果你是刚接触 Vue 和 Element 的开发者，或者被 el-cascader 的 lazyload 搞到一头雾水，这篇文章都适用。我会先讲清楚动态加载的数据流，再给完整可跑的示例代码，最后把报错问题按场景拆开，逐个告诉你为什么会报错，以及怎么处理。

1. 为什么 el-cascader 需要动态加载——先搞清楚它的数据流

1.1 静态数据 vs 动态加载：你该怎么选

大多数组件库里的级联选择器，最简单用法是直接传一个options数组。数据结构大概是这样的：

[ { value: 'zhejiang', label: '浙江', children: [ { value: 'hangzhou', label: '杭州', children: [] } ] } ]

这种方式在数据量小、层级固定、一次能全部返回的时候很省事。但真实业务里经常不是这样：省市区三级数据可能几万条，或者每个下级节点要按用户输入动态查询，一次全量返回要么接口太慢，要么数据太大导致页面卡顿。更重要的是，有些业务的下级数据是依赖上级选中的ID去查询的，根本就无法提前拿到完整的树。

这时候就需要“按需加载”——用户点击某个节点时，才去请求它的下级数据。el-cascader 里对应的能力就是lazyLoad，它和lazy: true配合使用。我一开始总以为动态加载很神秘，搞懂之后发现，它的本质就是：组件在需要展开一个节点时，主动调用你提供的函数，你在这个函数里resolve返回子节点数据，组件负责渲染。

1.2 动态加载的核心机制：lazyLoad 与 lazy

先看最基础的模板写法：

<template> <el-cascader v-model="selectedValue" :props="cascaderProps" style="width: 100%" /> </template> <script> export default { data() { return { selectedValue: [], cascaderProps: { lazy: true, lazyLoad: this.loadNode } }; }, methods: { loadNode(node, resolve) { // 在这里处理加载逻辑 } } }; </script>

这里有两个关键点要注意。

第一，lazy是props里的属性，不是直接写在 el-cascader 标签上的。很多人刚上手时会把它放在组件属性上，结果发现不生效。

第二，lazyLoad接收两个参数。第一个参数node是当前要加载子节点的节点对象，第二个参数resolve是一个回调函数，你必须调用它，并把子节点数组传给它。不传或者不调用，组件就会一直转圈。

node对象里有几个常用属性：level表示当前层级，根节点是 0；root表示根节点对象；data表示当前节点对应的数据；isLeaf表示当前节点是否叶子节点。后面写加载逻辑时基本离不开这几个。

2. 动态加载组件的完整落地步骤

2.1 基础结构搭建：从模板到 props

动态加载级联的模板部分和普通 cascader 没什么区别，核心在props配置。我通常会把 props 单独提出来，避免在模板里堆太多逻辑。

<template> <el-cascader v-model="selectedValue" :props="cascaderProps" :clearable="true" placeholder="请选择地区" /> </template> <script> export default { data() { return { selectedValue: [], cascaderProps: { lazy: true, lazyLoad: this.loadNode, // 如果有特殊字段名，在这里映射 value: 'value', label: 'label', children: 'children', // 是否叶子节点的判断字段，默认会去看 children 是否为空 leaf: 'leaf' } }; } }; </script>

leaf字段值得单独说。动态加载时，组件如何判断当前节点要不要继续渲染成“可展开”状态？默认情况是：如果当前节点的children存在且长度为 0，就认为是叶子节点；如果children为 undefined，就会认为还有下级，会显示为可展开。在很多动态加载场景下，你的接口返回的子节点数组本身就是有限的，哪怕真的有“更多下级”，你也不能直接给children塞一个空数组，否则组件会把它当成叶子节点，导致点不开。稳妥的做法是：让后端返回一个leaf字段，或者在前端根据业务规则自行计算。

比如后端约定的返回结构是：

{ "code": 0, "data": [ { "id": 1001, "name": "浙江省", "hasChildren": true } ] }

那么你的 props 要这么配：

cascaderProps = { lazy: true, lazyLoad: this.loadNode, value: 'id', label: 'name', leaf: 'hasChildren' };

注意这里的leaf字段名要配合接口返回的字段名。如果接口返回的是hasChildren: true，那就表示它还有子节点；如果返回hasChildren: false，就表示它是叶子。这个字段的值必须是布尔值，不要传字符串"false"，否则会判定错误。

2.2 分支加载逻辑：如何判断叶子节点

loadNode方法的通用写法，我一般分三层：

1. 根节点加载：当node.level === 0，请求第一级数据。
2. 中间层级加载：根据node.data里保存的ID或参数，请求当前节点的下级。
3. 叶子判断：根据后端返回的hasChildren或leaf字段，决定返回的每个节点是否还能继续展开。

具体代码：

methods: { async loadNode(node, resolve) { // 根节点 if (node.level === 0) { try { const res = await fetchRegionList({ parentId: 0 }); const nodes = res.data.map(item => ({ value: item.id, label: item.name, hasChildren: item.hasChildren, // 这里不能写 children: []，否则会被认为是叶子节点 // 可以写成 children: undefined，或者干脆不写 })); resolve(nodes); } catch (error) { // 加载失败也要 resolve，否则组件一直 loading resolve([]); } return; } // 非根节点 const parent = node.data; try { const res = await fetchRegionList({ parentId: parent.value }); const nodes = res.data.map(item => ({ value: item.id, label: item.name, hasChildren: item.hasChildren })); resolve(nodes); } catch (error) { resolve([]); } } }

这里有个很重要的点：loadNode里的resolve一定要在所有路径上都执行到。哪怕接口报错了，也要resolve([])，否则组件里那个节点的 loading 状态永远不会结束。我在开发时曾经因为忘了在catch里resolve，导致点一次没反应，再点一次直接卡死，控制台没有任何报错，排查了很久才发现是这里的问题。

还有一个容易被忽略的细节：node.data在根节点时是undefined，所以非根节点的加载逻辑必须放在根节点判断之后。如果你直接访问node.data.value，会报Cannot read property 'value' of undefined。这个错误后面会专门说。

2.3 回显与默认值：动态加载最容易被坑的地方

动态加载的级联组件，如果只是“点选”，问题不大。麻烦的是编辑场景下需要回显，比如修改表单时，后端返回一个['330000', '330100', '330106']这样的值数组，你需要让 cascader 正确显示对应的文字。

因为 el-cascader 是懒加载的，组件手里根本没有完整的树，它拿到 value 之后并不知道每个节点的 label 是什么。这时候通常有两种处理方式。

第一种，也是最推荐的：在回显前把完整路径的节点数据准备好，用一个“预加载”的方式走一遍 lazyLoad。但这个实现起来比较繁琐，要模拟点击路径。

第二种，用 Element 提供的cascaderRef实例方法？实际上 Element UI 的 el-cascader 并没有一个公开的“根据值加载路径”的接口。比较常见的方法是：在回显时，先把默认值对应的完整路径给组件，同时确保路径上的节点都已经被加载过。

我实际项目中用的方案是：后端在返回编辑详情时，除了返回 value 数组，还会返回一份完整的“文本路径数组”，比如：

editData = { areaValue: ['330000', '330100', '330106'], areaLabels: ['浙江省', '杭州市', '西湖区'] }

然后我在初始化时，用这个 labels 拼接出显示文本，直接放在表单里显示，而不依赖 el-cascader 自己去回显。如果业务上必须让 cascader 自己回显，就只能提前把所有路径上的节点都 resolve 出来，再把v-model赋值。

Element Plus 版本对动态回显有一些改进，但也不是开箱即用。后面我会在版本差异部分展开。

3. 报错排查：动态加载中我踩过的坑

3.1 “Cannot read property 'level' of undefined” 类问题

这是动态加载最经典的报错。我先描述一下场景：页面初始化时，cascaderProps里的lazyLoad方法用了this，但是在 props 初始化时this指向不对；或者你在loadNode里访问了node.level，但某些情况下node是 undefined。

Cannot read property 'level' of undefined还有一种触发情况：在data里初始化cascaderProps时，你直接写了：

data() { return { cascaderProps: { lazy: true, lazyLoad: (node, resolve) => { this.loadNode(node, resolve); // this 指向有问题 } } }; }

如果data()执行时，this并不是 Vue 实例（某些场景下确实会这样），箭头函数里的this就会捕获到错误作用域。解决办法是把lazyLoad指向一个定义在methods中的方法，像前面那样写成：

cascaderProps: { lazy: true, lazyLoad: this.loadNode }

这里有个细节：在data()中直接用this.loadNode是能拿到 methods 里的方法的，因为 Vue 初始化时会先把 methods 挂载到实例上。但如果你在某处把这个cascaderProps又赋值给别人，或者解构出来使用，this就丢了。稳妥起见，可以把loadNode的定义改为普通函数并在方法内部不依赖this，或者用箭头函数定义loadNode来固定this。

还有一个小坑：如果你在loadNode里使用了node.root，请确认是node.root而不是node.$root。Element 的级联组件节点对象上只有一个root属性，我记得早期版本有些文档里写过别的字段，容易让人踩坑。

3.2 无限加载或重复请求问题

动态加载时，点击一个节点，接口被调用了两三次，甚至一直转圈加载下一层，这种问题通常有两个原因。

第一个原因是每次点击都重复触发lazyLoad。Element 的 cascader 内部有节点状态管理，正常情况下一个节点加载完就不会再重复加载。但如果你在resolve之前就修改了组件外部的响应式数据，或者用了强制刷新的方式，可能会导致状态丢失，触发重复加载。我的经验是：不要在loadNode里同步修改selectedValue，也不要在lazyLoad里对node.data做响应式变更，比如Vue.set或this.$set。

第二个原因是leaf字段配置不对。如果接口返回的hasChildren字段一直是true，即使某节点已经是叶子节点，组件判断它还有下级，用户点击后又继续发请求，但后端返回空数组，然后组件可能又尝试继续加载，循环就开始了。正确做法是让后端保证hasChildren准确，或者前端根据业务逻辑二次计算。比如当节点是第三级时，强制把hasChildren设为false：

const isLeaf = item.level >= 3 || !item.hasChildren;

3.3 选中值不显示的排查

点选后，v-model里有值，但输入框里不显示对应文本，这个现象通常发生在动态加载的叶子节点数据没有正确匹配时。原因可能是你返回的节点数据里value字段和父级value重复了，或者value不是唯一值。

el-cascader 选中后要通过 value 去找到路径上的所有节点，才能拼接 label。如果某个层级节点数据丢失了，组件就无法显示完整文本。常见场景是：选中一个节点后，父级节点已经被清除，或者数据被重新加载，导致路径断裂。

解决办法是在loadNode中返回数据时，确保value唯一，并且不要随意清空options相关的数据源。如果使用了:options和lazy同时存在，也可能导致状态冲突，尽量只使用一种方式。

3.4 常见错误速查表

我在项目里整理过一个速查表，按症状、可能原因、解决办法三列来看，排查效率会高很多。

4. 实战：一个省份-城市-区县动态加载案例

4.1 需求描述与接口约定

假设我要做一个行政区划选择器。接口约定如下：

• GET /api/region/list，参数parentId
• 第一级传入parentId=0，返回所有省
• 第二级传入省 id，返回该省的城市
• 第三级传入城市 id，返回区县
• 每个节点返回id、name、hasChildren三个字段，其中hasChildren表示是否还有下级

这个需求可以说是动态加载最典型的应用。我不会依赖所有数据一次性加载，而是每次只请求一个节点的下级。

4.2 完整代码实现

这里我用 Vue 2 + Element UI 的写法，Element Plus 的逻辑也基本一致，后面会说明差异。

<template> <div class="region-select"> <el-cascader v-model="selectedValue" :props="cascaderProps" :clearable="true" filterable placeholder="请选择省/市/区" style="width: 320px" /> </div> </template> <script> import { fetchRegionList } from '@/api/region'; export default { name: 'RegionSelect', data() { return { selectedValue: [], cascaderProps: { lazy: true, lazyLoad: this.loadNode, value: 'id', label: 'name', leaf: 'hasChildren' } }; }, methods: { async loadNode(node, resolve) { try { let parentId = 0; if (node.level > 0 && node.data) { parentId = node.data.id; } const res = await fetchRegionList({ parentId }); if (res.code !== 0) { console.error('区域加载失败', res.msg); resolve([]); return; } const nodes = res.data.map(item => ({ id: item.id, name: item.name, hasChildren: !!item.hasChildren })); // 如果当前已经是第三级，强制叶子节点，避免出现第四级加载 if (node.level >= 2) { nodes.forEach(item => { item.hasChildren = false; }); } resolve(nodes); } catch (error) { console.error('加载区域数据异常：', error); resolve([]); } } } }; </script>

这段代码有几个细节：

1. parentId从 0 开始，根节点加载。
2. 通过node.level判断层级，第三级强制hasChildren = false，防止后端数据不准多出来不必要的第四级。
3. 所有异常路径都resolve([])，避免组件卡 loading。

4.3 与后端联调时的注意事项

和后端对接动态加载接口时，最容易出现的问题不是接口本身，而是字段语义不统一。

hasChildren的语义必须明确：它表示“当前节点还有没有下级”，而不是“当前节点有没有下级数据”。有些后端会把“有下级”和“有 children 字段”混用，结果返回了children: []或者干脆不返回，前端判断起来就很痛苦。

我建议在联调前和后端约定一份统一的返回结构：

{ "code": 0, "msg": "success", "data": [ { "id": 110000, "name": "北京市", "hasChildren": true } ] }

另外，如果点击某个节点后发现请求根本没发出，先看浏览器 Network 面板有没有请求。没有请求说明lazyLoad逻辑没走，可能还是lazy没配好。有请求但返回慢，那就是接口性能问题，和组件无关。

接口并发也要注意。用户快速连续点击多个节点时，请求可能乱序，导致后一次请求比前一次先返回，渲染出错误的数据。解决方式通常有两种：一是前端加请求序列控制，二是后端保证接口响应速度足够快。组件本身不会帮你处理这种竞态问题。

5. 进阶优化与性能建议

5.1 缓存已加载节点

动态加载虽然避免了全量渲染，但同一个节点如果被反复展开，每次都去请求接口，体验并不好。最简单的优化是加一个缓存，把已经加载过的parentId对应的节点列表存起来。

data() { return { nodeCache: {} }; }, methods: { async loadNode(node, resolve) { let parentId = 0; if (node.level > 0 && node.data) { parentId = node.data.id; } if (this.nodeCache[parentId]) { resolve(this.nodeCache[parentId]); return; } try { const res = await fetchRegionList({ parentId }); // ...处理数据... this.nodeCache[parentId] = nodes; resolve(nodes); } catch (error) { resolve([]); } } }

注意：缓存的数据一定不能带children: []，否则叶子判断会出错。我通常只缓存{ id, name, hasChildren }这样的纯节点信息，不包含组件运行时添加的状态。

5.2 加载状态与用户体验

动态加载时，网络慢的情况下用户点开节点，会有一段空白时间。Element 的级联面板里默认会有一个 loading 动画，但不是特别明显。如果希望体验更好，可以结合业务做一层“展开时提示”。

另外，每次接口失败后，我建议在页面上 Toast 或者 message 弹出错误，而不是只在控制台打印。因为用户不会打开控制台，但如果界面没有任何反馈，他会以为组件坏了。我自己的习惯是，在 catch 里加一个this.$message.error('区域加载失败，请重试')。

5.3 大数据量下的替代方案

如果你的数据是真的巨大，比如全国小区级地址，几千上万个节点，el-cascader 的动态加载也只是解决“不一次性请求所有数据”的问题，但下拉面板本身渲染大量已加载节点时仍然可能卡顿。这时候有两个方向：

一是把组件换成支持虚拟滚动的级联选择器，比如自研，或者使用其他专门针对大数据量优化的组件库。二是改变交互方式，不用级联，改成三个独立的下拉选择器，省市区联动。后者在很多后台系统里更常见，性能也更可控。

我在实际项目中就遇到过一个需求，动态加载省市区完全够用，但加载到街道层级后，某个市下面有上千个街道，此时 el-cascader 面板展开会有明显掉帧。最后和产品沟通后改成了三个独立 select，体验反而更好。

5.4 Element UI 与 Element Plus 的版本差异

Element UI（Vue 2）和 Element Plus（Vue 3）在 el-cascader 的用法上大部分一致，但有几个差异需要留意。

第一，Element Plus 中lazyLoad的resolve行为基本一样，但组件内部对leaf字段的判断更严格。如果你在 Element Plus 里发现节点明明配置了leaf: false还是无法展开，先确认版本，2.x 之后对leaf的处理有一些调整。

第二，Element Plus 的el-cascader支持:before-filter等新属性，如果你用了filterable，要注意过滤时动态加载的数据可能不会被过滤。因为懒加载模式下，组件只对已加载的数据做匹配。

第三，Element Plus 的回显问题比 Element UI 有改善，在设置v-model时，如果值对应的节点已经被加载过，通常能正确显示；但如果没加载过，依然需要手动处理。

第四，Vue 3 的响应式机制让node对象里的数据可能是 proxy 包装过的，打印出来不像普通对象。如果你在loadNode里直接修改node.data的某个字段，可能会触发警告。尽量只读，不要改。

6. 扩展玩法：动态加载 + 其他组件联动

6.1 与表单校验联动

动态加载的级联值通常需要参与表单校验。Element 的el-form对el-cascader的校验是直接校验v-model绑定的值。这个值是一个数组，比如['330000', '330100', '330106']，校验规则里用type: 'array'就行。

rules: { region: [ { type: 'array', required: true, message: '请选择地区', trigger: 'change' } ] }

如果遇到“明明选了值但校验不过”的情况，检查v-model的值是否是数组，有些场景下你绑定成字符串'330000,330100,330106'，校验就识别不了。

6.2 与关系图谱/上钻下钻结合的思路

我看到有些场景里会把 el-cascader 动态加载和 relation-graph 这种关系图谱组件结合，实现“上钻下钻动态加载数据”。思路其实类似：图谱点击某个节点时，按当前节点 ID 动态请求下一层数据；上钻时回到父级节点重新加载。el-cascader 在这里更多是作为“路径选择器”来提供当前链路，方便用户知道自己在图谱中的位置。

如果你的项目也有这种需求，建议把动态加载数据的方法抽成一个公共函数，既提供给 cascader 用，也提供给图谱点击事件用，避免两套逻辑不一致。我实践下来，这样维护成本最低。

6.3 懒加载与搜索的取舍

filterable是很多人喜欢开的属性，但动态加载模式下，搜索也只会搜到“已经加载过”的节点。比如你还没展开“浙江省”，直接搜“杭州”是搜不到的。这个限制是由懒加载的本质决定的，组件不可能把所有未加载的数据都拿去搜索。

如果你的业务必须支持全局搜索，那就不能只靠 el-cascader 的动态加载，需要额外做一个搜索接口，并把搜索结果转成可选值。我做过一个方案是：输入关键字时，请求一个“模糊搜索区域”接口，拿到命中的路径数组，然后通过 cascader 的v-model直接赋值并显示。这种方式能绕过懒加载的搜索限制，但需要后端配合。

6.4 二次封装建议

如果项目里多处用到了动态加载级联，我建议封装成一个业务组件，把接口请求、缓存、错误处理、回显逻辑全部收敛到组件内部。对外只暴露v-model和一个loadData的 props 方法。这样调用方不用关心内部是 Element 还是其他组件库，也方便后续替换。

我在公司内部就是按这个思路封装的，大概长这样：

<template> <el-cascader v-model="innerValue" :props="innerProps" @change="handleChange" /> </template> <script> export default { props: { value: { type: Array, default: () => [] }, loadData: { type: Function, required: true } }, data() { return { innerValue: this.value, innerProps: { lazy: true, lazyLoad: this.handleLoadNode } }; }, methods: { handleLoadNode(node, resolve) { this.loadData(node, resolve) .then(data => resolve(data)) .catch(() => resolve([])); }, handleChange(val) { this.$emit('input', val); this.$emit('change', val); } }, watch: { value(val) { this.innerValue = val; } } }; </script>

这样封装之后，业务方只需要提供loadData函数，具体接口请求逻辑由业务自己控制，组件只负责把数据交给 el-cascader。后面即使 el-cascader 出了新坑，也只需要在组件内部修。

7. 写在最后的避坑心得

我再分享几个自己长期使用 el-cascader 动态加载的切身体会。

第一，遇到问题先打开控制台看resolve到底有没有被调用，这是排查一切动态加载问题的首要步骤。很多异常表面上是组件 bug，实际上是你自己某个分支漏了resolve。

第二，不要过度依赖组件内部自动判断叶子节点。后端能返回hasChildren就用这个字段，返回不了就靠层级强判，千万不要让组件去猜。

第三，缓存对体验提升非常明显。同一次页面生命周期内，已经加载过的省市区数据没有必要重复请求。尤其是一些公共基础数据，甚至可以放到全局 store 里共享。

第四，Element UI 和 Element Plus 的报错信息都不算特别友好，遇到读不懂的错误，优先检查自己传给props的字段有没有拼写错，其次检查数据结构是否符合预期。我碰到的绝大多数问题，最后都出在数据和配置上。

动态加载本身不复杂，把数据流理顺，把错误分支都处理好，稳定性就能上来。希望这篇文章能让你少走一些弯路。