鸿蒙 uni-app x map 组件腾讯地图适配与排障

鸿蒙专家

在鸿蒙平台做地图能力，uni-app x 的 map 组件是常用方案：它用于在页面中嵌入地图，承载位置、标记点、路线、多边形等展示。该组件从 HarmonyOS 4.61 开始支持，目前鸿蒙平台只支持腾讯地图，App 和 Web 端必须在 manifest 中配置腾讯地图 Key，否则地图不会显示。

兼容性与前置配置

鸿蒙平台只支持腾讯地图，不支持高德和 Google。App 端和 Web 端需要在 manifest 中配置 Key，微信小程序则在小程序后台配置。一个典型的 manifest 配置如下：

2. {
3.   "app-plus": {
4.     "modules": {
5.       "Maps": {}
6.     },
7.     "distribute": {
8.       "sdkConfigs": {
9.         "maps": {
10.           "tencent": {
11.             "appkey": "你的腾讯地图Key"
12.           }
13.         }
14.       }
15.     }
16.   }
17. }

复制代码

配置完成后，就可以在页面中声明 map。最基础的使用只需要经纬度和缩放级别：

2. <template>
3.   <map :longitude="116.39747" :latitude="39.9085" :scale="16"
4.        style="width: 100%; height: 300px;"></map>
5. </template>

复制代码

核心属性与覆盖物

map 的属性很多，开发中高频使用的是 longitude、latitude、scale 和 markers。除此之外，polyline、polygons、circles 分别用于路线、多边形和圆。显示控制类属性包括 show-location、show-compass、enable-satellite、enable-traffic 等，角度控制类属性也有对应配置。

markers 是最常用的标记点属性，可设置 id、经纬度、标题、图标、宽高、锚点和气泡：

2. const markers = [
3.   {
4.     id: 1,
5.     latitude: 39.9085,
6.     longitude: 116.39747,
7.     title: '天安门',
8.     iconPath: '/static/marker.png',
9.     width: 30,
10.     height: 30,
11.     anchor: { x: 0.5, y: 1 },
12.     callout: {
13.       content: '天安门广场',
14.       color: '#333333',
15.       fontSize: 14,
16.       borderRadius: 5,
17.       bgColor: '#ffffff',
18.       padding: 8,
19.       display: 'ALWAYS'
20.     } as MapMarkerCallout
21.   }
22. ]

复制代码

其中 MapMarkerCallout 控制气泡，display 常用 ALWAYS 和 BYCLICK，前者常显，后者点击标记点后显示。

polyline 用于画路线，支持颜色、线宽、虚线、箭头线、边框等设置：

2. const polyline = [
3.   {
4.     points: [
5.       { latitude: 39.9085, longitude: 116.39747 },
6.       { latitude: 39.9086, longitude: 116.40747 },
7.       { latitude: 39.9087, longitude: 116.41747 }
8.     ],
9.     color: '#2196F3',
10.     width: 6,
11.     dottedLine: false,
12.     arrowLine: true,
13.     borderColor: '#1565C0',
14.     borderWidth: 2
15.   }
16. ]

复制代码

polygons 可画多边形区域，常用 points、fillColor、strokeWidth、strokeColor；circles 可画圆，常用 latitude、longitude、radius、color、fillColor、strokeWidth。

常见实战场景

场景一：显示当前位置。搭配 uni.getLocation 获取定位，再把 longitude、latitude 绑定到 map，并设置 show-location。原文示例使用 type: 'gcj02'，成功回调中更新经纬度。

场景二：显示多个标记点。准备 markers 数组，每个对象包含 id、经纬度、title、iconPath、width、height，然后把数组传给 :markers。

场景三：画路线。把起点和终点放进 markers，同时构造 polyline.points，并用 include-points 圈定起终点，让地图自动缩放以显示完整路线。

场景四：标记点点击事件。监听 @markertap，在回调里读取 event.detail.markerId，再通过 id 查找对应 marker 信息。

场景五：视野变化监听。监听 @regionchange，event.detail.causedBy 可取 drag、scale、update，分别表示拖动、缩放和更新导致。

场景六：卫星图和实时路况。给 map 设置 enable-satellite 和 enable-traffic 即可开启。

MapContext 与地图方法

通过 uni.createMapContext('myMap') 获取地图上下文后，可以调用地图方法。原文列出的能力包括：moveToLocation 移动到指定位置，getCenterLocation 获取中心坐标，getRegion 获取视野范围，getScale 获取缩放级别，translateMarker 平移标记点，addMarkers 添加标记点，removeMarkers 移除标记点。

2. const mapContext = uni.createMapContext('myMap')
3. mapContext.getCenterLocation({
4.   success: (res) => {
5.     console.log('中心坐标：', res.latitude, res.longitude)
6.   }
7. })

复制代码

鸿蒙平台专属实现与取舍

鸿蒙平台使用 ArkUI 的 map 组件做原生实现，优势是性能好、交互流畅。鸿蒙原生开发中地图使用 MapComponent：

2. MapComponent({
3.   mapOptions: {
4.     position: {
5.       target: { latitude: 39.9085, longitude: 116.39747 },
6.       zoom: 16
7.     }
8.   }
9. })
10. .width('100%')
11. .height(300)

复制代码

对比来看，uni-app x 的 map 属性更丰富，markers、polyline、polygons 等覆盖物功能在鸿蒙原生中需要自行实现。鸿蒙平台还支持个性化地图 layer-style，可用于暗黑模式等自定义样式，但需要在腾讯位置服务后台创建样式并绑定 Key。

踩坑与排障清单

1. 必须配置地图 Key。App 和 Web 端如果未在 manifest 中配置腾讯地图 Key，地图不会显示。
2. 鸿蒙只支持腾讯地图。高德和 Google 在鸿蒙平台不可用，如果原项目使用高德，需要切换到腾讯。
3. iconPath 推荐使用本地路径，例如 /static 目录。网络图片可能加载失败。
4. scale 范围有差异。Web 端为 5-18，App 端为 3-20，超出范围会被截断。
5. include-points 至少需要 2 个坐标点，否则不生效。
6. callout 的 display 控制气泡时机：ALWAYS 一直显示，BYCLICK 点击标记点显示。
7. controls 属性在微信小程序已废弃，建议使用 cover-view 替代。

总结

uni-app x 的 map 组件是嵌入地图的标准方案。鸿蒙适配时要先确认 HarmonyOS 4.61 及以上版本，并配置腾讯地图 Key；鸿蒙端只支持腾讯地图。日常开发优先掌握 longitude、latitude、scale、markers，再按需使用 polyline、polygons、circles、事件和 MapContext。markers 最常用，polyline 画路线方便，include-points 可自动缩放视野，MapContext 则负责调用地图方法。