@cordova-ohos/cordova-plugin-geolocation

v5.0.0

Published

3 days ago

Cordova Geolocation Plugin

Downloads

152

0High
0Medium
0Low

cordova geolocation ecosystem:cordova cordova-openharmony

cordova-plugin-geolocation

Cordova 地理位置插件，用于在 Cordova 应用中访问设备的 GPS、网络定位等功能，实现跨平台（iOS/Android/OHOS）的地理位置信息获取与监听，满足各类位置相关应用场景需求，本文档只说明在OHOS系统中的应用。

该插件的定位是采用W3C定位的，实现方式：插件主要是弹窗获取用户地理位置授权后，有webview的定位功能实现定位，兼容W3C。

一、插件概述

1.1 核心功能

快速获取设备当前精确地理位置（纬度、经度、海拔、精度等）
实时监听设备位置变化，支持动态更新位置信息
可配置定位精度、超时时间、缓存策略，适配不同场景
提供完善的错误处理机制，明确错误类型与解决方案
严格遵循 Cordova 插件开发规范，兼容主流 Cordova 版本

1.2 适用场景

地图类应用（如导航、周边服务）
基于位置的信息展示（如本地天气、区域资讯）
运动类应用（如轨迹记录、距离计算）
考勤打卡、位置签到等场景

二、安装指南

2.1 前提条件

已安装 Node.js（建议 v14+）与 npm（建议 v6+）
已安装 hcordova (npm install -g hcordova)
已创建 Cordova 项目（hcordova create <项目名>）
已添加目标平台（hcordova platform add ohos）

2.2 安装方式

在 Cordova 项目根目录执行以下命令：

#安装最新版
hcordova plugin add cordova-plugin-geolocation

#指定OHOS安装
hcordova plugin add cordova-plugin-geolocation --platform ohos

#指定gitcode安装
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-geolocation.git --platform ohos

三、快速使用示例

3.1 获取当前位置

通过 getCurrentPosition 方法获取设备当前位置，适用于一次性定位场景（如用户签到）：

// 调用获取当前位置方法
navigator.geolocation.getCurrentPosition(
 // 成功回调：获取位置信息
 function (position) {
   console.log("定位成功，位置信息如下：");
   console.log("纬度：", position.coords.latitude); // 纬度（十进制）
   console.log("经度：", position.coords.longitude); // 经度（十进制）
   console.log("定位精度：", position.coords.accuracy + " 米"); // 水平精度
   console.log("海拔：", position.coords.altitude); // 海拔（部分设备支持）
   console.log("海拔精度：", position.coords.altitudeAccuracy ); // 海拔精度
   console.log("定位时间：", new Date(position.timestamp).toLocaleString()); // 定位时间
 },

 // 失败回调：处理定位错误
 function (error) {
   console.error("定位失败：");
   switch (error.code) {
     case error.PERMISSION_DENIED:
       console.error("错误码 1：用户拒绝授予定位权限");
       break;
     case error.POSITION_UNAVAILABLE:
       console.error("错误码 2：位置信息不可用（如设备无GPS信号）");
       break;
     case error.TIMEOUT:
       console.error("错误码 3：定位请求超时");
       break;
     default:
       console.error("错误码 4：未知错误");
       break;
   }

 },

 // 配置选项：自定义定位参数

 {
   enableHighAccuracy: true, // 是否启用高精度定位（GPS），true=高精度（耗电），false=低精度（网络定位）
   timeout: 15000, // 定位超时时间（毫秒），超过时间未获取位置则触发失败回调
   maximumAge: 0 // 位置缓存有效期（毫秒），0=不使用缓存，30000=允许使用30秒内的缓存位置
 }

);

3.2 监听位置变化

通过 watchPosition 方法持续监听设备位置变化，适用于轨迹跟踪、实时导航等场景：

// 启动位置监听，返回监听ID（用于后续停止监听）
var watchId = navigator.geolocation.watchPosition(
 // 成功回调：位置更新时触发
 function (position) {
   console.log("位置更新：");
   console.log("当前纬度：", position.coords.latitude);
   console.log("当前经度：", position.coords.longitude);
 },

 // 失败回调：监听错误时触发
 function (error) {
   console.error("位置监听失败：", error.message);

 },

 // 配置选项
 {
   enableHighAccuracy: false, // 低精度模式（适合后台持续监听，降低耗电）
   timeout: 30000, // 超时时间30秒
   maximumAge: 60000 // 允许使用1分钟内的缓存位置，减少重复请求
 }

);

// 停止位置监听（如页面关闭、用户停止跟踪时）
function stopLocationWatch() {
 if (watchId) {
   navigator.geolocation.clearWatch(watchId);
   watchId = null;
   console.log("位置监听已停止");
 }

}

