如果你的需求只是让用户顺手选一个省市区，ElementUI 里官方提供的 el-cascader 一行代码就能解决，页面效果还过得去。但我在实际项目里走了另一条路：自己封装一个 ElementUI 自定义组件——地区三级联动。原因不是级联选择器不好用，而是当后端接口坚持把省、市、区拆成三个独立字段提交时，当产品要求三个下拉框必须并排出现在表格筛选栏里时，当一个页面里省级必填、市级可空、区级只读时，el-cascader 的默认交互就变得很别扭。这篇文章把我从第一版能跑、到后来踩坑修补的完整过程整理出来，适合正在用 ElementUI 做后台管理项目、想实现自定义表单控件的朋友参考，也适合理清“自定义组件如何接表单校验”这条技术路线。
1. 先想清楚：为什么不用自带 el-cascader，非要自己封装
1.1 三个让我决定自研的现实问题
先说最直接的场景。我之前接手的后台管理系统里，用户的收货地址和项目所在地都需要录入省市区。后端同学给的接口协议非常明确：入库字段分别是provinceCode、provinceName、cityCode、cityName、districtCode、districtName，六个字段一一对应，一个都不能少。
用 el-cascader 当然也能做，@change回调里把选中节点的路径取出来，再映射成六个字段。但问题在于，这种映射逻辑每个用到地址选择的页面都要写一遍，一旦页面变多，相同的代码会在十多个地方重复出现。更重要的是，el-cascader 的值本质上是一个一级数组或者叶子值，它和表单模型里的扁平字段天然不对齐，每次提交前都要做一层转换，出错的概率反而更高。
第二个问题是页面形态不匹配。后台列表页顶部通常要放一组筛选条件，产品希望省、市、区三个下拉框横向排开，一眼能看到当前选中的是哪三级。如果放一个 el-cascader，用户在弹层里选择，收起之后看到的只是一段“广东省 / 深圳市 / 南山区”的文本。如果筛选区还有其他条件需要和地区联动，比如选完省之后要触发一次附近门店的查询，级联选择器这种整体式的变化回调就不如三个独立下拉框灵活了。
第三个问题来自权限控制。项目里有个角色只能修改“市”这一级，省和区都要锁定；另一个角色则是三个级别都只能看不能改。el-cascader 的disabled是整块禁用的，做不到“省禁用、市可用、区禁用”这种细粒度控制。虽然也可以在外层套遮罩模拟，但维护成本高，而且交互很生硬。
1.2 自定义组件至少要满足哪些底线
决定自己封装之前，我先给这个组件列了一个能力清单，作为“能不能上线”的验收标准：
- 对外使用方式必须像原生表单控件，能直接
v-model绑定一个结构化的地区对象； - 内部是三个 el-select，但调用方完全不用关心省市区列表是怎么联动、怎么加载的；
- 必须支持表单校验：组件值变化时，所在的
el-form-item要能自动触发校验，而不是让业务方手动callback； - 支持
disabled、clearable、size等常规属性，保证和页面里其他表单项风格一致； - 不把数据请求逻辑写死在组件里。数据可以来自静态 JSON，也可以由外部传入或按需请求，组件只负责“联动”这件事。
这些底线看似简单，实际写起来还是踩了不少坑。尤其是“自动触发表单校验”这一条，很多自定义组件的实现都栽在这里。
2. 数据是地基：地区数据的获取、清洗与归一化
2.1 三种数据来源怎么选
地区数据是整个组件的地基。如果数据源没定好，后面联动逻辑写得再漂亮都会出问题。我梳理了三种常见来源，也给出我的选择倾向。
| 数据来源 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 静态 JSON 打包进前端 | 加载快、不依赖接口、离线可用 | 行政区划变更要重新发版 | 省市区三级固定、更新频率低、对实时性要求不高 |
| 后端接口按需加载 | 数据实时、可扩展乡镇街道级 | 需要处理 loading 和请求竞态 | 地区数据有业务定制（比如排除某些地区） |
| 第三方数据服务 | 准确度高、省维护成本 | 依赖外部服务稳定性和配额 | 小型非核心项目可用 |
我最终选择的是静态 JSON 方案。因为后台系统的省市区数据一年到头也更新不了几次，而且静态 JSON 可以做到“组件一加载，省列表立刻出现”，用户体感比异步接口好。等以后需要扩展到乡镇街道级，再改造组件支持接口加载也不迟。
2.2 一份组件友好的数据格式
地区数据的结构，我强烈建议使用树形嵌套，每个节点用code而不是自增id作为唯一标识。行政区划代码是国标，换系统、换项目都不会变，而且同一个地区在不同系统里的 code 完全一致，方便后端做数据关联。
数据长这样：
[ { "code": "110000", "name": "示例省A", "children": [ { "code": "110100", "name": "示例市A1", "children": [ { "code": "110101", "name": "示例区A1-1" }, { "code": "110102", "name": "示例区A1-2" } ] } ] } ]为什么不用扁平数组加parentCode的方式？虽然接口返回经常是扁平的，但前端联动时树形结构可以直接从“省节点”上取到它的children作为市级下拉数据，从“市节点”上取到区级下拉数据，不需要每次都对全量数组做filter。我在第一版也试过扁平结构，写着写着发现每次选省都要遍历一遍全国数据找子节点，代码不直观，性能也完全没有必要地差。
2.3 清洗脚本能帮你省下一周的体力活
原始数据从各种渠道拿回来，基本上都要处理。我遇到过的情况包括：某些接口把省下面的地级市直接挂在省节点下，但直辖市下面只有区和县，缺少中间层；某些数据源带了乡镇街道级，但业务只需要到区县；还有一部分节点存在空children，需要过滤掉。
所以清洗脚本的核心逻辑就三件事：裁层级、去空节点、保顺序。
// 裁剪到三级，去掉 children 为空的节点 function normalizeRegion(list, deep = 3) { if (!Array.isArray(list)) return [] const result = [] list.forEach(item => { if (!item || !item.code || !item.name) return const node = { code: item.code, name: item.name } if (deep > 1 && Array.isArray(item.children) && item.children.length) { const children = normalizeRegion(item.children, deep - 1) if (children.length) { node.children = children } } result.push(node) }) return result }这个脚本看起来简单，但非常实用。处理完的数据直接输出成src/assets/region.json，打包时体积也不大，纯省市区三级全国数据压缩后通常只有几十 KB，对性能的影响可以忽略。
3. 组件整体设计：对外协议与表单接入
3.1 让 v-model 承载结构化的值
自定义组件第一步是定好对外协议。地区三级联动组件我推荐用对象结构作为v-model的值，而不是用简单数组。对象的好处是省、市、区的 code 和 name 一起绑定，后端提交和前端回显都只认这一个对象。
props: { value: { type: Object, default: () => ({}) }, disabled: { type: Boolean, default: false }, clearable: { type: Boolean, default: true }, size: { type: String, default: 'medium' }, filterable: { type: Boolean, default: true }, placeholders: { type: Array, default: () => ['请选择省', '请选择市', '请选择区'] } }其中value对象里的字段固定为六个：
{ provinceCode: '', provinceName: '', cityCode: '', cityName: '', districtCode: '', districtName: '' }这样设计还有一个好处：后端接口如果已经返回了这种扁平字段，编辑页回显时直接把详情接口的地址字段塞给 v-model 就行，前端不需要再额外组装。
3.2 模板骨架与内部状态
组件内部用三个 el-select 串成一行。为了让调用方完全无感，省市区列表的变化全部由内部维护。
<template> <div class="region-linkage"> <el-select v-model="provinceCode" :disabled="disabled" :clearable="clearable" :size="size" :filterable="filterable" :placeholder="placeholders[0]" class="region-linkage__select" @change="handleProvinceChange" > <el-option v-for="item in provinceList" :key="item.code" :label="item.name" :value="item.code" /> </el-select> <el-select v-model="cityCode" :disabled="disabled" :clearable="clearable" :size="size" :filterable="filterable" :placeholder="placeholders[1]" class="region-linkage__select" @change="handleCityChange" > <el-option v-for="item in cityList" :key="item.code" :label="item.name" :value="item.code" /> </el-select> <el-select v-model="districtCode" :disabled="disabled" :clearable="clearable" :size="size" :filterable="filterable" :placeholder="placeholders[2]" class="region-linkage__select" @change="handleDistrictChange" > <el-option v-for="item in districtList" :key="item.code" :label="item.name" :value="item.code" /> </el-select> </div> </template>内部 data 除了三个列表，还要维护省、市、区各自的 code 和 name：
data() { return { provinceList: [], cityList: [], districtList: [], provinceCode: '', provincerName: '', cityCode: '', cityName: '', districtCode: '', districtName: '', syncing: false } }第一版我踩过的一个明显问题：name 和 code 必须同步维护。有人在省 change 时只更新了cityCode，没更新cityName。看起来下拉框左边选中了，但表单提交到后端时 cityName 还是上一次的旧值，排查了半天才发现。
3.3 注册进业务表单
封装完成后，业务页面里的用法非常干净：
<el-form-item label="所在地区" prop="region"> <region-linkage v-model="form.region" /> </el-form-item>表单校验规则可以用自定义 validator：
rules: { region: [ { validator(rule, value, callback) { if (!value || !value.provinceCode) { callback(new Error('请选择省')) } else if (!value.cityCode) { callback(new Error('请选择市')) } else if (!value.districtCode) { callback(new Error('请选择区')) } else { callback() } }, trigger: 'change' } ] }这里的trigger必须写成change，因为组件没有原生 blur 事件，如果写blur，表单永远只在失去焦点时触发校验，很多情况下不会触发。
4. 联动细节：核心逻辑与容易踩的坑
4.1 上级变化时重置下级只能多不能少
三联动的核心逻辑其实不难，难点在“重置”这件事要做到位。所谓到位，不只是把下级的 code 清空，还包含下级的 name、下级的选项列表一并处理。
省改变时的方法如下：
handleProvinceChange(code) { // 找到当前选中的省级节点 const node = this.provinceList.find(item => item.code === code) // 清空省级名称 this.provinceName = node ? node.name : '' // 重置市级和区级 this.cityCode = '' this.cityName = '' this.districtCode = '' this.districtName = '' // 刷新市级下拉列表，同时清空区级列表 this.cityList = node ? node.children || [] : [] this.districtList = [] this.emitChange() }注意这里有个细节：当用户点击 el-select 自带的清空按钮时，@change回调拿到的 code 是空字符串，此时find返回undefined，所以node ? node.children : []这种写法能保证列表也被清空。如果不加这个判断，就会出现“省级已经清空，但市级下拉还留着上次的数据”的 bug。
市级变化的逻辑类似，差异只是它只需要重置区级：
handleCityChange(code) { const node = this.cityList.find(item => item.code === code) this.cityName = node ? node.name : '' this.districtCode = '' this.districtName = '' this.districtList = node ? node.children || [] : [] this.emitChange() }4.2 回显场景下的时序问题
编辑页回显是个大坑，而且这个坑是 ElementUI 自定义表单控件普遍会遇到的。
我遇到过两种典型情况：第一种，页面一打开，详情的地区编码已经返回，但组件内部的省列表还没从 JSON 里加载完成。第二种，省列表是静态的，但市级列表依赖省级选中后再计算，此时外部回显的value里同时给了省、市、区三个 code，组件怎么知道市级列表应该用哪一个省去生成？
解决思路是：回显时不只看外部 value，还要主动从省列表反查。组件的syncFromValue方法要做成幂等的——无论外部 value 何时变化，都能根据 value 里的provinceCode找到对应的市级节点，再根据cityCode找到区级节点。
syncFromValue(val) { if (!val) return const pCode = val.provinceCode || '' const cCode = val.cityCode || '' const dCode = val.districtCode || '' // 如果省列表还没就绪，先把外部值缓存下来，等待列表加载后再处理 if (!this.provinceList.length) { this.pendingValue = { ...val } return } this.provinceCode = pCode const pNode = this.provinceList.find(item => item.code === pCode) this.provinceName = pNode ? pNode.name : (val.provinceName || '') this.cityList = pNode ? pNode.children || [] : [] this.cityCode = cCode const cNode = this.cityList.find(item => item.code === cCode) this.cityName = cNode ? cNode.name : (val.cityName || '') this.districtList = cNode ? cNode.children || [] : [] this.districtCode = dCode const dNode = this.districtList.find(item => item.code === dCode) this.districtName = dNode ? dNode.name : (val.districtName || '') }当省列表是从接口异步获取时，在created加载完成后要再调用一次：
async loadProvinceList() { const data = await getRegionList() this.provinceList = data if (this.pendingValue) { this.syncFromValue(this.pendingValue) this.pendingValue = null } }另外，组件的 watch 逻辑也要处理“自循环”问题。组件向外$emit('input')之后，父组件的 v-model 会更新回来，又会触发 watch。如果每次 emit 都重新同步一遍，可能出现死循环。我的做法是维护一个syncing标志：
emitChange() { const payload = { provinceCode: this.provinceCode, provinceName: this.provinceName, cityCode: this.cityCode, cityName: this.cityName, districtCode: this.districtCode, districtName: this.districtName } this.syncing = true this.$emit('input', payload) this.$emit('change', payload) this.$nextTick(() => { this.syncing = false }) }这里用$nextTick而不是直接赋值 false，是因为父组件接收 input 事件后，v-model 的值更新也要等到下一个 tick，过早放开 syncing 标志，watch 仍然可能在一次事件循环里被触发。
4.3 触发 el-form-item 校验的正确方式
上一节我给出了自定义 rules validator 的方式，但它有个弱点：如果业务方觉得每个页面都写 validator 太啰嗦，希望组件自己负责“值一变化就唤起校验”，那就得让组件能主动通知到外层表单项。
ElementUI 内部有一套 dispatch 机制，组件可以通过向上遍历找到最近的ElFormItem，触发它的el.form.change事件。这套机制在自定义组件里同样能用，不需要依赖任何第三方库：
methods: { dispatch(componentName, eventName, params) { let parent = this.$parent || this.$root while (parent) { if (parent.$options && parent.$options.componentName === componentName) { parent.$emit.apply(parent, [eventName].concat([params])) break } parent = parent.$parent } } }然后在emitChange里加一行：
this.dispatch('ElFormItem', 'el.form.change', payload)这样做的效果是：只要组件内部的任何一个下拉框发生改变，外层表单项就会用 rules 里定义的 validator 校验当前值。如果 rules 里没有配置这个prop，也不会报错，只是白白遍历一次，可以放心加。
我实测过，这个 dispatch 方法在 ElementUI 2.x 下可以稳定工作。如果你用的是 Vue 3 的 Element Plus，el-form-item的组件名和事件名略有差异，但思路完全一致。
4.4 只读、禁用、必填的粒度控制
我最初只做了disabled属性，后来产品提了个需求：某个角色必须选省级和市级，区级可选；另一个角色省级是只读的，市级区级可以编辑。于是我给组件加了levelDisabled和levelClearable两个对象类型的 props：
levelDisabled: { type: Object, default: () => ({ province: false, city: false, district: false }) }模板里对应的 el-select 改为：
<el-select :disabled="disabled || levelDisabled.province" ... >disabled是总开关，levelDisabled是单级开关，两件事互不干扰。如果你的表单里还有“省级必填、市级必填、区级选填”这种需求，rules 里自己控制即可，组件不需要内置必填逻辑，保持单一职责。
5. 实测中的性能优化与体验打磨
5.1 什么时候才需要懒加载
很多人一提到省市区联动就担心数据量太大，实际上纯省市区三级全国数据也就几千条，静态 JSON 全量加载完全没压力。真正需要懒加载的场景是数据扩到了乡镇街道甚至村居，或者地区数据由后端接口实时下发。
如果决定走接口懒加载，需要注意请求竞态问题。用户快速从“广东省”切到“浙江省”，上一次的市级请求可能比下一次晚返回，导致浙江省下面显示的是广东省的城市。一个简单可靠的方案是记录请求序号：
async handleProvinceChange(code) { const seq = ++this.reqSeq this.cityList = [] this.districtList = [] const list = await fetchCityByProvince(code) // 只有最新一次请求的返回值才允许覆盖列表 if (seq === this.reqSeq) { this.cityList = list } }每次省变化都自增reqSeq，只有最后一次请求的序号能通过校验。这个方案比“取消上一次请求”要轻量很多，也不依赖 axios 的 cancelToken，适用面更广。
5.2 几个容易被忽视的交互细节
宽度问题。三个 el-select 默认宽度不一样，并排起来非常难看。我在组件外层用了 flex 布局，同时给每个 el-select 加style="width: 100%"，这样三个下拉框会根据容器宽度等比伸缩：
.region-linkage { display: flex; gap: 10px; } .region-linkage__select { flex: 1; }如果是在弹窗里的窄容器中，建议把gap调成 8px，甚至允许换行，否则小屏下三个下拉框会挤成一团。
搜索问题。ElementUI 的 el-select 自带filterable后，默认按 label 文本匹配，能满足按地区中文名搜索。但很多用户习惯输入拼音首字母，比如输入“gd”希望过滤出“广东”。这种情况就不能只靠默认 filter 了，需要给 el-option 的数据里加一个pinyin字段，然后用filter-method自定义过滤逻辑。这个改造不复杂，但通常要在格式化地区数据时提前把拼音传入。
清空后的体验。当用户点掉省级的选择时，市级和区级必须一并清空，这个逻辑我前面已经强调过了。还有一个容易漏掉的点：清空省级之后，市 dropdown 的 placeholder 会正常显示，但区 dropdown 如果还残留旧的选中文本，看起来就是“省空、市空、区有值”的怪状态。所以只要省级变化，无论选还是清空，都要把区级的下拉列表置空。
5.3 实测中遇到过的 bug 清单
| 现象 | 根因 | 处理方式 |
|---|---|---|
| 修改省之后，市级数据变成上一个省的 | 市级列表在某次点击时没有立即清空，旧列表被短暂渲染 | 在省 change 方法里第一时间this.cityList = []，再异步加载 |
| 编辑回显时区级名称一直是空 | 组件内部只根据 code 找节点，找不到就默默返回，没有用外部值中的 name 兜底 | syncFromValue里找不到节点时，使用val.cityName等字段 |
| 连续切换省，城市下拉数据错乱 | 异步请求返回顺序不可控 | 使用请求序号拦截过期响应 |
| 表单校验红框一直不消失 | 组件只 emit 了 input 事件，没有触发 ElFormItem 的校验 | 使用 dispatch 主动触发el.form.change |
使用JSON.parse(JSON.stringify())拷贝地区数据，下拉切换偶尔性能卡顿 | 大对象深拷贝代价高 | 改为浅拷贝或直接只读引用，组件内部不修改原始数据 |
这些 bug 单看每一条都挺简单，但如果不做组件封装，这些问题会在每一个用到地区选择的页面上重复出现。封装的价值就在这里：一次性把坑填平，所有页面只需面对一个稳定的RegionLinkage组件。
我在实际使用中还有一个体会：不要把地区数据请求和组件逻辑混在一起。静态 JSON 方案下，组件自给自足；接口方案下，建议通过 props 把数据源函数传进来，组件只负责渲染和联动，把“从哪里拿数据”留给调用方决定。这样做之后，同一个组件既可以用在管理后台，也可以用在 C 端嵌套在复杂表单里，不需要因为数据来源不同而复制两份代码。
最后再分享一个经验：如果你也决定封装这类联动组件，第一时间先写清楚对外协议——v-model 绑定什么结构、change 事件返回什么对象、表格校验怎么接入。协议定得越清楚，后面写内部实现就越轻松。我第一次是直接动手写下拉框，写到一半才发现 value 结构设计得不合理，回头改组件接口的成本比想象中大得多。先设计协议，再填逻辑，这一步不能省。
