在鸿蒙应用中快速接入地图功能：从配置到实战案例全解析
摘要
现在很多应用都离不开地图，不管是打车软件、外卖配送，还是旅游攻略、运动轨迹记录，地图功能都是刚需。对于鸿蒙（HarmonyOS）开发者来说，想要快速接入地图，可以直接用华为 HMS 提供的 Map Kit。它帮我们封装好了地图展示、标记点、路径绘制等功能，开发者只需要做一些配置，就能在应用里轻松集成。本文会带你从零开始，一步步实现一个“地图展示 + 标记点点击”的小 Demo，并结合几个实际场景来说明用法。
引言
随着鸿蒙生态的发展，越来越多的应用都需要用到位置和地图相关的能力。比如：
- 出行类应用（查看附近的地铁站、公交站）
- 本地生活类应用（展示商家位置，点开导航）
- 社交类应用（发送实时位置，约朋友见面）
如果你在做鸿蒙应用，想在页面里放一个可交互的地图，Map Kit 就是最直接的选择。接下来我们会从依赖配置、API Key 获取、代码接入三个步骤，带你跑通一个可运行的 Demo。
配置依赖和 API Key
添加依赖
首先要在 oh-package.json5 中加上 Map Kit 的依赖：
"dependencies": {"@hw-agconnect/map": "x.x.x" // 建议用最新版本
}
这样应用就能识别 Map Kit 提供的 Map 组件了。
申请 API Key
然后去 华为开发者联盟 申请一个 Map Kit API Key，在应用的 AppScope/app.json5 里加上：
"app": {"apiKey": "你的API_KEY"
}
这个 Key 就是你调用 Map Kit 功能的凭证，没有的话地图不会正常显示。
在页面中接入地图
下面我们写一个简单的页面，打开就能看到一张地图，并且设置初始中心点和缩放级别。
// pages/Index.ets
import map from '@hw-agconnect/map';@Entry
@Component
struct IndexPage {build() {Column() {map.Map({mapType: map.MapType.NORMAL, // 普通地图zoom: 12, // 缩放等级center: { lat: 31.2304, lng: 121.4737 } // 初始中心点：上海}).width('100%').height('100%')}}
}
这样运行后，你就能在页面里看到一个居中的上海地图了。
给地图加上标记点
地图光能显示还不够，大多数时候我们要标记一些点，提示用户某个位置。比如在上海人民广场加一个 Marker：
map.addMarker({position: { lat: 31.2304, lng: 121.4737 },title: "上海市中心",snippet: "人民广场"
});
运行后，地图上就会出现一个标记点，点击还能看到提示信息。
Demo：地图 + 标记点点击事件
我们把前面的内容合在一起，做一个可运行的小 Demo：在地图上显示上海，并在人民广场加个标记点，点击 Marker 时弹出提示。
// pages/Index.ets
import map from '@hw-agconnect/map';
import prompt from '@ohos.prompt';@Entry
@Component
struct IndexPage {build() {Column() {map.Map({mapType: map.MapType.NORMAL,zoom: 12,center: { lat: 31.2304, lng: 121.4737 }}).onReady((mapInstance) => {const marker = mapInstance.addMarker({position: { lat: 31.2304, lng: 121.4737 },title: "上海市中心",snippet: "人民广场"});marker.onClick(() => {prompt.showToast({message: "你点击了人民广场标记点"});});}).width('100%').height('100%')}}
}
这个 Demo 运行后，地图会加载出来，点击标记点会在页面底部弹出 Toast。
实际应用场景举例
外卖/商家定位
用户下单后，页面展示商家位置，点击标记点显示“商家详情”。
marker.onClick(() => {prompt.showToast({message: "商家：张三烧烤 · 点击查看更多信息"});
});
这样用户可以快速确认商家在地图上的位置。
出行/导航起点终点
比如打车应用，要同时显示起点和终点，并画一条连线。
const start = mapInstance.addMarker({position: { lat: 31.2243, lng: 121.4768 },title: "出发地"
});
const end = mapInstance.addMarker({position: { lat: 31.2400, lng: 121.4900 },title: "目的地"
});// 绘制路线
mapInstance.addPolyline({points: [{ lat: 31.2243, lng: 121.4768 },{ lat: 31.2400, lng: 121.4900 }],color: "#FF0000",width: 5
});
这样地图就能同时展示出行的起止点和路径。
运动轨迹记录
比如跑步 APP，可以记录用户的 GPS 点，并实时在地图上画线。
mapInstance.addPolyline({points: userRunTrack, // 实时追加的经纬度数组color: "#00FF00",width: 4
});
用户边跑边更新轨迹，最后生成完整路线。
QA 环节
Q1：为什么地图加载不出来？
A1：先检查 API Key 是否配置正确，其次确认设备联网。还要确保依赖包版本和 SDK 配置正确。
Q2：可以离线用吗？
A2：目前 Map Kit 主要依赖网络，离线支持有限。常见做法是预加载地图切片或缓存路线。
Q3：能不能自定义 Marker 图标？
A3：可以，Map Kit 提供了自定义 Marker 的 API，可以用自己的图片替换默认样式。
总结
在鸿蒙应用里集成地图功能，其实就是三步：
- 配置 Map Kit 依赖和 API Key；
- 在页面里使用 Map 组件展示地图；
- 根据需求加 Marker、路线、事件监听等。
通过一个简单的 Demo，我们就能跑通地图展示和标记点交互。结合实际应用场景，比如商家定位、导航、运动轨迹，Map Kit 能覆盖大多数常见需求。如果你正在开发和位置相关的鸿蒙应用，不妨试试把地图集成进来。