简介：这份资源面向微信小程序开发者，聚焦地址选择场景中常见的省市县三级联动需求，提供一套可直接参考的完整实现方案。压缩包共5个文件，约27KB，以js逻辑文件为主，配合wxml页面结构、wxss样式与json配置，分别承担数据筛选与事件处理、选择器布局、界面样式和页面声明等职责，结构紧凑、便于快速导入开发者工具运行调试。目前已有1464人学习下载，说明该功能在实战开发中需求稳定。资源核心价值在于给出清晰的数据组织思路：以含id、name、parentId的JSON数据源为基础，通过picker组件动态绑定range，并在省、市、县选择变化时逐级过滤下级选项，同时处理默认选中与初始化逻辑。读者可据此掌握数据过滤方法、事件监听流程与组件联动技巧，并在此基础上扩展为地址管理、订单填写等实际业务模块。

1. 省市县三级联动：一个被低估的小程序基础组件

做微信小程序表单时，地址选择几乎是绕不开的一环。用户填收货地址、门店归属地、户籍所在地，只要涉及行政区划，就得让用户从省一路选到县。看起来简单，真动手写才发现坑不少：数据从哪来、picker 怎么串、切换省份后市县怎么重置、回显时怎么反查索引。我见过不少项目在这块翻车——用户选了广东省，结果市列表还挂着上一轮的北京市数据，提交上去地址对不上。这个项目就是来解决这件事的：一份完整的省市县三级联动实现，包含行政区划数据、picker 联动逻辑、回显处理和常见边界情况。适合正在写小程序表单、又不想在这块反复踩坑的开发者，新手能直接跑通，熟手能拿它的数据结构去做二次封装。

2. 项目结构与技术选型：为什么用原生 picker 而不是自造轮子

2.1 整体目录与文件职责

这个项目的结构很轻，没有引入任何第三方 UI 库，走的是微信小程序原生能力。常见做法是拆成数据层、逻辑层、视图层三块，目录大致如下：

miniprogram/ ├── pages/ │ └── address/ │ ├── address.js // 页面逻辑：联动、回显、校验 │ ├── address.wxml // 视图：三个 picker 串联 │ ├── address.wxss // 样式 │ └── address.json // 页面配置 ├── utils/ │ └── region.js // 行政区划数据 + 查询工具函数 └── app.js / app.json

region.js是整个项目的核心资产，里面存的是省、市、县三级嵌套数据，同时导出几个查询函数。address.js负责把这份数据接到 picker 上，处理bindchange事件和索引换算。视图层只做一件事：把三个picker按顺序摆好，绑定对应的数组和当前索引。这种拆法的好处是数据与逻辑解耦，后面要换成接口拉取行政区划，只改region.js的加载方式，页面逻辑基本不动。

2.2 技术选型：原生 picker 的取舍

微信小程序的picker组件自带mode="multiSelector"多列选择模式，理论上一个 picker 就能搞定三级联动。但这个项目用的是三个独立的mode="selector"picker 串联，原因很实际：多列 picker 的列数据必须同时准备好，切换省份时要手动setData更新后两列并重置选中项，事件里拿到的value是数组，回显时反查索引更绕；而三个单列 picker 各自独立，切换省份时只需重置市、县两个数组和索引，逻辑线性、调试直观。代价是视觉上不如多列滚轮紧凑，但对表单场景来说，清晰比炫技重要。

数据格式上，项目用的是嵌套结构，每个省节点带children存市，每个市节点带children存县：

// utils/region.js 数据结构示意 const regionData = [ { name: '某省A', children: [ { name: '某市A1', children: [{ name: '某县A1-1' }, { name: '某县A1-2' }] }, { name: '某市A2', children: [{ name: '某县A2-1' }] } ] }, { name: '某省B', children: [ { name: '某市B1', children: [{ name: '某县B1-1' }] } ] } ]; module.exports = { regionData };

这里说明一下参数：name是展示文本，children是下一级数组，层级固定为三层。选嵌套而不是扁平化加parentId，是因为小程序端数据量不大，嵌套结构在页面里取regionData[provinceIndex].children一步到位，省掉了每次切换都过滤数组的开销。如果行政区划数据量大到几千条，扁平结构加索引表会更合适，但那是另一个量级的场景。

提示：真实项目里行政区划数据建议单独维护成 JSON 文件，通过require引入，避免和业务代码混在一个文件里，后续更新数据时替换文件即可。

3. 核心联动逻辑拆解：从 picker 事件到三级索引

3.1 页面 data 的初始设计

联动能不能写顺，一半取决于data怎么设计。这个项目在data里维护了六组状态：三个展示数组、三个选中索引，外加一个最终拼接的地址字符串。

