npm package: @luqi_test/cordova-plugin-geolocation
Description: Cordova Geolocation Plugin
Author: Huawei geolocation, Inc. Ltd. and
Latest version: 5.0.0

# 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 项目根目录执行以下命令：


```bash
#安装最新版
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` 方法获取设备当前位置，适用于一次性定位场景（如用户签到）：



```js
// 调用获取当前位置方法
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` 方法持续监听设备位置变化，适用于轨迹跟踪、实时导航等场景：



```js
// 启动位置监听，返回监听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平台系统权限配置说明

使用该插件需要配置获取地理位置权限，否则无法定位

```json
"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：定位精度低，与实际位置偏差较大？

可能是未启用高精度定位，或设备定位模式设置不当：


1. 将 `options.enableHighAccuracy` 设为 `true`（启用 GPS 定位）；

2. 提示用户在设备设置中开启 “高精度定位模式”（结合 GPS、Wi-Fi、基站）；

3. 避免在室内、地下室等 GPS 信号弱的环境测试。


## 七、许可证

本插件采用 **Apache 许可证** 开源，您可以自由使用、修改和分发，无需支付任何费用，但需保留原作者版权信息。

完整许可证文本见项目根目录的 [LICENSE](LICENSE) 文件。


## 八、参考资料

* Android，ios插件：[www.npmjs.com](https://www.npmjs.com/package/cordova-plugin-geolocation)

* OHOS权限配置：[docs.openharmony.cn](https://docs.openharmony.cn/pages/v6.0/zh-cn/application-dev/security/AccessToken/declare-permissions.md)