cordova-plugin-baidumaplocation

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

• cordova-plugin-baidumaplocation
  • 简介
  • 核心特性
  • 支持平台
  • 下载安装
    • 1. 基础安装（指定 API Key）
    • 2. 安装指定版本
    • 3. 从 GitCode 安装（开发版本）
    • 4. 离线安装（本地包）
    • 5. 安装后验证
    • 6. 卸载插件
  • 约束与限制
    • 兼容性
  • 平台配置
    • OHOS 配置
    • 权限说明
  • 使用示例
    • 示例 1：单次定位（获取当前位置信息）
  • 使用说明
    • 1. 核心使用前提
    • 2. 核心 API 说明
    • 3. 定位结果参数说明
    • 4. OHOS 平台注意事项
    • 5. 调用方式选择
  • 常见问题
  • 目录结构
  • 贡献代码
  • 许可证
  • 参考资源
  • 官方资源

简介

一款基于百度地图定位 SDK 开发的 Cordova 定位插件，为混合式移动应用提供高精度、高稳定性的地理位置获取服务，支持 GPS、网络、基站等多源定位方式，适配 Android、iOS 和 OHOS 三平台，满足各类场景下的定位需求。

该插件在 OHOS 系统平台上，不直接应用百度地图，而是使用 OHOS 原生定位功能定位，然后转为百度地图的坐标，既贴合 OHOS 系统特性，又能满足开发者对百度地图坐标体系的使用需求，无需额外处理坐标转换逻辑。

核心特性

• 多源定位支持：支持 GPS、Wi-Fi、基站、蓝牙等多种定位方式，自动根据当前场景选择最优定位源，提升定位成功率与稳定性，适配 OHOS 原生定位能力。

• 高精度定位能力：GPS 定位精度可达米级，网络定位精度可达百米级，可根据业务需求选择合适的定位模式，满足不同场景下的精度要求。

• 灵活定位模式：支持单次定位和持续定位两种模式，持续定位可自定义定位间隔，适配实时定位、轨迹追踪等不同业务场景。

• 逆地理编码：支持将经纬度坐标转换为详细地址信息（省、市、区、街道、门牌号等），无需额外调用第三方接口，简化地址解析逻辑。

• 完善事件监听：提供定位成功、失败、权限变更等事件监听，便于开发者根据不同状态处理业务逻辑，提升应用交互体验。

• 智能权限管理：自动处理定位权限申请，支持权限状态查询和手动申请，适配 OHOS 系统权限管理规范，减少开发者权限处理成本。

• 低功耗优化：持续定位时支持低功耗模式，有效减少设备电量消耗，适配移动设备长时间运行场景，提升应用续航表现。

• OHOS 特性适配：OHOS 平台采用原生定位功能，自动转换为百度地图坐标，无需集成百度地图 SDK，降低集成复杂度，贴合 OHOS 系统开发规范。

支持平台

• Android 平台：适配主流 Android 版本，基于百度地图定位 SDK 实现，支持所有核心定位功能，兼容主流品牌机型。

• iOS 平台：适配 iOS 11.0 及以上版本，集成百度地图定位 SDK，支持高精度定位、逆地理编码等全部功能。

• OHOS 平台：5.0 及以上版本，使用 OHOS 原生定位功能实现定位，自动将定位结果转为百度地图坐标，支持核心定位与逆地理编码功能，需配置对应定位权限。

下载安装

通过 hcordova 命令化工具完成插件的安装、卸载，支持全平台或指定 OHOS 平台操作，安装过程自动完成基础配置，快速集成到 Cordova 项目。

1. 基础安装（指定 API Key）

通过 hcordova 命令安装最新稳定版，指定 OHOS 平台，无需额外配置 API Key（OHOS 平台采用原生定位，不依赖百度地图 SDK）：

# 安装 hcordova 命令化工具
npm install -g hcordova

# OHOS 系统安装（推荐）
hcordova plugin add cordova-plugin-baidumaplocation --platform ohos

2. 安装指定版本

如需兼容特定 Cordova 或 OHOS 版本，可指定版本号安装（仅 OHOS 平台）：

# 安装 1.0.0 版本（示例）
hcordova plugin add [email protected] --platform ohos

3. 从 GitCode 安装（开发版本）

如需测试最新功能或问题修复，可从 GitCode 仓库安装开发分支（仅 OHOS 平台）：

# 仅支持 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-baidumaplocation.git --platform ohos

# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-baidumaplocation.git@develop --platform ohos

4. 离线安装（本地包）

适用于无网络环境，先下载插件包到本地，再执行离线安装：

# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-baidumaplocation）
# 执行离线安装
hcordova plugin add ../Downloads/cordova-plugin-baidumaplocation  --platform ohos

5. 安装后验证

安装完成后，可通过以下命令验证插件是否成功添加到项目中：

# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list

6. 卸载插件

如需移除插件，进入项目根目录，执行以下命令，支持全平台卸载或仅卸载 OHOS 平台插件：

# 全平台卸载
hcordova plugin remove cordova-plugin-baidumaplocation

