简介面向微信小程序开发者的省市县三级联动组件资源包专注解决地址选择场景中的逐级筛选与数据联动问题。资源基于原生小程序框架展示了从全国行政区划JSON数据结构设计、picker组件绑定、事件处理到页面渲染的完整实现思路并附有核心代码片段与注释说明适合初中级开发者学习借鉴。压缩包共5个文件包含2个JavaScript逻辑文件负责数据处理与交互、1个WXML页面结构、1个WXSS样式及1个JSON配置结构精简可直接对照核心代码快速上手。整个资源仅27KB轻量易用。已有1460人学习下载。通过学习可掌握picker动态设置range、按父级ID过滤下级数据、默认省份自动初始化等关键方法并可直接复用或改造为完整地址选择模块节省从零开发时间。1. 微信小程序省市县联动数据层级比组件更重要开发过微信小程序收货地址表单的人都知道省市县三级联动看着就是三列滚轮真正动手才发现难点不在 picker 组件而在数据层级与索引同步。这份资源把行政区划数据、三级联动组件、示例页面和踩坑笔记打包在一起拿到后不用理解复杂算法直接能用于微信小程序的表单场景。它解决的核心问题是当你切换省份时市和县如何可靠地重建并保持滚轮位置正确。适合正在写自定义选择器、或者想把系统自带 region picker 替换成可定制弹层的小程序开发者。2. 数据与选区模型行政区划数据的三种组织方式与选型处理这个资源的第一步就是定数据结构。微信小程序里 setData 的性能和页面渲染直接相关省市区数据组织不好后面联动逻辑怎么写都别扭。先看常见的三种组织方式再决定这份资源里用什么。2.1 嵌套 JSON、扁平数组与编码前缀三种结构谁更合适常见做法是三种选一种。第一种是嵌套 JSON父子关系直接用 children 表达{ 100000: { name: 示例省, children: { 100100: { name: 示例市, children: { 100101: { name: 示例区 } } } } } }这种结构读起来最直观但取子级时每次都要沿树查微信开发者工具里深层遍历加 setData 容易卡。第二种是扁平数组每条记录带 parentCode[ { code: 100000, name: 示例省, parentCode: }, { code: 100100, name: 示例市, parentCode: 100000 }, { code: 100101, name: 示例区, parentCode: 100100 } ]扁平结构用 parentCode 筛选写起来最顺手新增一个地区只需要加一条记录不用维护层级关系。第三种是编码前缀法利用行政区划编码规则省级编码前两位市级前四位县级前六位取子集时直接 filter 编码前缀。这份资源默认采用“嵌套存储 扁平索引”。数据源用嵌套 JSON 保持可读性同时生成扁平索引表运行时用索引表查子级。这样既保留了层级文件体积小的特点又避免了递归查子级。生成索引的脚本很简单function buildIndex(nodes, parentCode , result []) { for (const key in nodes) { const node nodes[key]; result.push({ code: key, name: node.name, parentCode: parentCode }); if (node.children) buildIndex(node.children, key, result); } return result; }逻辑说明把嵌套对象拍平成数组每条记录带 parentCode后续 getChildren(code) 就是一次 filter不用递归。参数说明nodes 是嵌套数据对象parentCode 用于标记上级编码result 是收集用的数组实际调用时传 buildIndex(data)。2.2 picker 与 picker-view什么时候别用系统 region 组件微信小程序自带的 picker 组件有一个 moderegion 属性可以直接弹出省市区选择器。但它的样式完全由系统决定没法嵌入到自定义弹层里也不能控制每一列的宽度、字体和选中态。如果你的页面只需要一个简单的表单选择直接用它没问题但如果你要做成通用组件或者需要“确认/取消”按钮和遮罩就得用 picker-view 自己搭。维度picker moderegionpicker-view 自定制实现成本低一行代码高需要数据驱动样式定制基本不能完全自由数据来源系统内置自己的省市区数据适用场景快速表单自定义弹层/统一交互在模拟项目X里有个页面要求把地址选择嵌到遮罩浮层中region 组件无法控制浮层内布局只能换 picker-view 重新实现。这份资源选择 picker-view 的原因就是可定制同时附带了三列联动逻辑你不用再从零排版。2.3 数据瘦身剪掉经纬度和邮编只留 code 与 name从公开渠道拉到的原始省市区数据一般包含经纬度、电话区号、邮编、拼音、简称等字段直接塞进小程序会让主包变大setData 传输量也变大。资源里带的裁剪思路如下const fs require(fs); const raw JSON.parse(fs.readFileSync(./raw.json, utf8)); function prune(list) { return list.map(item { const result { code: item.code, name: item.name }; if (item.children item.children.length) { result.children prune(item.children); } return result; }); } fs.writeFileSync(./region.min.json, JSON.stringify(prune(raw)));逻辑说明递归遍历原始数组只保留 code、name 和 children没有子级就不输出 children 字段进一步减小体积。参数说明这段脚本在 Node 环境跑raw.json 是原始数据如果原始数据是“省-市-县”三级之外还有街道children 长度大于 0 就会继续递归理论上支持多级实际使用时建议把源数据先归一化再跑。注意code 字段必须是字符串。行政区划编码看起来像数字但前端处理时如果写成 Number前导零会丢后面前缀截取会翻车。这个坑在第 4 章还会提到。3. 从零实现联动选择器核心逻辑与代码落地数据结构定下来之后三级联动的实现就只有三步维护列表、监听 change、重建下级。这一章直接给出页面版实现先跑通再在下一章封装成组件。3.1 WXML 结构一个 picker-view 挂三列在页面的 WXML 中核心结构是三个 picker-view-column 放在同一个 picker-view 内picker-view classregion-picker value{{selectedIndex}} bindchangeonRegionChange picker-view-column view wx:for{{provinceList}} wx:keycode classpicker-item{{item.name}}/view /picker-view-column picker-view-column view wx:for{{cityList}} wx:keycode classpicker-item{{item.name}}/view /picker-view-column picker-view-column view wx:for{{districtList}} wx:keycode classpicker-item{{item.name}}/view /picker-view-column /picker-view逻辑说明picker-view 的 value 是一个数组数组第 0 项表示第一列省份的选中索引第 1 项表示市级第 2 项表示县级。三个列各自绑定一个列表列表内容由 data 里的 provinceList、cityList、districtList 提供。参数说明classpicker-item 是给每个滚动选项设置高度一般写 80rpx 左右同时 picker-view 本身要有明确高度如果列没有数据picker-view-column 内部为空滚动时会出现空白后面第 4 章会讲怎么避免。3.2 联动更新用 index 重建下级数组bindchange 回调的第一件事不是立刻 setData是先判断当前 index 对应的上一级数据存在Page({ data: { selectedIndex: [0, 0, 0], provinceList: [], cityList: [], districtList: [] }, onRegionChange(e) { const val e.detail.value; const province this.data.provinceList[val[0]]; if (!province) return; // 用索引表或 children 取市级列表 const cities this.getChildren(province.code); const city cities[val[1]] || cities[0]; const districts this.getChildren(city.code); this.setData({ cityList: cities, districtList: districts, selectedIndex: [val[0], cityIndex, 0] }); } });逻辑说明很多第一次写的人会直接 setData 一个 cityList但忘了一起把 selectedIndex 更新到新市级列表的有效范围内导致第二列还停留在旧的索引出现越界。这里用 val[0] 获取当前省索引cities 是新的市级数组cityIndex 是当前市级索引如果 val[1] 超出了新数组长度就回退到 0。参数说明getChildren(code) 是内部方法根据编码查子级资源里用扁平索引表实现这里为了演示写成方法调用。selectedIndex 必须同时更新否则 picker-view 会认为你想让第二列选中一个不存在的行。3.3 默认值与回显初始化时按编码定位索引表单编辑场景常见需求已有省市区编码打开组件后三列直接定位到对应位置。用编码反查索引initByCode(codeArr) { const [provinceCode, cityCode, districtCode] codeArr; const provinceIndex this.data.flatList.findIndex(item item.code provinceCode); const province this.data.flatList.find(item item.code provinceCode); const cities this.getChildren(provinceCode); const cityIndex cities.findIndex(item item.code cityCode); const city cities[cityIndex]; const districts this.getChildren(city.code); const districtIndex districts.findIndex(item item.code districtCode); this.setData({ provinceList: this.data.provinceList, cityList: cities, districtList: districts, selectedIndex: [provinceIndex, cityIndex, districtIndex] }, () { // 在回调里设置确实处理完成的标记 }); }逻辑说明先找到省记录再找市级列表中的市再找县级列表中的区。注意如果 codeArr 里的编码找不到findIndex 会返回 -1必须做兜底否则 selectedIndex 里出现 -1 会导致 picker-view 崩溃。常见做法是每个 findIndex 后加一个if (index -1) index 0;。参数说明codeArr 是类似[100000, 100100, 100101]的编码数组必须和扁平索引里的 code 字段类型一致字符串。initByCode 通常放在组件 properties 的 observer 里调用也可以在页面 onLoad 时手动调用。4. 常见问题排查与避坑4 个最容易翻车的环节这套逻辑我在模拟项目X里反复调过踩坑记录比功能代码还多。按现象、原因、解决整理如下每一个都是真实出现在开发者工具和真机上的。4.1 滚动以后列表空白value 索引越界现象在开发者工具中连续切换省份第二列或第三列变成空白控制台没有报错。原因picker-view 的 value 数组与 column 数量不一致。比如省份切到第 5 个但 cityList 还是上一个省的旧数据或者 selectedIndex[1] 是 3而新 cityList 只有 2 条渲染时索引越界列表显示空白。解决在 bindchange 里先计算新的 cities 和 districts再一次性 setData 所有相关字段包括 cityList、districtList、selectedIndex。代码参考 3.2 节。如果你碰到的是异步获取子级要确保子级数据 setData 完成后再把 selectedIndex 设置成有效值不要先置空再填充。4.2 真机与开发者工具滚动位置不一致现象开发者工具正常安卓真机打开后第一列总是停在中间第二列错位。原因picker-view 在初始化时需要拿到 value 和列表数据如果 value 在列表渲染之前就设置了组件会按默认位置渲染渲染完成后再改 value 不一定生效。开发者工具渲染快看不出来真机慢就暴露了。解决用 wx.nextTick 或者 setData 回调中再调整 value。比如 initByCode 里把 selectedIndex 放进 setData 回调再设置this.setData({ cityList: cities, districtList: districts, selectedIndex: [provinceIndex, cityIndex, districtIndex] }, () { wx.nextTick(() { this.setData({ selectedIndex: [provinceIndex, cityIndex, districtIndex] }); }); });逻辑说明第一次 setData 保证列表先有数据wx.nextTick 保证渲染完成后再校准一次索引。第二次 setData 不要带上列表数据只传 selectedIndex减少性能消耗。4.3 切换省份时白屏卡顿一次性加载全部子级现象首次从省切到另一个省页面出现明显白屏快速连续切换时卡死。原因每个省份下面几十个市每个市下面几十个县如果 setData 时把全国所有市级和县级数据一次性传过去或者频繁 setData 都包含大对象渲染线程会被阻塞。解决每次只 setData 当前选中的省对应的市列表和市对应的区列表。资源中的缓存策略是首次访问某省时从索引表生成市列表并存到本组件 data 的 cache 对象再次切换回来看 cache没有再重新生成。getChildren(parentCode) { if (this.data.cache[parentCode]) return this.data.cache[parentCode]; const children this.data.flatList.filter(item item.parentCode parentCode); this.setData({ [cache. parentCode]: children }); return children; }逻辑说明用 this.setData 写入 cache 时key 用计算属性路径cache. parentCode这样不会触发整个 cache 对象的深拷贝性能损失小。注意 filter 返回的是新数组缓存后不要直接 push 修改避免数据串掉。4.4 bindchange 触发过于频繁滚动惯性导致多次联动现象快速滑动省份列bindchange 连续触发三四次每次都在 setData页面掉帧。原因picker-view 的 bindchange 在滚动停止并选中新值后触发但用户快速滑动时中间经过多个索引每个停止点都可能触发一次。如果每次触发都做完整联动成本很高。解决用一个 lastIndex 记录上一次处理的省份索引只有在索引确实变化时才做联动onRegionChange(e) { const val e.detail.value; if (val[0] this.lastProvinceIndex) return; this.lastProvinceIndex val[0]; // 正常联动逻辑 }逻辑说明lastProvinceIndex 放在组件实例上而不是 data 里避免 setData 污染。这个方案比防抖更简单因为我们需要的是最终选中状态而不是中间过程。注意如果用户在同一省份内滑动市级列这个判断不拦截市级更新你可以用类似方式加一个 lastCityIndex。5. 把组件封装成可复用插件属性、事件与多场景接入页面代码跑通之后下一步是封装成自定义组件。组件目录下放 index.js、index.wxml、index.json、index.wxss核心逻辑全部收进组件内部。5.1 Component 化properties、observers 与内部状态关键在 index.jsComponent({ properties: { value: { type: Array, value: [] }, visible: { type: Boolean, value: false } }, observers: { value, visible: function(value, visible) { if (visible value.length 3) { this.initByCode(value); } } }, data: { provinceList: [], cityList: [], districtList: [], selectedIndex: [0, 0, 0], cache: {} }, methods: { initByCode(codeArr) { // 见第 3.3 节 }, onConfirm() { const codes this.getSelectedCodes(); this.triggerEvent(confirm, { codes, names: this.getSelectedNames() }); } } });逻辑说明父页面通过 value 属性传入初始省市区编码通过 visible 控制弹层开关。observers 同时监听 value 和 visible保证弹层每次打开都重置到指定位置。如果只监听 value第一次打开后第二次打开时 value 没变化组件会保留上一次的选择不符合表单编辑场景。参数说明properties 定义好外部接口内部所有状态放 data。triggerEvent 把组件内部的选择结果抛给父页面。外部只需要关心属性怎么传、事件怎么接不用理解联动细节。5.2 弹层交互遮罩、确定与取消弹层 WXML 结构包括一个遮罩层和底部选择区域view wx:if{{visible}} classmask catchtaponCancel view classpicker-panel catchtapnoop view classpanel-header text bindtaponCancel取消/text text bindtaponConfirm确定/text /view picker-view classregion-picker value{{selectedIndex}} bindchangeonRegionChange !-- 三列内容省略 -- /picker-view /view /view逻辑说明遮罩的 catchtap 用于点击外部关闭面板内部要再包一层 catchtapnoop 防止冒泡到遮罩导致误关。noop 是一个空方法只做事件拦截。onCancel 时要恢复打开前的选中状态。组件在弹层打开时需要有一次“后悔药”快照open() { this._backupCodes this.getSelectedCodes(); this.setData({ visible: true }); }, onCancel() { if (this._backupCodes) this.initByCode(this._backupCodes); this.setData({ visible: false }); }逻辑说明_backupCodes 存在实例上不参与 setData。取消时先回滚到备份编码再关闭弹层这样下次打开仍然是之前的值。确定时不需要回滚直接 triggerEvent。5.3 表单接入把组件返回值变成可提交的数据在父页面 JSON 里声明 usingComponents然后在 WXML 放组件region-picker idregionPicker value{{form.regionCode}} visible{{showRegion}} bind:confirmonRegionConfirm /父页面绑定onRegionConfirm(e) { const { codes, names } e.detail; this.setData({ form.regionCode: codes, form.regionText: names.join( ) }); }逻辑说明组件层面只输出编码数组和名称数组具体展示格式由页面决定。提交时如果后端要求字符串可以直接codes.join(,)要求文本用names.join()。这样组件的复用边界清晰不会把业务字段写死。如果你用的是一份旧的表单页面还有更省事的改法直接在 onConfirm 里修改地区显示控件的 text 和隐藏的 input value。但那样组件和页面耦合度高后面其他页面想复用就要再写一套不建议。6. 进阶用索引表做省市区检索与首字母定位前面强调的扁平索引表除了支撑联动还能用来做“搜索定位”。常见场景用户在编辑地址时不想一页页滚直接在搜索框输入“示例区”组件滚动到对应位置。利用扁平索引表一次 filter 就能找到节点然后反向拿到各级编码再调用 initByCode 完成定位。searchByName(keyword) { const results this.data.flatList.filter(item item.name.includes(keyword)); if (results.length 0) return null; const target results[0]; let codes []; let current target; while (current) { codes.unshift(current.code); current this.data.flatList.find(item item.code current.parentCode); } if (codes.length 3) { this.initByCode(codes); } return codes; }逻辑说明找到目标节点后沿 parentCode 回推省、市、县完整编码链unshift 保证顺序是从省到区。参数说明results 可能有多条重名取第一条如果要更精确可以让用户选择搜索结果再定位。另一个技巧是首字母定位。数据里如果不带拼音可以在脚本阶段用拼音库生成一个 pinyinMap把每个省名的首字母映射成省份索引。初始化时根据首字母跳到对应省份减少用户滚动距离。资源里附带了生成 pinyinMap 的脚本但拼音库体积不小建议只映射省份不映射到区县。我最早整理这个组件时觉得索引表只是实现细节后来在真实需求里要按名称定位到县级才发现没有索引表就得一层层递归代码立刻难看一倍。从那以后我每次集成省市区组件都强制走一遍“先生成索引表、再写联动逻辑、最后做回显验证”的流程能少踩很多坑。希望帮到你。本文还有配套的精品资源点击获取