大家好,我是[晚风依旧似温柔],新人一枚,欢迎大家关注~

前言

在地图类应用开发中,很多开发者可能都遇到过这样一个幽灵问题:通过设备的 GPS 获取了当前的经纬度,或者从后端接口拉取了目标位置的数据,在控制台打印出来的数字与数据库中完全一致。但是,当调用 Map Kit 的接口将这个坐标作为 Marker(标记)绘制到地图上时,却发现图标偏离了实际位置几百米——原本应该在马路上的 Marker,却“漂”到了旁边的河里或建筑物上。

如果只看表现,很容易误以为是定位不准或者组件渲染异常。但实际上,这往往是因为忽略了一个核心的地理信息概念:坐标系不匹配。

根据 HarmonyOS Map Kit 官方文档的明确说明,由于地图数据的合规与标准要求,中国大陆、中国香港、中国澳门地区使用的坐标系为 GCJ02,而其他部分地区使用的是 WGS84。

这就意味着,如果直接将设备底层返回的 WGS84 坐标原封不动地绘制在 GCJ02 坐标系的地图上,必然会产生偏移。这篇文章,我们就以 HarmonyOS Map Kit 为基础,理清坐标系引发的偏移问题,并给出可复现的转换和排查方案。

一、现象:为什么经纬度正确,Marker 却偏了?

单纯的一组数字(如 Latitude: 39.9042, Longitude: 116.4074)如果在没有指定“参照系”的情况下,是没有任何实际意义的。地球并不是一个完美的标准球体,为了在二维平面上表示三维的地球,人类制定了多种测量基准和投影方法,这就是坐标系(Coordinate Reference System)。

如果数据的提供方使用的是 A 坐标系,而数据的展示方(地图底图)使用的是 B 坐标系,即使数字一模一样,它们在地图上对应的真实物理位置也是不同的。这就是产生“偏移”的根本原因。

二、先把官方规则和核心概念弄清楚

在排查问题之前,我们需要先明确 HarmonyOS 系统能力中涉及到的两种最常见的坐标系。

1. WGS84(World Geodetic System 1984)

这是国际上广泛使用的全球地理坐标系统,也是 GPS 全球定位系统使用的标准。

  • 在 HarmonyOS 中的来源: 如果你调用 @kit.LocationKit 中的 geoLocationManager.getCurrentLocation() 接口,在获取底层硬件卫星定位时,默认返回的标准经纬度数据就是基于 WGS84 坐标系的。

2. GCJ02(国家测量局02号标准)

这是中国国家测绘局制定的一种坐标系统,国内俗称“火星坐标系”。它是基于 WGS84 经过特定算法加密后得到的结果。

  • 在 HarmonyOS 中的应用: 根据 Map Kit 官方文档,当应用运行并在中国大陆、中国香港、中国澳门地区请求地图服务时,地图的底图瓦片、POI(兴趣点)检索结果、路线规划等,均强制要求或返回 GCJ02 坐标系数据。

核心结论: 当地图组件当前处于 GCJ02 模式时,如果把 LocationKit 取到的 WGS84 数据直接传给 mapController.addMarker(),就会发生数百米的位移。必须先将 WGS84 转换为 GCJ02。

三、判断数据来源,确定是否需要转换

在动手写代码转换之前,建议先梳理清楚当前项目中的数据流向。这是排查地图偏移最关键的一步。

需要转换的场景(WGS84 -> GCJ02):

  1. 直接从 geoLocationManager 获取的设备原始 GPS 坐标,要在国内地图上显示。
  2. 后端服务或第三方硬件(如车载 GPS 终端)上报了标准的 WGS84 坐标,要求在 App 国内地图上绘制。

不需要转换的场景(直接使用):

  1. 调用 Map Kit 自身的 site(位置服务)进行 POI 搜索返回的坐标(已经是 GCJ02)。
  2. 用户在地图上点击(mapController.on("mapClick"))获取的坐标(地图组件返回的就是匹配当前底图的坐标系)。

四、核心代码实现:WGS84 与 GCJ02 的转换与 Marker 绘制

对于这类坐标转换,开发者可以在应用层通过标准的数学算法进行换算。下面提供一个最小化、可复现的实践场景:我们先模拟获取到一个 WGS84 坐标,利用标准算法将其转换为 GCJ02,然后再将其安全地绘制到 MapComponent 上。

1. 权限与工程配置

使用地图和定位,首先需要在 module.json5 中声明网络与定位权限:

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.LOCATION"
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION"
      }
    ]
  }
}

