鸿蒙 uni-app x map 组件腾讯地图适配与排障
在鸿蒙平台做地图能力，uni-app x 的 map 组件是常用方案：它用于在页面中嵌入地图，承载位置、标记点、路线、多边形等展示。该组件从 HarmonyOS 4.61 开始支持，目前鸿蒙平台只支持腾讯地图，App 和 Web 端必须在 manifest 中配置腾讯地图 Key，否则地图不会显示。兼容性与前置配置
鸿蒙平台只支持腾讯地图，不支持高德和 Google。App 端和 Web 端需要在 manifest 中配置 Key，微信小程序则在小程序后台配置。一个典型的 manifest 配置如下：
{
"app-plus": {
"modules": {
"Maps": {}
},
"distribute": {
"sdkConfigs": {
"maps": {
"tencent": {
"appkey": "你的腾讯地图Key"
}
}
}
}
}
}
配置完成后，就可以在页面中声明 map。最基础的使用只需要经纬度和缩放级别：
<template>
<map :longitude="116.39747" :latitude="39.9085" :scale="16"
style="width: 100%; height: 300px;"></map>
</template>
核心属性与覆盖物
map 的属性很多，开发中高频使用的是 longitude、latitude、scale 和 markers。除此之外，polyline、polygons、circles 分别用于路线、多边形和圆。显示控制类属性包括 show-location、show-compass、enable-satellite、enable-traffic 等，角度控制类属性也有对应配置。
markers 是最常用的标记点属性，可设置 id、经纬度、标题、图标、宽高、锚点和气泡：
const markers = [
{
id: 1,
latitude: 39.9085,
longitude: 116.39747,
title: '天安门',
iconPath: '/static/marker.png',
width: 30,
height: 30,
anchor: { x: 0.5, y: 1 },
callout: {
content: '天安门广场',
color: '#333333',
fontSize: 14,
borderRadius: 5,
bgColor: '#ffffff',
padding: 8,
display: 'ALWAYS'
} as MapMarkerCallout
}
]
其中 MapMarkerCallout 控制气泡，display 常用 ALWAYS 和 BYCLICK，前者常显，后者点击标记点后显示。
polyline 用于画路线，支持颜色、线宽、虚线、箭头线、边框等设置：
const polyline = [
{
points: [
{ latitude: 39.9085, longitude: 116.39747 },
{ latitude: 39.9086, longitude: 116.40747 },
{ latitude: 39.9087, longitude: 116.41747 }
],
color: '#2196F3',
width: 6,
dottedLine: false,
arrowLine: true,
borderColor: '#1565C0',
borderWidth: 2
}
]
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 移除标记点。
const mapContext = uni.createMapContext('myMap')
mapContext.getCenterLocation({
success: (res) => {
console.log('中心坐标：', res.latitude, res.longitude)
}
})
鸿蒙平台专属实现与取舍
鸿蒙平台使用 ArkUI 的 map 组件做原生实现，优势是性能好、交互流畅。鸿蒙原生开发中地图使用 MapComponent：
MapComponent({
mapOptions: {
position: {
target: { latitude: 39.9085, longitude: 116.39747 },
zoom: 16
}
}
})
.width('100%')
.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 则负责调用地图方法。
Re: 鸿蒙 uni-app x map 组件腾讯地图适配与排障
感谢楼主整理，这篇把鸿蒙上 uni-app x 的 map 组件从配置到覆盖物再到常见场景都串起来了，很实用。我目前也在做鸿蒙地图，正好卡在腾讯地图 Key 配置后地图还是不显示的问题上，想问下一般排障顺序是什么？是先看 manifest 里的 appkey 有没有配对，还是看腾讯地图后台的包名和 Bundle ID 绑定？另外文中提到鸿蒙只支持腾讯地图，那如果原来项目用的是高德或 Google，迁移时是不是地图相关能力都得重做一遍？ 还有几个实际点想请教：markers 的图标路径在鸿蒙上有没有限制，网络图片能不能用；polyline 的箭头线和边框在鸿蒙上显示效果和 App 端一致吗；MapContext 里的 addMarkers、removeMarkers 这些方法在鸿蒙有没有已知限制或兼容问题。如果后面能补一个最小排障清单，比如 Key 不生效、标记点不显示、定位偏移分别先查哪里，就更好了。先收藏，等更新。Re: 鸿蒙 uni-app x map 组件腾讯地图适配与排障
感谢楼主整理，鸿蒙 uni-app x 的 map 走腾讯地图这个限制确实容易踩坑，尤其 manifest 里 Maps 模块和 sdkConfigs 下 tencent.appkey 没配好就直接不显示，这点很关键。markers 的 callout 用 ALWAYS/BYCLICK 控制气泡、polyline 的 arrowLine 和 border 这些细节写得很清楚，后面做路线和标记点点击能少绕不少弯。想请教下，如果按这个配置后地图白屏，一般优先检查 Key 是否和当前应用匹配、Maps 模块有没有打进去，还是先确认 HarmonyOS 版本到了 4.61？另外 show-location 配合 uni.getLocation 时坐标类型用 gcj02 就能直接和腾讯地图对上吧？Re: 鸿蒙 uni-app x map 组件腾讯地图适配与排障
感谢楼主整理，这篇对鸿蒙上 uni-app x 的 map 组件讲得很清楚。腾讯地图 Key 必须在 manifest 里配好，否则地图不显示，这个点确实很关键。markers 的气泡、polyline 的箭头线和边框、polygons 和 circles 的常用属性，还有 include-points 自动缩放，都是实际开发里很容易用到的。六个实战场景也基本覆盖了定位、标记、路线、点击事件、视野监听和卫星路况这些常见需求，后面做鸿蒙地图功能时可以对照着排查。MapContext 里的 moveToLocation、getCenterLocation、getRegion、translateMarker、addMarkers 和 removeMarkers 也列得很明白，先收藏了，回头在项目里试试。
页:
[1]