# 指定 OHOS 平台卸载
hcordova plugin remove cordova-plugin-baidumaplocation --platform ohos

约束与限制

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |

在以下版本中已测试通过：

| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |

平台配置

插件安装后需根据目标平台进行必要配置，确保定位功能正常运行，以下重点说明 OHOS 平台的配置要求（Android、iOS 平台配置参考官方指南）。

OHOS 配置

使用该插件需要配置获取地理位置相关权限，否则无法正常实现定位功能，需在应用配置文件中添加以下权限配置：

"requestPermissions": [
    {
    "name" : "ohos.permission.LOCATION",
    "reason": "$string:locationInfo", 
    "usedScene": {
        "abilities": [
        "EntryAbility"
        ],
        "when": "always"
    }
    },
    {
    "name" : "ohos.permission.APPROXIMATELY_LOCATION",
    "reason": "$string:locationInfo",
    "usedScene": {
        "abilities": [
        "EntryAbility"
        ],
        "when": "always"
    }
    },
    {
    "name" : "ohos.permission.LOCATION_IN_BACKGROUND",
    "reason": "$string:locationInfo",
    "usedScene": {
        "abilities": [
        "EntryAbility"
        ],
        "when": "always"
    }
    }
]

权限说明

• ohos.permission.LOCATION：获取精确地理位置权限，用于 GPS 等高精度定位方式。

• ohos.permission.APPROXIMATELY_LOCATION：获取粗略地理位置权限，用于网络、基站等定位方式。

• ohos.permission.LOCATION_IN_BACKGROUND：后台定位权限，用于应用在后台运行时仍能进行持续定位。

备注：权限配置中的 $string:locationInfo 需在字符串资源文件中定义，说明申请权限的原因（如“为了为您提供精准的地理位置服务”），符合 OHOS 权限申请规范。

使用示例

以下示例均适配 OHOS 平台，涵盖单次定位、结果处理等核心场景，结合 OHOS 平台特性（原生定位转百度坐标），可直接复制到项目中使用（需确保 Cordova 环境就绪且权限配置完成）。

示例 1：单次定位（获取当前位置信息）

调用 getCurrentPosition 方法实现单次定位，获取经纬度、地址等详细信息，适配 OHOS 原生定位转百度坐标的特性：

// 等待 Cordova 环境完全加载（必须在 deviceready 事件后调用插件）
document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
  // 检查插件是否成功加载
  if (window.cordova && window.cordova.plugins && window.cordova.plugins.baidumaplocation) {
    const baidumap_location = cordova.plugins.baidumaplocation;
    
    // 单次定位，获取当前位置信息
    baidumap_location.getCurrentPosition(
      function (result) {
        // 定位成功，result 为定位结果对象（已转为百度地图坐标）
        const locationInfo = JSON.stringify(result, null, 2);
        document.getElementById("localInfo").innerHTML = locationInfo;
        console.log("定位成功：", locationInfo);
        
        // 可单独获取具体字段
        console.log("纬度：", result.latitude);
        console.log("经度：", result.longitude);
        console.log("详细地址：", result.addr);
        console.log("定位方式：", result.locTypeDescription);
      },
      function (error) {
        // 定位失败，处理错误信息
        console.error("定位失败：", error.message);
        document.getElementById("localInfo").innerHTML = `定位失败：${error.message}`;
      }
    );
  } else {
    console.error("插件未加载，请检查安装是否正确");
    document.getElementById("localInfo").innerHTML = "插件未加载，请检查安装是否正确";
  }
}

使用说明

本插件使用流程简洁，核心需遵循“环境就绪→权限配置→调用 API→处理结果”的逻辑，重点适配 OHOS 平台使用场景，结合使用示例理解更高效。

1. 核心使用前提

• 插件所有 API 均需在 Cordova 环境完全就绪后调用，即必须在 deviceready 事件触发后执行，否则会出现“插件未加载”“接口未定义”等错误。

• OHOS 平台必须配置定位相关权限（参考平台配置章节），否则定位会失败，且需在权限申请理由中明确说明使用场景，符合 OHOS 权限规范。

• OHOS 平台无需集成百度地图 SDK，插件通过原生定位获取位置后，自动转为百度地图坐标，开发者可直接使用，无需额外处理坐标转换。

2. 核心 API 说明

插件通过全局对象 cordova.plugins.baidumaplocation 暴露所有接口，所有方法均为异步执行，通过成功回调和错误回调处理结果，适配 OHOS 平台的核心 API 如下：

| API 方法 | 功能描述 | 说明（OHOS 平台） | |---|---|---| | getCurrentPosition(success, error) | 单次定位 | success：定位成功回调，参数为定位结果对象（含经纬度、地址等，已转为百度坐标）；error：定位失败回调，参数为错误对象。 |

3. 定位结果参数说明

getCurrentPosition 方法成功回调的 result 对象，包含以下核心参数（OHOS 平台适配，已转为百度地图坐标）：