2. ArkTS 坐标转换工具类

以下是业界通用的 WGS84 到 GCJ02 的数学转换算法实现,可以将其封装为一个工具类:

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

export class CoordinateUtil {
  private static readonly PI: number = 3.1415926535897932384626;
  private static readonly A: number = 6378245.0; // 卫星椭球坐标投影到平面地图坐标系的投影因子
  private static readonly EE: number = 0.00669342162296594323; // 椭球的偏心率

  /**
   * 将 WGS84 坐标转换为 GCJ02 坐标
   * @param wgs84Lat WGS84纬度
   * @param wgs84Lng WGS84经度
   * @returns mapCommon.LatLng GCJ02坐标
   */
  public static wgs84ToGcj02(wgs84Lat: number, wgs84Lng: number): mapCommon.LatLng {
    if (this.isOutOfChina(wgs84Lat, wgs84Lng)) {
      // 如果不在中国范围内,官方地图底图可能使用的是 WGS84,不需要转换
      return { latitude: wgs84Lat, longitude: wgs84Lng };
    }

    let dLat = this.transformLat(wgs84Lng - 105.0, wgs84Lat - 35.0);
    let dLng = this.transformLng(wgs84Lng - 105.0, wgs84Lat - 35.0);
    
    let radLat = wgs84Lat / 180.0 * this.PI;
    let magic = Math.sin(radLat);
    magic = 1 - this.EE * magic * magic;
    let sqrtMagic = Math.sqrt(magic);
    
    dLat = (dLat * 180.0) / ((this.A * (1 - this.EE)) / (magic * sqrtMagic) * this.PI);
    dLng = (dLng * 180.0) / (this.A / sqrtMagic * Math.cos(radLat) * this.PI);
    
    return {
      latitude: wgs84Lat + dLat,
      longitude: wgs84Lng + dLng
    };
  }

  // 判断是否在国内的粗略算法(排除法)
  private static isOutOfChina(lat: number, lng: number): boolean {
    if (lng < 72.004 || lng > 137.8347) return true;
    if (lat < 0.8293 || lat > 55.8271) return true;
    return false;
  }

  private static transformLat(x: number, y: number): number {
    let ret = -100.0 + 2.0 * x + 3.0 * y + 0.2 * y * y + 0.1 * x * y + 0.2 * Math.sqrt(Math.abs(x));
    ret += (20.0 * Math.sin(6.0 * x * this.PI) + 20.0 * Math.sin(2.0 * x * this.PI)) * 2.0 / 3.0;
    ret += (20.0 * Math.sin(y * this.PI) + 40.0 * Math.sin(y / 3.0 * this.PI)) * 2.0 / 3.0;
    ret += (160.0 * Math.sin(y / 12.0 * this.PI) + 320 * Math.sin(y * this.PI / 30.0)) * 2.0 / 3.0;
    return ret;
  }

  private static transformLng(x: number, y: number): number {
    let ret = 300.0 + x + 2.0 * y + 0.1 * x * x + 0.1 * x * y + 0.1 * Math.sqrt(Math.abs(x));
    ret += (20.0 * Math.sin(6.0 * x * this.PI) + 20.0 * Math.sin(2.0 * x * this.PI)) * 2.0 / 3.0;
    ret += (20.0 * Math.sin(x * this.PI) + 40.0 * Math.sin(x / 3.0 * this.PI)) * 2.0 / 3.0;
    ret += (150.0 * Math.sin(x / 12.0 * this.PI) + 300.0 * Math.sin(x / 30.0 * this.PI)) * 2.0 / 3.0;
    return ret;
  }
}

3. 在地图组件中应用转换后的坐标

拿到转换后的 GCJ02 坐标,我们就可以放心地调用 MapController 进行 Marker 的绘制。

import { MapComponent, mapCommon, mapCore } from '@kit.MapKit';
import { CoordinateUtil } from '../utils/CoordinateUtil';

@Entry
@Component
struct MapDisplayPage {
  private mapController?: mapCore.MapController;
  
  // 模拟从 LocationKit 或后端拿到的原始 WGS84 坐标(天安门广场附近)
  private rawWgs84Lat: number = 39.9037;
  private rawWgs84Lng: number = 116.3978;

  build() {
    Column() {
      MapComponent({
        mapOptions: {
          position: {
            target: {
              latitude: this.rawWgs84Lat, 
              longitude: this.rawWgs84Lng 
            },
            zoom: 14
          }
        },
        mapCallback: (err, controller) => {
          if (!err) {
            this.mapController = controller;
            this.addMarkerWithConversion();
          }
        }
      })
      .width('100%')
      .height('100%')
    }
  }

