在鸿蒙应用中快速接入地图功能：从配置到实战案例全解析

摘要

现在很多应用都离不开地图，不管是打车软件、外卖配送，还是旅游攻略、运动轨迹记录，地图功能都是刚需。对于鸿蒙（HarmonyOS）开发者来说，想要快速接入地图，可以直接用华为 HMS 提供的 Map Kit。它帮我们封装好了地图展示、标记点、路径绘制等功能，开发者只需要做一些配置，就能在应用里轻松集成。本文会带你从零开始，一步步实现一个"地图展示 + 标记点点击"的小 Demo，并结合几个实际场景来说明用法。

引言

随着鸿蒙生态的发展，越来越多的应用都需要用到位置和地图相关的能力。比如：

出行类应用（查看附近的地铁站、公交站）
本地生活类应用（展示商家位置，点开导航）
社交类应用（发送实时位置，约朋友见面）

如果你在做鸿蒙应用，想在页面里放一个可交互的地图，Map Kit 就是最直接的选择。接下来我们会从依赖配置、API Key 获取、代码接入三个步骤，带你跑通一个可运行的 Demo。

配置依赖和 API Key

添加依赖

首先要在 oh-package.json5 中加上 Map Kit 的依赖：

json 复制代码

"dependencies": {
  "@hw-agconnect/map": "x.x.x"   // 建议用最新版本
}

这样应用就能识别 Map Kit 提供的 Map 组件了。

申请 API Key

然后去华为开发者联盟申请一个 Map Kit API Key ，在应用的 AppScope/app.json5 里加上：

json 复制代码

"app": {
  "apiKey": "你的API_KEY"
}

这个 Key 就是你调用 Map Kit 功能的凭证，没有的话地图不会正常显示。

在页面中接入地图

下面我们写一个简单的页面，打开就能看到一张地图，并且设置初始中心点和缩放级别。

ts 复制代码

// 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：

ts 复制代码

map.addMarker({
  position: { lat: 31.2304, lng: 121.4737 },
  title: "上海市中心",
  snippet: "人民广场"
});

运行后，地图上就会出现一个标记点，点击还能看到提示信息。

Demo：地图 + 标记点点击事件

我们把前面的内容合在一起，做一个可运行的小 Demo：在地图上显示上海，并在人民广场加个标记点，点击 Marker 时弹出提示。

ts 复制代码

// 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。

实际应用场景举例

外卖/商家定位

用户下单后，页面展示商家位置，点击标记点显示"商家详情"。

ts 复制代码

marker.onClick(() => {
  prompt.showToast({
    message: "商家：张三烧烤 · 点击查看更多信息"
  });
});

这样用户可以快速确认商家在地图上的位置。

出行/导航起点终点

比如打车应用，要同时显示起点和终点，并画一条连线。

ts 复制代码

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 点，并实时在地图上画线。

ts 复制代码

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 能覆盖大多数常见需求。如果你正在开发和位置相关的鸿蒙应用，不妨试试把地图集成进来。