// pages/address/address.js const { regionData } = require('../../utils/region'); Page({ data: { provinceList: [], // 省份名称数组，供 picker range 使用 cityList: [], // 当前省下的市名称数组 countyList: [], // 当前市下的县名称数组 provinceIndex: 0, // 省选中索引 cityIndex: 0, // 市选中索引 countyIndex: 0, // 县选中索引 addressText: '' // 拼接后的完整地址，用于展示 }, onLoad() { // 初始化省份列表，默认选中第一个省及其下第一个市、县 const provinceList = regionData.map(p => p.name); const firstProvince = regionData[0]; const cityList = firstProvince.children.map(c => c.name); const countyList = firstProvince.children[0].children.map(c => c.name); this.setData({ provinceList, cityList, countyList, provinceIndex: 0, cityIndex: 0, countyIndex: 0 }); } });

这段代码的关键点在于：picker的range属性接收的是字符串数组，所以provinceList用map把对象数组转成名称数组，而原始嵌套数据始终留在regionData里做索引查询。onLoad里做了一次默认初始化，保证页面一进来三个 picker 都有值可选，不会出现空列表。参数上，provinceIndex等索引初始为 0，对应数组第一项，这是小程序 picker 的默认行为，不需要额外设置value属性也能正确显示。

3.2 省份切换：重置市县两级

省份变化是联动的起点，也是最容易出 bug 的地方。用户从省 A 切到省 B，市列表必须整体替换，县列表要跟着新省的第一个市走，两个索引都要归零。

// 省份 picker 的 bindchange 回调 onProvinceChange(e) { const provinceIndex = Number(e.detail.value); const province = regionData[provinceIndex]; // 用新省的市数据替换市列表，县列表取新省第一个市的县 const cityList = province.children.map(c => c.name); const countyList = province.children[0].children.map(c => c.name); this.setData({ provinceIndex, cityList, countyList, cityIndex: 0, // 市索引必须归零 countyIndex: 0 // 县索引必须归零 }, () => { this.updateAddressText(); }); }

逻辑说明：e.detail.value拿到的是字符串形式的索引，先Number转换再当数组下标用，这一步不做转换在某些基础库版本下会出玄学问题。cityIndex和countyIndex归零是硬性要求——如果不归零，用户切省后市 picker 会显示一个越界或错位的选项，血泪经验是这类问题在真机上才暴露，模拟器不一定复现。setData的第二个参数是回调，等视图更新完再拼地址文本，避免拿到旧数据。

3.3 市与县的级联更新

市切换和县切换的逻辑类似，但数据来源不同：市要从当前省的children里取，县要从当前市的children里取。