| 参数名 | 类型 | 说明 | |---|---|---| | time | number | 定位时间戳（毫秒级） | | locType | number | 定位类型：1（GNSS）、2（NETWORK）、3（INDOOR）、4（RTK） | | locTypeDescription | string | 定位类型描述：GNSS、NETWORK、INDOOR、RTK | | latitude | number | 纬度（百度地图坐标） | | longitude | number | 经度（百度地图坐标） | | altitude | number | 海拔高度（单位：米） | | radius | number | 定位精度（单位：米） | | country | string | 国家名称 | | province | string | 省份名称 | | city | string | 城市名称 | | district | string | 区县名称 | | street | string | 街道名称 | | addr | string | 详细地址信息（含门牌号等） | | 不确定参数 | — | userIndoorState（室内状态）、direction（方向）、locationDescribe（位置描述）等，根据定位场景返回。 |

4. OHOS 平台注意事项

• OHOS 平台不直接应用百度地图 SDK，而是通过原生定位功能获取位置，再自动转为百度地图坐标，开发者无需额外集成百度地图相关依赖，降低集成复杂度。

• 必须严格配置定位相关权限（ohos.permission.LOCATION、ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.LOCATION_IN_BACKGROUND），否则定位会失败，且权限申请理由需明确合理。

• 定位结果中的经纬度已自动转为百度地图坐标，可直接用于百度地图相关业务（如地图展示、路径规划等），无需手动转换。

• 在室内、地下等 GPS 信号较弱的场景下，插件会自动切换为网络或基站定位，确保定位成功率，定位精度会根据定位源自动调整。

• 持续定位模式下，建议开启低功耗模式，减少设备电量消耗，可通过插件相关配置（参考官方文档）实现。

• 若定位失败，可检查以下几点：权限是否配置并授予、设备定位功能是否开启、网络/GPS 信号是否良好、插件安装是否正确。

5. 调用方式选择

• 单次定位：适合仅需获取当前位置的场景（如用户打卡、地址填写），调用 getCurrentPosition 方法即可（对应示例 1）。

• 权限处理：定位权限已下放到插件，定位时会自动弹窗取得用户授权

• 持续定位：适合轨迹追踪、实时定位等场景，需参考官方文档配置定位间隔、低功耗模式等参数，调用对应接口实现。

常见问题

• 问题 1：OHOS 平台调用定位 API 提示“插件未加载”？ 解决：检查插件是否安装成功（通过 hcordova plugin list 确认），确保在 deviceready 事件后调用插件，重新安装插件并重启项目。

• 问题 2：定位失败，提示“权限不足”？ 解决：检查应用配置文件中的定位权限是否配置完整，确保用户已授予定位权限，若未授予，可通过 requestPermission 方法手动申请。

• 问题 3：定位结果经纬度不是百度地图坐标？ 解决：OHOS 平台插件会自动将原生定位结果转为百度地图坐标，无需手动处理，若仍有异常，检查插件版本是否兼容，重新安装插件重试。

• 问题 4：室内或地下场景定位失败？ 解决：此类场景 GPS 信号较弱，插件会自动切换为网络/基站定位，确保设备网络通畅，若仍失败，可提示用户移动到信号较好的区域。

• 问题 5：持续定位时设备电量消耗过快？ 解决：开启低功耗模式，合理设置定位间隔（避免过短），减少不必要的定位请求，降低电量消耗。

目录结构

cordova-plugin-baidumaplocation/
├── src/                          # 源代码目录
│   └── main/                     # 主要源代码
│       └── cpp/                  # C++ 原生代码
│           └── BaiduGeolocation/ # 百度地图定位模块
│               ├── BaiduMapLocation.cpp  # 百度地图定位功能的 C++ 实现
│               ├── BaiduMapLocation.h    # 百度地图定位功能的头文件
│               ├── translateWgs.cpp      # WGS 坐标转换的 C++ 实现
│               └── translateWgs.h        # WGS 坐标转换的头文件
├── www/                          # Web 资源目录
│   └──baidumap_location.js   # JavaScript 百度地图定位接口（Cordova 桥接层）
├── .gitignore                    # Git 忽略文件配置
├── LICENSE                       # 项目开源许可证
├── OAT.xml                       # OpenHarmony 审核配置文件
├── package.json                  # Node.js 包配置
├── plugin.xml                    # Cordova 插件描述文件（核心配置）
└── README.md                     # 项目说明文档

贡献代码

使用过程中发现任何问题都可以提 Issue，当然也非常欢迎发 PR 共建。

许可证

本插件（cordova-plugin-baidumaplocation）基于 Apache License 2.0 开源，详见 LICENSE 文件。

参考资源

• OHOS 插件仓库：https://gitcode.com/CPF-Cordova/cordova-plugin-baidumaplocation

• Android、iOS 插件说明：https://www.npmjs.com/package/cordova-plugin-baidumaplocation

• Cordova 官方文档：Cordova Documentation

• OHOS 开发文档：OpenHarmony 官方文档

• 百度地图坐标体系说明：百度地图坐标说明

官方资源

• Android 和 iOS：cordova-plugin-baidumaplocation 官方指南

• GitCode 仓库：CPF-Cordova/cordova-plugin-baidumaplocation