微信小程序地图选点与路线规划实战：腾讯位置服务避坑指南

1. 从选个地址说起地图选点到底在解决什么问题做过小程序的人大概都有过这种体验用户下单时要填收货地址你给他一个输入框他手动敲某市某区某路某号敲完你还得担心他填错、填漏、填了个根本不存在的地方。后来大家学聪明了接个地图选点组件让用户在地图上戳一下经纬度直接回填省事又准确。这个需求看起来简单但真动手做的时候问题一个接一个冒出来——地图怎么渲染用户拖动地图时中心点标记怎么固定选完之后地址怎么反解析成文字如果还要显示从A到B怎么走路线规划又该怎么接微信小程序本身提供了wx.chooseLocation这个原生能力但它有几个硬伤样式不可定制、部分场景下无法满足业务对地图交互的深度要求、而且它依赖用户授权位置权限的时机比较死板。所以很多团队会选择自己用map组件配合腾讯位置服务Tencent Location Service后面简称 TLS的 WebService API 来做一套可控的选点方案。这套方案的核心链路其实就三件事地图渲染与交互、逆地址解析坐标转文字、路线规划驾车/步行/骑行。听起来不多但每一块都有细节。这篇文章适合谁看如果你是小程序开发者正在做外卖、打车、上门服务、物流寄件、门店导航这类和地理位置强相关的功能那这篇内容基本就是给你写的。我会从地图组件的初始化讲起把选点交互的设计逻辑、逆地址解析的调用姿势、路线规划的接口选型和参数细节全部拆开再补上我自己踩过的坑和实测有效的优化手段。不堆概念直接上能跑的东西。先说一个基本认知腾讯位置服务在小程序里的使用分两条线。一条是客户端 SDK通过qqmap-wx-jssdk这个包在小程序里直接调用部分能力另一条是服务端 WebService API通过 HTTPS 请求调用需要申请 key 并配置合法域名。选点和路线规划这两个场景客户端和服务端的能力有重叠也有分工选错了实现方式后面会很难受。2. 动手之前key申请、域名配置与SDK引入的完整准备2.1 申请key时那几个容易填错的字段去腾讯位置服务控制台创建应用、添加 key这一步本身不难但有几个字段填错了后面会一直报错而且报错信息不一定直白。创建 key 时需要选择启用产品这里要勾选WebServiceAPI和微信小程序。很多人只勾了 WebServiceAPI结果在小程序里用 SDK 时一直提示鉴权失败。另外如果用到路线规划WebServiceAPI 里的路线规划相关能力要确认已开通。还有一个关键点授权 IP 和小程序 appid 的绑定。WebServiceAPI 的 key 如果开启了 IP 白名单限制那你在小程序里直接请求会失败因为小程序的请求来源 IP 是不固定的。正确做法是如果这个 key 只给小程序端用就在 key 配置里绑定小程序的 appid而不是配 IP 白名单。绑定 appid 之后小程序发起的请求才能通过校验。这个细节官方文档有写但很容易被忽略我见过好几个团队卡在这里排查半天。2.2 合法域名配置别等到真机才想起来小程序请求外部接口必须在request合法域名里配置。腾讯位置服务的 WebService 域名是https://apis.map.qq.com这个必须加到 request 合法域名里。开发阶段可以在开发者工具里勾选不校验合法域名但上线前一定要配好否则真机上直接请求失败。这里有个实操建议开发阶段就把域名配好不要依赖不校验选项。因为有些问题比如证书、跨域相关的行为差异在勾选不校验时是看不出来的等到提审前才配域名容易暴露一堆问题来不及改。2.3 SDK引入的两种方式与选择逻辑腾讯位置服务为小程序提供了qqmap-wx-jssdk引入方式有两种第一种是下载 SDK 文件放到项目里通过require引入。这种方式的好处是不依赖网络加载稳定坏处是版本更新要手动替换。第二种是通过 npm 安装。如果你的小程序项目已经用了 npm 构建直接npm install qqmap-wx-jssdk然后构建即可。我个人的选择是下载文件放到libs目录下原因很简单这个 SDK 更新频率不高而小程序对 npm 构建偶尔会有缓存问题直接放文件最省心。引入代码大概长这样const QQMapWX require(../../libs/qqmap-wx-jssdk.js); const qqmapsdk new QQMapWX({ key: 你申请的key });注意 key 直接写在前端代码里是有暴露风险的。虽然腾讯位置服务的 key 有域名/appid 限制暴露了也不能被随意盗用但更稳妥的做法是把敏感调用放到自己的服务端代理。不过对于选点和路线规划这种场景客户端直接调用是官方支持的用法key 的权限已经被 appid 绑定限制住了实际风险可控。如果你特别在意可以走服务端中转但会增加一层网络开销。3. 地图选点的交互设计中心点固定与拖动选点的实现逻辑3.1 为什么不用原生chooseLocation前面提过wx.chooseLocation的局限。具体来说它的问题集中在三点一是 UI 完全不可定制和你的小程序设计风格可能格格不入二是它返回的地址信息粒度有限有时候拿不到你想要的省市区结构化数据三是它无法和你的业务流程深度耦合比如你想在选点时同时显示附近门店、或者限制只能选某个城市范围内的点原生组件做不到。自己实现选点的核心思路是地图铺满中心点用一个固定的 marker 图标盖在地图中央用户拖动地图地图停止移动后读取地图中心坐标再逆解析成地址。这个交互模式用户很熟悉滴滴、美团选上车点都是这个逻辑。3.2 map组件的关键属性配置先看 map 组件的基础配置map idmap longitude{{longitude}} latitude{{latitude}} scale{{scale}} markers{{markers}} show-location{{true}} bindregionchangeonRegionChange bindtaponMapTap stylewidth: 100%; height: 100vh; /map几个属性值得说明。show-location打开后会显示用户当前位置的蓝点但注意这需要用户授权scope.userLocation如果用户拒绝蓝点不显示但地图仍可正常使用要做好降级处理。scale控制缩放级别选点场景一般设在 16 到 18 之间太远了看不清街道太近了又看不到周边参照物。bindregionchange是核心事件它在视野变化时触发。但这个事件触发非常频繁用户拖动过程中会连续触发如果每次触发都去请求逆解析接口调用量会爆炸。所以必须做防抖处理等用户停止拖动后再请求。3.3 中心点marker的定位技巧固定中心点的实现有两种常见做法。一种是用cover-view在地图上方绝对定位一个图标这个图标不随地图移动视觉上就是钉在屏幕中央。另一种是用 map 的markers但 markers 是跟着地图坐标走的做不到固定。所以正确做法是第一种在地图容器上叠一个cover-view里面放图标。view classmap-container map .../map cover-view classcenter-marker cover-image src/images/pin.png/cover-image /cover-view /view.map-container { position: relative; width: 100%; height: 100vh; } .center-marker { position: absolute; left: 50%; top: 50%; transform: translate(-50%, -100%); z-index: 10; }注意translate(-50%, -100%)这个细节水平居中好理解垂直方向要往上偏移整个图标的高度这样图标的尖端才对准地图中心点。如果只写translate(-50%, -50%)图标中心对准了地图中心实际选出来的点会偏。这个偏移量很多人第一次做会搞错导致选点位置和图标指示位置对不上。3.4 regionchange的防抖与坐标读取bindregionchange事件对象里有个type字段值为begin或end分别代表拖动开始和结束。我们只需要在end时处理。但即便如此用户可能快速连续拖动所以还要加一层时间防抖。let timer null; onRegionChange(e) { if (e.type ! end) return; clearTimeout(timer); timer setTimeout(() { this.getCenterLocation(); }, 300); } getCenterLocation() { const mapCtx wx.createMapContext(map, this); mapCtx.getCenterLocation({ success: (res) { this.setData({ latitude: res.latitude, longitude: res.longitude }); this.reverseGeocode(res.latitude, res.longitude); } }); }getCenterLocation拿到的是地图当前中心点的经纬度这个坐标就是用户选中的位置。300ms 的延迟是实测下来比较舒服的值太短了请求太频繁太长了用户觉得反应慢。4. 逆地址解析把经纬度变成人能看懂的地址4.1 逆解析接口的调用与返回结构拿到经纬度之后要把它变成某某市某某区某某路某某号这样的文字靠的是逆地址解析接口。用 SDK 调用reverseGeocode(lat, lng) { qqmapsdk.reverseGeocoder({ location: { latitude: lat, longitude: lng }, get_poi: 1, poi_options: policy2;page_size10, success: (res) { const { address, formatted_addresses, address_component, pois } res.result; this.setData({ address: formatted_addresses.recommend, province: address_component.province, city: address_component.city, district: address_component.district, pois: pois || [] }); }, fail: (err) { console.error(逆解析失败, err); } }); }返回结构里几个字段要重点理解。address是标准地址formatted_addresses.recommend是推荐地址更适合展示给用户address_component是结构化的省市区街道信息pois是附近的兴趣点列表。get_poi: 1这个参数打开后返回结果里会带上附近的 POIPoint of Interest兴趣点比如某某大厦某某地铁站。这个非常有用因为用户选点的时候往往更愿意选一个明确的 POI 而不是一串门牌号。你可以把 POI 列表展示在地址栏下方让用户点选体验会好很多。4.2 poi_options参数的取舍poi_options控制 POI 的返回策略。policy2表示按距离排序page_size控制返回数量。这里有个经验page_size 不要设太大10 到 20 足够。设太大不仅响应变慢而且用户根本看不过来反而干扰选择。另外POI 数据里有些是重复的或者质量不高的前端展示时最好做一层过滤比如过滤掉没有名称的、或者名称明显是乱码的。4.3 逆解析的调用频率控制与缓存逆解析接口是有配额限制的免费额度对个人开发者够用但如果你用户量大就要注意控制调用量。除了前面说的防抖还有两个优化点。一是相同坐标不重复请求。用户可能来回拖动又拖回原位如果坐标变化很小比如小数点后四位以内可以认为位置没变直接用缓存结果。可以维护一个简单的缓存对象key 用坐标的字符串形式。二是失败重试要有节制。逆解析偶尔会因为网络抖动失败但不要无脑重试最多重试一次并且加个短延迟。无节制重试在弱网环境下会雪上加霜。提示逆解析返回的formatted_addresses.recommend有时候会带上附近这样的模糊词如果业务对地址精度要求高建议用address字段而不是recommend或者两者结合判断。5. 路线规划驾车、步行、骑行的接口选型与参数细节5.1 三种出行方式的接口差异腾讯位置服务的路线规划分驾车direction、步行walking、骑行bicycling和公交transit几类。小程序 SDK 里对应的方法名不同参数结构也有差异。驾车规划最复杂因为它要考虑路况、避让、途经点等。步行和骑行相对简单主要是距离和耗时。公交规划最特殊它需要城市信息而且返回的是换乘方案结构和其他几种完全不同。选哪个接口取决于你的业务场景。外卖配送看骑手路线用骑行用户导航到店用步行或驾车同城物流用驾车。不要图省事全用驾车因为驾车路线可能绕行单行道对步行来说完全不合理。5.2 驾车规划的关键参数qqmapsdk.direction({ mode: driving, from: { latitude: 39.98, longitude: 116.30 }, to: { latitude: 39.90, longitude: 116.40 }, waypoints: , policy: LEAST_TIME, success: (res) { const route res.result.routes[0]; const polyline this.formatPolyline(route.polyline); this.setData({ polyline, distance: route.distance, duration: route.duration }); } });policy参数控制路线策略可选值包括LEAST_TIME最少时间、LEAST_DISTANCE最短距离、AVOID_HIGHWAY不走高速等。默认是最少时间。如果你的场景对距离敏感比如按里程计费就要显式指定LEAST_DISTANCE。waypoints是途经点格式是坐标数组的字符串。做多点配送的时候会用到但注意途经点数量有限制一般不超过 6 个。5.3 polyline的解析与地图渲染路线规划返回的polyline是一串压缩过的坐标需要解压才能用。SDK 里通常提供了tranPolylines之类的辅助方法但不同版本方法名可能不同。如果 SDK 没提供就得自己解压。解压后的坐标数组要转成 map 组件polyline属性需要的格式formatPolyline(coors) { const points coors.map(item ({ latitude: item.latitude, longitude: item.longitude })); return [{ points, color: #3B82F6, width: 6, arrowLine: true }]; }arrowLine: true会在线条上显示方向箭头导航场景下很有用。color和width按你的设计规范来。这里有个性能注意点路线很长时坐标点可能上千个全部渲染到地图上会有卡顿。实测下来可以对坐标做抽稀处理比如每隔几个点取一个视觉上几乎看不出差别但渲染压力小很多。5.4 起终点marker与视野自适应路线画出来之后还要把起点和终点标记出来并且让地图自动缩放到能显示整条路线的范围。标记用markers属性起终点用不同图标区分。视野自适应用includePoints方法const mapCtx wx.createMapContext(map, this); mapCtx.includePoints({ points: [fromPoint, toPoint], padding: [80, 80, 80, 80] });padding是四周留白单位是像素。留白太小路线会贴边太大又浪费空间80 左右比较合适。注意includePoints要在 polyline 渲染完成后再调用否则可能算不准范围。6. 那些文档里不写、但一定会踩的坑6.1 坐标系问题你以为的坐标不是你以为的这是最隐蔽也最致命的坑。GPS 原始坐标WGS84、国测局坐标GCJ02、百度坐标BD09是几套不同的坐标系同一个地点在不同坐标系下的经纬度数值是不一样的。腾讯位置服务用的是 GCJ02而wx.getLocation默认返回的也是 GCJ02type: gcj02。如果你从其他来源拿到 WGS84 的坐标直接丢给腾讯的接口位置会偏移几百米。我遇到过一个案例某团队从硬件设备上报的 GPS 坐标直接拿来做逆解析结果地址全错排查了两天才发现是坐标系没转换。所以记住一条所有进入腾讯位置服务接口的坐标都必须是 GCJ02。如果你的数据源是 WGS84先转换。6.2 授权时机的处理wx.getLocation需要用户授权scope.userLocation。如果用户第一次拒绝了再次调用会直接失败需要引导用户去设置页手动打开。这个流程要处理好否则用户会卡在定位失败的界面出不去。wx.getSetting({ success: (res) { if (!res.authSetting[scope.userLocation]) { wx.authorize({ scope: scope.userLocation, success: () { /* 授权成功 */ }, fail: () { wx.showModal({ title: 需要位置权限, content: 请在设置中打开位置权限, success: (r) { if (r.confirm) wx.openSetting(); } }); } }); } } });另外从较新的基础库版本开始wx.getLocation还需要在app.json里声明requiredPrivateInfos字段把getLocation和chooseLocation加进去否则真机上调用会失败。这个改动是后来才加的很多老教程里没有容易漏。6.3 地图组件的层级问题小程序的map组件是原生组件层级最高普通view盖不住它。所以地图上的悬浮元素必须用cover-view和cover-image。但cover-view的能力有限不支持很多 CSS 属性也不支持嵌套普通组件。如果你的选点界面有复杂的浮层比如搜索框、地址列表要么用cover-view硬做要么把地图区域缩小浮层放在地图外面。我个人的做法是地图占上半屏地址信息和 POI 列表放下半屏这样既避开了 cover-view 的限制交互也更清晰。全屏地图加浮层的方案看起来酷但实现成本高而且在小屏手机上体验并不好。6.4 真机与开发者工具的差异开发者工具里的地图是模拟的和真机行为有差异。比如regionchange的触发频率、getCenterLocation的精度、polyline 的渲染效果真机上都可能不一样。所以地图相关的功能一定要在真机上测尤其是 iOS 和 Android 的差异。我遇到过 Android 上 polyline 不显示箭头、iOS 上 cover-view 位置偏移的问题都是工具里看不出来的。7. 性能与体验优化让选点流程更顺滑7.1 减少不必要的接口调用前面提了防抖和缓存这里再补充一个策略分级请求。用户拖动地图时先用本地已有的数据做粗略展示等停止拖动后再请求精确的逆解析。如果用户只是微调位置可以复用上一次的 POI 列表只更新坐标。另外逆解析和 POI 搜索可以合并成一次请求get_poi: 1就做到了不要分开调两个接口那样请求数翻倍。7.2 地图初始化的优化地图首次加载时如果直接定位到用户当前位置需要等getLocation返回这期间地图是空白的。优化做法是给一个默认的中心点比如城市中心先渲染地图等定位返回后再moveToLocation平滑移动过去。这样用户感知上地图是立刻出来的。onLoad() { this.setData({ latitude: 39.908, // 默认中心点 longitude: 116.397, scale: 16 }); this.locateUser(); }7.3 路线规划的按需加载路线规划不是每次选点都需要。如果用户只是选个地址不需要画路线那就不要调路线规划接口。把路线规划做成一个独立的触发动作比如用户点击查看路线按钮既省配额又省流量。如果确实需要实时显示路线比如打车场景那要注意起终点变化时的请求节流。用户拖动起点时不要每动一下都重新规划等确定后再请求。8. 从选点到导航一个完整链路的串联思路把前面这些串起来一个完整的选点加路线规划流程大概是这样的页面加载地图以默认中心点渲染同时请求用户定位权限定位成功后地图平滑移动到用户位置触发一次逆解析展示当前地址用户拖动地图选点停止拖动后防抖请求逆解析更新地址和 POI 列表用户从 POI 列表中选择或确认地址记录最终坐标和地址文本如果需要路线以用户位置为起点、选中点为终点调用对应出行方式的规划接口解析 polyline 渲染到地图标记起终点调用 includePoints 自适应视野展示距离、预计耗时等信息这个链路里每一步都有降级方案。定位失败就用默认中心点逆解析失败就提示用户手动输入路线规划失败就只显示直线距离。不要因为某一个环节失败就让整个页面不可用这是地图类功能的基本素养。关于配额免费版腾讯位置服务的日调用量对中小项目是够的但如果你做的是高频场景比如每次滑动都请求很容易超。所以前面反复强调的防抖、缓存、按需加载不只是体验优化也是成本控制。最后说一个我自己的习惯把地图相关的配置和 key 抽到一个单独的配置文件里不要散落在各个页面。因为 key 可能会换、配额策略可能会调、默认中心点可能会改集中管理省得到处找。这个习惯在项目变大之后会感谢自己。地图选点和路线规划这套东西技术难度不算高但细节密度大坑也密。把坐标系、授权、层级、防抖这几件事处理明白基本就能稳定跑了。剩下的就是根据你的业务场景去打磨交互让用户选地址这件事变得不那么烦人。