  private async addMarkerWithConversion() {
    if (!this.mapController) return;

    // 关键点:将原始 WGS84 坐标转为 GCJ02 坐标
    let gcj02Location = CoordinateUtil.wgs84ToGcj02(this.rawWgs84Lat, this.rawWgs84Lng);

    // 构建 Marker 配置,使用转换后的坐标
    let markerOptions: mapCommon.MarkerOptions = {
      position: gcj02Location,
      title: '转换后的正确位置',
      clickable: true
    };

    // 添加 Marker 到地图
    await this.mapController.addMarker(markerOptions);
    
    // 同时也移动相机的视角到正确的 GCJ02 坐标上
    let cameraUpdate = mapCore.cameraUpdate.newCameraPosition({
      target: gcj02Location,
      zoom: 15
    });
    this.mapController.animateCamera(cameraUpdate, 1000);
  }
}

代码中真正需要关注的是 CoordinateUtil.wgs84ToGcj02 这一步。很多时候开发者习惯拿到数据就直接传给 markerOptions.position,只要加了这一层拦截并确认当前地区的底图标准,绝大多数的“幽灵偏移”都会消失。

五、第三方后端坐标数据怎么约定?

很多应用不只是前端自己定位,还会与后端进行大量的位置数据交互。如果只是前端自己处理了,但后端存的依然是一笔“糊涂账”,将来无论是做空间检索(比如“附近的人”)还是围栏报警,都会出问题。

这里建议和后端确立以下契约:

  1. 数据库统一存储基准: 建议数据库中统一以 WGS84 标准进行存储。因为这是国际标准,兼容性最强。

  2. API 接口显式声明坐标系: JSON 数据中,绝不能只传 lat 和 lng,必须带上 coordinate_type 字段。

    {
      "userId": "1001",
      "location": {
        "latitude": 39.9037,
        "longitude": 116.3978,
        "coordinateType": "WGS84"
      }
    }
    
  3. 前端拿到数据后,首先检查 coordinateType,如果是 WGS84 且当前地图环境是国内,则在组件渲染前调用转化方法。如果是 GCJ02 则直接渲染。

六、地图项目最容易留下的隐性 Bug

在开发 HarmonyOS 的地图应用时,由于 Map Kit 会自动根据国家和地区切换地图服务数据源,有两个极易被忽视的坑点值得单独注意。

1. 跨国界用户的“反向偏移”
Map Kit 官方明确区分了中国大陆、中国香港、中国澳门地区与其他地区。这意味着,如果用户的设备拿着你的 App 出国了,当地的地图底层瓦片会切回 WGS84。
此时如果你还在代码里不加判断地把所有 GPS 数据强行转换为 GCJ02,就会造成反向偏移。因此,转换工具类中的 isOutOfChina 判断逻辑极其重要,它决定了在非中国区域应当退回使用原始 WGS84 数据。

2. 本地缓存数据的坐标污染
很多开发者为了优化启动速度,会使用 @ohos.data.relationalStore(关系型数据库)或 Preferences 缓存上一次的位置信息。如果缓存时存入的是转换后的 GCJ02 坐标,读取时又以为是底层硬件返回的 WGS84 再次进行二次转换,误差将被成倍放大。
建议:本地缓存永远只存原始设备下发的 WGS84 数据。只在将数据“递交”给 UI(MapComponent)的那一刻,才进行转换。

七、开发经验总结

排查此类偏移问题,建议按照以下顺序进行:

  1. 看数据源:明确你的经纬度是从 LocationKit 来的,还是后端来的,查明它最原始的生成环境是什么标准。
  2. 看区域范围:明确目标位置是在中国境内还是境外,决定了 Map Kit 组件当前渲染所要求的坐标系。
  3. 看业务逻辑闭环:检查是否有将 GCJ02 数据传给后端,后端又当作 WGS84 下发导致“二次污染”的情况。

如果你正在做包含打卡、轨迹回放、门店导航等高精度地图业务,可以重点排查一下项目中是否存在这种隐性的坐标系错位。理解了坐标系的映射关系,远比单纯调参去修正位置要彻底得多。

参考资料

  1. 《Map Kit 开发指南 - 概述与限制》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/map-overview-V5
  2. 《Location Kit 开发指南 - 获取设备位置信息》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/location-get-location-V5

如果觉得有帮助,别忘了点个赞+关注支持一下~
喜欢记得关注,别让好内容被埋没~

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