做地址级联选择的时候，大多数项目都是省市区三级就收工了，但真做到政企后台、网格化管理、物流配送末端网点这类场景，你就会发现第四级（街道/乡镇）压根绕不开。刚接手这个需求时我也觉得“不就多一级嘛”，等真正动手才发现：数据量、加载策略、回显逻辑、联动时序，全都跟着变了。这篇文章就把我从三级改成四级的完整折腾过程拆开讲，包括数据结构怎么组织、Vue 组件怎么写、踩了哪些坑。
1. 四级联动到底在解决什么实际问题
很多同学觉得省市区三级已经够了，这种想法在 C 端营销页、简单表单里确实成立，但放到真正的业务系统里，第四级“街道/乡镇/开发区”往往是刚需。
1.1 哪些场景必须用到第四级
- 政企与基层治理类系统：网格化管理、人口普查登记、村委会/居委会信息维护，地址精确到街道甚至社区是硬性要求。
- 物流与供应链场景：末端配送网点划分、运费计算规则、车辆调度范围判定，全依赖四级地址的归属关系。
- 电商与本地生活服务：门店选址、配送范围判断、区域库存配置，都要求客户选到街道级，不然系统没法做“是否在配送范围内”的判定。
- 财务报表与抵扣场景：某些发票开具、税务登记信息里，地区类别需要细化到街道级，后台录入时就必须强制用户选到第四级。
说白了，第四级不是设计者多此一举，而是下游业务系统需要这一个细粒度的“归属地编码”。如果前端只给到区县，后端往往得再拿区县编码去反查街道列表，一来多一次请求，二来还得处理“区县编码下没有街道数据”的边界情况，反而更麻烦。
1.2 从三级升四级的核心变化点
三级联动大家都会写，父级变化时重新拉取子级数据就行。但升到四级后有三个容易忽略的变化：
- 数据量指数级上涨：全国县级行政区约 2800 多个，但街道/乡镇级是数万个量级，一次性全量挂载在前端不现实。
- 编码维度变长：行政区划编码通常是 6 位，前两位是省，三四位是市，五六位是区县。而街道级在国标里会用 9 位或 12 位编码，或者业务系统自定义扩展位，数据模型上要提前预留。
- 加载策略必须分层：省级数据量小可以全量加载，到了街道级必须懒加载或按需分页，才有较好的首屏体验。
2. 数据模型设计：先把地基打好再谈组件
我见过不少项目一上来就写组件，写到一半发现接口返回的数据格式跟组件预期对不上，又回头折腾数据层。地址联动这种场景，数据结构几乎决定了组件做起来顺不顺手。
2.1 树形结构 vs 扁平结构怎么选
两种方案各有适用场景，这里直接给结论：
- 全量树形结构：适合省市两级、最多到区县，数据量小，组件内部递归读取子节点就行。缺点是街道级数据全量挂成树，初始化时内存占用大、同步时间不可控。
- 扁平结构 + parentId + 按需过滤：适合四级甚至更深层级。后端接口按 parentId 加载子级，前端只需要维护一个“当前已加载的节点池”，联动逻辑天然清晰。
我最后采用的是扁平结构 + 按需请求的方案。核心数据模型长这样：
// 统一的节点结构 { code: '110105', // 节点编码 name: '朝阳区', // 节点名称 parentCode: '110100', // 父级编码，根节点为空 level: 3, // 层级，1省 2市 3区县 4街道 leaf: false // 是否叶子节点 }这个结构的好处是，无论级别多少，组件拿到的都是同一套数据形状。渲染某一列时，只需要用当前选中节点的code去请求子级数据，或者在已加载池里用parentCode过滤。
2.2 第四级编码与国标高危注意点
初期我犯过一个错，直接拿行政区划 6 位编码当唯一标识，结果到了街道级，后台返回的数据编码居然有的 9 位、有的 12 位，还有的是纯业务自定义编码。后来统一约定：
- 前端组件层不关心编码长度，只把
code当成不透明字符串处理。 - 后端保证每个节点的
code在全量数据中唯一，并且父级编码正确指向。 - 新增“扩展编码段”时不需要改前端组件，只要表结构里预留
parentCode字段就行。
2.3 本地模拟数据的组织方式
如果没有现成接口，开发阶段可以先用静态 JSON 模拟四级数据。这里给出一个最小可用的模拟结构，方便先跑通联动逻辑：
[ { "code": "11", "name": "北京市", "parentCode": "", "level": 1, "leaf": false }, { "code": "1101", "name": "市辖区", "parentCode": "11", "level": 2, "leaf": false }, { "code": "110105", "name": "朝阳区", "parentCode": "1101", "level": 3, "leaf": false }, { "code": "110105001", "name": "望京街道", "parentCode": "110105", "level": 4, "leaf": true } ]模拟数据的关键点有两个：一是每个节点的parentCode必须精确指向上级，二是level字段要跟真实接口对齐，方便后面切接口时只改数据源不改组件逻辑。
3. Vue 组件实现：四级联动的核心逻辑拆解
数据模型想清楚了，组件层就是水到渠成的事。下面按实现顺序拆解每个核心环节，包括组件设计、联动逻辑、异步处理。
3.1 组件对外参数设计
组件通过v-model对外暴露选中值，同时接收一个数据源加载函数。核心 props 和事件定义如下：
<template> <div class="city-cascader"> <div class="cascader-panel" v-show="visible"> <div v-for="(column, columnIndex) in columns" :key="columnIndex" class="cascader-column" > <div v-for="node in column" :key="node.code" class="cascader-node" :class="{ active: node.code === selectedCodes[columnIndex], disabled: node.disabled }" @click="onNodeClick(node, columnIndex)" > {{ node.name }} </div> </div> </div> </div> </template>props: { // 异步加载函数，接收父级编码，返回子级数组 loadData: { type: Function, required: true }, // 是否多选 multiple: { type: Boolean, default: false }, // 默认选中值，支持数组 ['11', '1101', '110105', '110105001'] modelValue: { type: Array, default: () => [] } } emits: ['update:modelValue', 'change']组件内部维护的关键状态：
columns：二维数组，每一列代表一级面板的数据。selectedCodes：当前每一列选中的编码。loading：是否正在请求子级数据。
3.2 联动的核心逻辑：父级变化触发子级加载
只要你选中的父级变了，后续所有列都要重建。这里最稳妥的做法是：先清空后面所有列的数据，再加载下一级。
async function onNodeClick(node, columnIndex) { // 如果点击的是当前列已选中的节点，可以取消选中，也可以忽略 if (selectedCodes.value[columnIndex] === node.code) return; // 更新选中状态，并截断后面的层级 selectedCodes.value = selectedCodes.value.slice(0, columnIndex); selectedCodes.value[columnIndex] = node.code; // 清空被截断的列 columns.value = columns.value.slice(0, columnIndex + 1); // 触发 change 事件 emit('change', { codes: selectedCodes.value, labels: getSelectedLabels() }); // 如果不是叶子节点，加载下一级 if (!node.leaf) { await loadNextLevel(node, columnIndex + 1); } } async function loadNextLevel(parentNode, nextColumnIndex) { loading.value = true; try { const children = await props.loadData(parentNode.code); // 把新列插入到 columns 中 columns.value[nextColumnIndex] = children || []; // 如果有默认值需要继续展开，这里可以递归调用 if (defaultValues.value[nextColumnIndex]) { const defaultNode = columns.value[nextColumnIndex].find( item => item.code === defaultValues.value[nextColumnIndex] ); if (defaultNode) { await onNodeClick(defaultNode, nextColumnIndex); } } } finally { loading.value = false; } }这段代码里最关键的一行是selectedCodes.value = selectedCodes.value.slice(0, columnIndex)。它保证你重新选择省级的时候，后面市级、区县级、街道级全部重置，不会出现“选了广东省，结果还保留着北京市下面的海淀区”这种脏数据。
3.3 数据加载的并发与竞态处理
异步加载天然有竞态问题。比如用户快速点了“北京市”再点“上海市”，第一次请求可能还没回来，第二次请求已经发出去了。等第一次响应返回时，很可能把第二次的结果覆盖掉，界面就乱了。
我的处理方案也很简单：每次加载子级时记一个自增请求序号，回来的时候只认最新的序号。
let requestSeq = 0; async function loadNextLevel(parentNode, nextColumnIndex) { const seq = ++requestSeq; loading.value = true; try { const children = await props.loadData(parentNode.code); if (seq !== requestSeq) return; // 过期请求，丢弃 columns.value[nextColumnIndex] = children || []; } finally { if (seq === requestSeq) loading.value = false; } }这种做法在“接口慢 + 用户手快”的场景下非常有效，比做取消请求简单得多，而且逻辑不容易出错。别忘了，用户切了省级马上再切市级时，省级的子级加载如果还没完成，也会被这个机制拦截掉，不会影响市级列的数据。
3.4 回显默认值时的异步展开
编辑场景下，后端传回来的值是完整的四级编码数组，比如['11', '1101', '110105', '110105001']。组件要做的是打开面板时逐级异步展开，同时默认选中对应节点。
这个地方容易踩坑：如果你一股脑平行请求四级数据，可能每一级接口都返回了，但因为异步回传顺序不定，最终 panel 列的顺序会错乱。正确做法是逐级展开，上一级找到默认节点后再请求下一级：
async function initByDefaultValues(codes) { // 逐级展开：省 -> 市 -> 区 -> 街道 for (let i = 0; i < codes.length; i++) { const parentCode = i === 0 ? '' : codes[i - 1]; const nodes = await props.loadData(parentCode); const target = nodes.find(node => node.code === codes[i]); if (!target) break; columns.value[i] = nodes; selectedCodes.value[i] = target.code; if (!target.leaf && i < codes.length - 1) { // 继续下一级 continue; } else { break; } } }初始化这个操作建议放在组件的mounted里，或者在watch到modelValue变化的时候触发。切记不要在初始化完成之前允许用户点击，否则用户操作和回显逻辑会互相打架。
4. 交互体验与细节打磨：让组件真正能用
逻辑层面跑通后，剩下的就是交互体验。地址联动组件看着简单，但实际用起来，大量细节决定了一个组件是“能用”还是“好用”。
4.1 点击已选中的父级时要不要清除子级
这是个很微妙的交互点。有的设计是点击已选中父级直接取消选中，同时清除后面的所有子级；有的设计是点击已选中父级不做任何操作，避免误点导致数据清空。
我的建议是：已经选中的父级再次点击，保持选中状态，不触发任何操作。因为地址选择往往是“改一个值”，而不是高频反复切换，误触带来的成本比多切一次的繁琐更高。
但如果你的业务要求支持清空操作，别靠“点击已选中项”来实现，单独提供一个清空按钮或者触发表单重置更稳妥，免得用户分不清是“没点中”还是“组件坏了”。
function onNodeClick(node, columnIndex) { // 已选中的节点再次点击，不处理 if (selectedCodes.value[columnIndex] === node.code) { return; } // 正常联动逻辑... }4.2 加载中的反馈状态
第四级在网速一般的时候，请求时间完全不可控。如果点了省之后界面毫无反馈，用户会以为组件卡死。我至少做了两件事：
- 在请求下一级期间，当前列底部展示一个轻量的加载提示区。
- 在请求超时或报错时，给列内展示重试按钮，而不是直接甩一个空白列。
展示加载提示的代码很简单：
<div class="cascader-column"> <div v-for="node in column" :key="node.code" class="cascader-node" > {{ node.name }} </div> <div v-if="loading && loadingColumnIndex === columnIndex" class="cascader-loading"> 加载中... </div> </div>这个加载状态的粒度是“列级”，不是整个组件级。否则用户在第一列点完省，因为省数据早已加载完，却要等市级接口返回才能继续操作第二列，体验会非常笨重。
4.3 搜索与模糊匹配的加装思路
很多后台系统的地址选择器，用户不一定按层级去找，而是希望直接输入“朝阳”就能定位。这个功能可以基于已加载的节点数据做前端过滤，也可以让后端提供一个searchAddress(keyword)的接口。
如果做纯前端搜索，注意规模问题：街道级几万个节点，每次输入都做全量筛选，性能撑不住。我的优化思路是做一个防抖搜索，请求接口时把 keyword 传过去，后端直接返回匹配到的节点列表，前端再按命中项的用户点击目标去自动展开对应层级，效率比前端硬扛高很多。
function handleSearch(keyword) { if (!keyword) return; // 防抖 300ms clearTimeout(searchTimer); searchTimer = setTimeout(async () => { const results = await props.searchAddress(keyword); searchResults.value = results; }, 300); }搜索结果展示后，用户点击某一条，组件需要拿到它的code和祖先链，然后调用initByDefaultValues展开面板到对应层级。这个过程依然依赖逐级展开逻辑，只是触发点从默认值变成搜索结果。
4.4 键盘操作与无障碍支持
给地址联动加键盘操作有一定成本，但很多后台管理系统都有无障碍评审，组件完全无法用 Tab 键和 Enter 键操作会被判定不合规。
最轻量的实现方案：每个节点渲染成button元素，天然支持 Tab 聚焦和 Enter 触发。样式上重新设置一下就行，收益非常大。
<button v-for="node in column" :key="node.code" type="button" class="cascader-node" @click="onNodeClick(node, columnIndex)" > {{ node.name }} </button>4.5 移动端适配
虽然四级地址多用于后台，但总有需要在手机上录入的场景。移动端的核心问题是横向空间不够，四级面板如果全部横排，一屏根本放不下。
常见做法是改成底部弹层 + 每列独立滑动选择，类似时间选择器；或者做“面包屑 + 单列列表”的钻取模式，先选省，进入下一级选市，再进入下一级选区，逐级向下钻。
我实际落地过钻取模式，逻辑非常直观，就是把columns改成一个当前正在显示的单列：
<template> <div class="drill-panel"> <div class="breadcrumb"> <span v-for="(item, index) in selectedCodes" :key="index" @click="backToLevel(index)"> {{ selectedLabels[index] }} </span> </div> <div v-for="node in currentColumn" :key="node.code" class="drill-node" @click="onDrillNodeClick(node)"> {{ node.name }} </div> </div> </template>钻取模式需要维护一个currentLevel变量，点击某一级的面包屑就回退到那一级重新展示。这个模式在 PC 上也能用，具体选哪种，看你的用户习惯。
5. 常见问题与性能优化实录
从三级升四级的过程中，各种怪问题没少遇到。这部分整理几个高频问题，附带排查思路和解决方案，觉得有用的可以直接抄。
5.1 切换父级后，子级数据残留
现象：重新选择省级后，市级列和区县级列还残留着上一次的数据。
原因：联动逻辑里只更新了当前列，没有截断后面的列。
解决：严格按照前面onNodeClick里的逻辑，先slice截断selectedCodes和columns，再加载新一级数据。核心就两行：
selectedCodes.value = selectedCodes.value.slice(0, columnIndex); columns.value = columns.value.slice(0, columnIndex + 1);5.2 多选场景下的联动冲突
现象：开启多选后，用户勾选了一个省的多个市，然后修改省，发现已勾选的市数据全丢了，或者勾选状态混乱。
原因：多选模式下，每一级之间不是简单的单选联动关系，选中项可能跨多个父级。如果沿用单选逻辑去处理，就会互相覆盖。
解决：多选场景建议不用“联动面板”的结构，而是改成“左侧勾选树 + 右侧已选列表”的结构。每一级都是独立的勾选数据，已选列表单独维护：
// 多选已选列表结构 const checkedNodes = ref([ { code: '1101', name: '北京市', level: 2, parentCode: '11' }, { code: '110105', name: '朝阳区', level: 3, parentCode: '1101' } ]);多选联动是另一个复杂度级别，如果后续有时间我可以单独写一篇，这里不展开。
5.3 接口请求风暴与缓存优化
现象：用户在省、市、区之间快速切换，每切换一次就发好几个请求，后端接口压力非常大。
原因：没有做请求缓存，也没有做请求合并。
解决：最简单有效的优化是加“已加载池”，请求之前先看池子里有没有，有就直接用，没有才发请求：
const loadedPool = new Map(); async function loadChildren(parentCode) { if (loadedPool.has(parentCode)) { return loadedPool.get(parentCode); } const promise = props.loadData(parentCode); loadedPool.set(parentCode, promise); // 缓存 Promise，而非数据 return promise; }这里有个细节：缓存的是Promise而不是data。因为点击事件可能同时触发多个请求，如果数据已返回，缓存 Promise 也能直接拿到结果；如果请求还没返回，多个调用方共享同一个 Promise，天然就合并了请求，不会重复发。
5.4 数据量过大时的渲染性能优化
如果某级接口一次返回几百个节点，渲染时会有明显卡顿。特别是街道这一级，有的地区街道数量很多，加上节点 DOM 结构复杂，v-for 渲染压力不小。
- 虚拟滚动：只渲染可视区域的节点，渲染数量控制在几十个。实现不复杂，监听滚动容器高度和 scrollTop，算出截取范围。
- 本地搜索过滤：当列内节点数超过一定阈值时，给列顶部加一个小型筛选输入框。
- 懒加载子树：节点展开时才请求下一级，这个前面已经说过，这里强调一定要在节点上做
leaf标记，避免没有下级的时候白白发请求。
一个需要提前声明的原因是：虚拟滚动会破坏 CSS 的等高布局，滚动条高度需要手动设置，否则会出现“滚动到底加载不出来”的坑。所以如果节点数量在 200 以下，建议先用“列内搜索”这种低成本方案，别急着上虚拟滚动。
5.5 响应式数据层级过深的警告
Vue 3 的响应式是 Proxy 代理，深层嵌套的响应式对象在某些场景下会触发大量代理操作，导致性能下降。比如直接在 data 里塞一棵很深的树形 JSON，整个树都会被递归代理，访问时就慢。
如果确认层级深、数据量大，可以给数据加markRaw或shallowRef，让组件内部不去深度响应式追踪：
import { shallowRef } from 'vue'; // 组件内部维护的列数据，只做整体替换，不做深层变更 const columns = shallowRef([]); // 加载新列时整体替换 columns.value = [...columns.value.slice(0, columnIndex + 1), children];这个优化见效立竿见影，因为地址联动数据本质上是“整体替换局部列”，并不存在单独修改某个 node 内部字段的需求。shallowRef完美契合这种场景。
5.6 组件如何正确释放资源
地址联动组件如果在带 keep-alive 的页面里使用，或者组件被频繁创建销毁，要注意两点：
- 组件卸载时清掉正在进行的请求标记，避免 resolve 时操作已卸载的 DOM。
- 监听全局事件（比如点击外部关闭面板）记得在
onBeforeUnmount里移除。
let disposed = false; onBeforeUnmount(() => { disposed = true; }); async function loadNextLevel(parentNode, nextColumnIndex) { const children = await props.loadData(parentNode.code); if (disposed) return; // 组件已经卸载，丢弃数据 columns.value[nextColumnIndex] = children || []; }6. 几个让你少走弯路的实操心得
最后聊几点心得，这些是我在实际项目里反复调整后的体会。
第一，编码一致性是愿则性问题。开发前期就让后端把所有层级节点的编码规则定死，甚至出一个统一的常量文档。前端组件只认code、parentCode、name、leaf四个字段，后端接口无论怎么换，只要 shape 不变，前端一行都不用改。
第二，别过度设计。如果你的业务只需要三级，就别硬上四级组件。地址联动这种功能，每多一级，数据量和交互细节都复杂一个量级。只有确认有真实第四级需求，才值得投入这个成本。
第三，把异常处理当功能来做。地址联动接口一定会遇到慢、失败、超时、数据缺失这些情况。前端要把这些场景都做成可见的提示，而不是白屏、无限加载、列空白。你可以让用户重试，也可以自动 fallback 到上级数据，但绝不能没有反应。
第四，组件尽量做成无业务耦合的纯受控组件。地址联动组件只负责“选择并输出编码数组”，不要自己发请求、不要拼后端字段。数据加载函数和搜索结果函数全部通过 props 注入，这样任何项目都能复用，不用改内部逻辑。
如果用这个思路沉淀组件，下次换项目、换后端，你只需要重写一个loadData函数，组件本体一行不动。这才是地址联动组件应该有的姿态。