onCityChange(e) { const cityIndex = Number(e.detail.value); const province = regionData[this.data.provinceIndex]; const city = province.children[cityIndex]; const countyList = city.children.map(c => c.name); this.setData({ cityIndex, countyList, countyIndex: 0 // 换市后县索引归零 }, () => { this.updateAddressText(); }); }, onCountyChange(e) { const countyIndex = Number(e.detail.value); this.setData({ countyIndex }, () => { this.updateAddressText(); }); }

这里有个细节值得说：onCityChange里取省用的是this.data.provinceIndex，而不是重新从事件里拿。因为市 picker 的 change 事件只带市索引，省索引得从当前状态读。这就要求省份切换时provinceIndex必须已经setData生效，所以三个回调都用了setData回调来串行化，避免异步更新导致读到旧索引。县切换最简单，只更新索引，因为县下面没有第四级。

3.4 地址文本拼接与回显反查

选完之后要把三级名称拼成一个字符串展示或提交，同时表单编辑场景需要根据已有地址反查出三个索引，把 picker 恢复到正确位置。

// 拼接完整地址 updateAddressText() { const { provinceIndex, cityIndex, countyIndex } = this.data; const province = regionData[provinceIndex]; const city = province.children[cityIndex]; const county = city.children[countyIndex]; this.setData({ addressText: `${province.name}${city.name}${county.name}` }); }, // 根据已有地址字符串反查索引，用于编辑回显 setAddressByText(addressText) { let provinceIndex = 0, cityIndex = 0, countyIndex = 0; regionData.some((p, pi) => { if (!addressText.startsWith(p.name)) return false; provinceIndex = pi; p.children.some((c, ci) => { if (!addressText.startsWith(p.name + c.name)) return false; cityIndex = ci; c.children.some((cc, cci) => { if (addressText === p.name + c.name + cc.name) { countyIndex = cci; return true; } return false; }); return true; }); return true; }); const province = regionData[provinceIndex]; const city = province.children[cityIndex]; const countyList = city.children.map(c => c.name); this.setData({ provinceIndex, cityIndex, countyIndex, cityList: province.children.map(c => c.name), countyList, addressText }); }

updateAddressText直接按索引取三级名称拼接，简单直接。setAddressByText是回显的关键，用some逐级匹配前缀，匹配到就中断，避免全量遍历。参数上，addressText要求是「省+市+县」无分隔符拼接的格式，如果后端存的是带分隔符的地址，进来前先replace掉。这里用前缀匹配而不是精确匹配省名，是因为有些地址文本可能带「省」「市」后缀差异，实际项目里我一般会先做一次名称归一化再匹配，减少匹配失败。

4. 避坑与排查：三级联动里那些真机上才暴露的问题

4.1 切换省份后市列表错位

现象：用户从省 A 切到省 B，市 picker 显示的选项还是省 A 的市，或者显示空白。原因：cityList更新了但cityIndex没归零，picker 按旧索引去新数组里取值，越界或错位。解决：省份 change 回调里必须同时setData新的cityList和cityIndex: 0，两者放在同一次setData里，不要分两次调用，否则中间态会触发一次错误渲染。

4.2 回显时县列表为空

现象：编辑页面根据地址回显，省和市对了，县 picker 是空的。原因：setAddressByText里只更新了countyIndex，忘了同步更新countyList，而countyList依赖当前市的children。解决：回显时按「省索引 → 市列表 → 市索引 → 县列表 → 县索引」的顺序一次性算好再setData，缺一环都会导致列表和索引对不上。

4.3 直辖市与特殊行政区划导致层级缺失

现象：选中某些直辖市，县列表为空或只有一项，picker 卡住。原因：部分行政区划在数据里只有两级，市下面直接是区，没有第三级，或者数据结构不统一。解决：在region.js里对这类数据做补齐，把缺失的层级用同名或占位节点填上，保证三层结构一致；页面逻辑里也可以加一层兜底，countyList为空时用['请选择']占位，避免 picker 崩溃。

4.4 真机上 picker 索引不刷新

现象：模拟器上切换正常，真机上 picker 显示的还是旧值。原因：picker的value属性绑定的是索引，如果只更新了range没更新value，部分基础库版本不会主动重绘。解决：wxml里给每个 picker 显式绑定value="{{provinceIndex}}"这类属性，并在setData里确保索引和列表同批更新。这个坑我踩过不止一次，后来养成习惯：凡是 picker，range和value永远成对出现。

4.5 数据体积拖慢首屏

现象：页面首次加载明显卡顿，尤其低端机。原因：行政区划数据全量require进来，几千条对象常驻内存，onLoad里又做了一次全量map。解决：把数据拆成按省懒加载，首屏只加载省份列表，市和县在用户切换时再按需取；或者把数据转成扁平数组加索引映射，减少嵌套遍历。数据量再大就考虑放云开发数据库或接口拉取，本地只留缓存。

5. 二次开发与改造思路：把联动封装成可复用组件

5.1 从页面逻辑抽成自定义组件

现在这套逻辑写在页面里，换个页面就得复制一遍。更合理的做法是抽成自定义组件region-picker，对外只暴露value和bindchange两个接口。组件内部维护三级索引和列表，页面只关心最终选中的地址对象。

// components/region-picker/region-picker.js Component({ properties: { value: { type: String, value: '' } // 外部传入的地址文本，用于回显 }, data: { provinceList: [], cityList: [], countyList: [], provinceIndex: 0, cityIndex: 0, countyIndex: 0 }, lifetimes: { attached() { this.initData(); if (this.data.value) { this.setAddressByText(this.data.value); } } }, methods: { // 内部联动逻辑与页面版一致，选中后触发事件 emitChange() { const { provinceIndex, cityIndex, countyIndex } = this.data; const province = regionData[provinceIndex]; const city = province.children[cityIndex]; const county = city.children[countyIndex]; this.triggerEvent('change', { province: province.name, city: city.name, county: county.name, text: `${province.name}${city.name}${county.name}` }); } } });

改造要点：properties.value接收外部地址文本，attached生命周期里做回显；triggerEvent把选中的三级名称和拼接文本一起抛给页面，页面不用再关心索引换算。这样封装后，任何表单页面引入组件、绑一个bindchange就能用，回显也只需传value。参数上，value格式要和内部拼接格式一致，不一致就在组件里加一层归一化。

5.2 数据源替换与验证方法

行政区划数据会变，项目里写死的数据迟早要更新。改造时把region.js的静态require换成可替换的数据源，比如启动时从接口拉取并缓存到storage，拉取失败再回退到本地兜底数据。验证方法很直接：准备一组边界地址文本，包括直辖市、只有两级的数据、名称带后缀差异的，跑一遍setAddressByText，看三个索引和列表是否都对得上；再手动切省、切市，确认索引归零和列表刷新没有中间态错位。我一般会在组件里留一个debug开关，打开后把每次setData前后的索引打到控制台，排查联动问题时比盲猜快得多。

从那以后我每次写联动类组件，都强制先把「索引归零」和「列表与索引同批更新」这两条写成注释贴在setData旁边，再动手写业务。希望帮到你。

本文还有配套的精品资源，点击获取