四、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"
    }
    }
]

五、API 详细参考

5.1 核心方法

1. navigator.geolocation.getCurrentPosition()

功能：获取设备当前位置（一次性定位）
参数：

| 参数名 | 类型 | 说明 | | --------------- | -------- | ------------------------------------- | | successCallback | Function | 定位成功回调，参数为 Position 对象（包含位置信息） | | errorCallback | Function | 定位失败回调，参数为 PositionError 对象（包含错误信息） | | options | Object | 可选配置项，见下表 |

options 配置项：

| 配置项 | 类型 | 默认值 | 说明 | | ------------------ | ------- | -------- | ----------------------------------------- | | enableHighAccuracy | Boolean | false | 是否启用高精度定位（true=GPS，false = 网络定位 / 基站定位） | | timeout | Number | Infinity | 定位超时时间（毫秒），超过时间未获取位置则触发 errorCallback | | maximumAge | Number | 0 | 位置缓存有效期（毫秒），0 = 不使用缓存，大于 0 = 允许使用指定时间内的缓存 |

2. navigator.geolocation.watchPosition()

功能：持续监听设备位置变化，位置更新时触发回调
参数：与 getCurrentPosition 完全一致
返回值：Number 类型的 watchId（监听 ID），用于后续停止监听

3. navigator.geolocation.clearWatch(watchId)

功能：停止指定的位置监听
参数：

| 参数名 | 类型 | 说明 | | ------- | ------ | -------------------------- | | watchId | Number | watchPosition 方法返回的监听 ID |

5.2 数据对象

1. Position 对象（定位成功返回）

| 属性名 | 类型 | 说明 | | --------- | ------ | ----------------------------------------- | | coords | Object | 位置坐标信息，包含 latitude、longitude 等属性（见下表） | | timestamp | Number | 定位时间戳（毫秒，从 1970-01-01 00:00:00 UTC 开始计算） |

2. Coords 对象（Position.coords）

| 属性名 | 类型 | 说明 | | ---------------- | ------ | ------------------------------- | | latitude | Number | 纬度（十进制，范围：-90 ~ 90） | | longitude | Number | 经度（十进制，范围：-180 ~ 180） | | accuracy | Number | 水平定位精度（米，值越小精度越高） | | altitude | Number | 海拔高度（米，null 表示不支持） | | altitudeAccuracy | Number | 海拔精度（米，null 表示不支持） | | heading | Number | 设备朝向（度，0 = 正北，顺时针递增，null 表示不支持） | | speed | Number | 设备移动速度（米 / 秒，null 表示不支持或静止） |

3. PositionError 对象（定位失败返回）

| 属性名 | 类型 | 说明 | | ------- | ------ | --------------------------------------- | | code | Number | 错误码（1 = 权限拒绝，2 = 位置不可用，3 = 超时，4 = 未知错误） | | message | String | 错误描述信息（用于调试，不建议直接展示给用户） |

六、错误处理与常见问题

6.1 错误码说明

| 错误码 | 常量名 | 原因分析 | 解决方案 | | --- | --------------------- | ----------------------------------- | ----------------------------------------------------------- | | 1 | PERMISSION_DENIED | 用户拒绝授予定位权限，或系统禁用了应用的定位权限 | 1. 引导用户在系统设置中开启定位权限；2. 优化权限申请文案，说明定位用途 | | 2 | POSITION_UNAVAILABLE | 无法获取位置信息（如设备无 GPS 信号、网络定位失败、处于飞行模式） | 1. 提示用户检查设备 GPS / 网络状态；2. 切换定位模式（高精度 / 低精度） | | 3 | TIMEOUT | 定位请求超时（如 GPS 信号弱，长时间无法获取位置） | 1. 延长 timeout 配置时间；2. 降低定位精度（enableHighAccuracy: false） | | 4 | UNKNOWN_ERROR | 未知错误（如插件未正确安装、平台配置错误） | 1. 重新安装插件；2. 检查 config.xml 中权限配置是否正确；3. 查看日志调试 |

6.2 常见问题

Q1：定位精度低，与实际位置偏差较大？

可能是未启用高精度定位，或设备定位模式设置不当：

将 options.enableHighAccuracy 设为 true（启用 GPS 定位）；
提示用户在设备设置中开启 “高精度定位模式”（结合 GPS、Wi-Fi、基站）；
避免在室内、地下室等 GPS 信号弱的环境测试。

七、许可证

本插件采用 Apache 许可证 开源，您可以自由使用、修改和分发，无需支付任何费用，但需保留原作者版权信息。

完整许可证文本见项目根目录的 LICENSE 文件。

八、参考资料

Android，ios插件：www.npmjs.com
OHOS权限配置：docs.openharmony.cn