当前位置：首页 > news >正文

HarmonyOS：Map Kit简介

news 来源：原创 2025/5/21 22:09:55

一、概述

Map Kit（地图服务） 为开发者提供强大而便捷的地图能力，助力全球开发者实现个性化显示地图、位置搜索和路径规划等功能，轻松完成地图构建工作。您可以轻松地在HarmonyOS应用/元服务中集成地图相关的功能，全方位提升用户体验。

Map Kit提供了全球3.2亿的 Poi（Point of Interest，兴趣点）。在地图表达中，一个 Poi 可代表一家商铺、一栋办公楼、一处景点等等。

Map Kit不断优化丰富地图的细节呈现能力，例如在Poi和路网信息展示方面，根据Poi属性信息及区域路网差异，在不同层级比例尺条件下，为用户展示更合适的Poi和路网信息。手势交互方面，提供了包括缩放、旋转、移动、倾斜等流畅的交互体验。

二、场景介绍

中国大陆使用GCJ02坐标系，中国台湾和海外使用WGS84坐标系。详见下文坐标转换。

Map Kit提供以下功能，满足绝大多数地图开发的需求：

创建地图： 呈现内容包括建筑、道路、水系等。
地图交互： 控制地图的交互手势和交互按钮。
在地图上绘制： 添加位置标记、覆盖物以及各种形状等。
位置搜索： 多种查询Poi信息的能力。
路径规划： 提供驾车、步行、骑行路径规划能力。
静态图： 获取一张地图图片。
地图Picker： 提供地点详情展示控件、地点选取控件、区划选择控件。
通过Petal 地图应用实现导航等能力： 查看位置详情、查看路径规划、发起导航、发起内容搜索。
地图计算工具： 华为地图涉及的2种坐标系及其使用区域和转换。

三、坐标转换

华为地图在中国大陆使用GCJ02坐标系，若使用WGS84坐标系直接叠加在华为地图上，因坐标值不同，展示位置会有偏移。所以，在中国大陆如果使用WGS84坐标调用Map Kit服务，需要先将其转换为GCJ02坐标系再访问。

3.1 接口说明

以下是坐标转换功能相关接口，主要由map命名空间下的convertCoordinateSync、rectifyCoordinate方法提供，更多接口及使用方法请参见接口文档。

接口名	描述
mapCommon.CoordinateType	坐标系类型。
convertCoordinateSync(fromType: mapCommon.CoordinateType, toType: mapCommon.CoordinateType, location: mapCommon.LatLng): mapCommon.LatLng	坐标转换，将WGS84坐标系转换为GCJ02坐标系。
rectifyCoordinate(context: common.Context, locations: Array<mapCommon.CoordinateLatLng>): Promise<Array<mapCommon.CoordinateLatLng>>	坐标纠偏。
mapCommon.LatLng	经纬度对象。

3.2 开发步骤

3.2.1 导入相关模块。

import { map, mapCommon } from '@kit.MapKit';

3.2.2 坐标转换

初始化需要转换的坐标，调用convertCoordinateSync方法转换坐标。

let wgs84Position: mapCommon.LatLng = {
  latitude: 30,
  longitude: 118
};
// 转换经纬度坐标
let gcj02Position: mapCommon.LatLng =
  map.convertCoordinateSync(mapCommon.CoordinateType.WGS84, mapCommon.CoordinateType.GCJ02, wgs84Position);

3.2.3 坐标纠偏

rectifyCoordinate接口根据输入的坐标系和坐标，判断是否需要纠偏坐标，规则如下：

输入的坐标系是GCJ02，当前路由地是中国大陆。
检查传入的坐标是否在大陆/港澳地区，如果不在，返回WGS84坐标系和输入的原始坐标，否则返回GCJ02坐标系和输入的原始坐标。
输入的坐标系是GCJ02，当前路由地不是中国大陆。
返回WGS84坐标系和输入的原始坐标。
输入的坐标系是WGS84，当前路由地是中国大陆。
检查传入的坐标是否在大陆/港澳地区，如果在，返回GCJ02坐标系和转换后的坐标，否则返回WGS84坐标系和输入的原始坐标。
输入的坐标系是WGS84，当前路由地不是中国大陆。
返回WGS84坐标系和输入的原始坐标。

说明
rectifyCoordinate接口仅为解决原始坐标与华为地图展示偏转的问题。

let locations: Array<mapCommon.CoordinateLatLng> = [
  {
    // 输入巴黎坐标和GCJ02坐标系，返回WGS84坐标系和输入的巴黎坐标
    coordinateType: mapCommon.CoordinateType.GCJ02,
    location: { latitude: 42.860000, longitude: 2.340000 }
  },
  {
    // 输入香港坐标和GCJ02坐标系，返回GCJ02坐标系和输入的香港坐标
    coordinateType: mapCommon.CoordinateType.GCJ02,
    location: { latitude: 22.280556, longitude: 114.984000 }
  },
  {
    // 输入香港坐标和WGS84坐标系，若当前地图站点使用GCJ02坐标系，返回GCJ02坐标系和转换后的香港坐标，
    // 若当前地图站点使用WGS84坐标系，返回WGS84坐标系和原香港坐标
    coordinateType: mapCommon.CoordinateType.WGS84,
    location: { latitude: 22.280556, longitude: 114.984000 }
  },
  {
    // 输入巴黎坐标和WGS84坐标系，返回WGS84坐标系和输入的巴黎坐标
    coordinateType: mapCommon.CoordinateType.WGS84,
    location: { latitude: 42.860000, longitude: 2.340000 }
  }
];
// 包含await的外层方法需要添加async关键字
let arr: Array<mapCommon.CoordinateLatLng> = await map.rectifyCoordinate(getContext(), locations);