{"_id":"@cordova-ohos/cordova-plugin-geolocation","_rev":"5-729401df42b3bee1c04ec0e47041a77a","name":"@cordova-ohos/cordova-plugin-geolocation","dist-tags":{"latest":"5.0.1"},"versions":{"5.0.0":{"name":"@cordova-ohos/cordova-plugin-geolocation","version":"5.0.0","keywords":["cordova","geolocation","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei geolocation, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-geolocation@5.0.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-geolocation/issues"},"dist":{"shasum":"9fd2f24894ea2bca8138119c7b7f32896d1e81d3","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-geolocation/-/cordova-plugin-geolocation-5.0.0.tgz","fileCount":10,"integrity":"sha512-kk6z+g3AxVWXnNtzngfg7qVt7Phu4Wqv1Rj/X8CfREeR3LkLenIqm7DPVS+OWuEmdMTl7vJ4ZJ2DbU0HpVuHZA==","signatures":[{"sig":"MEUCIAscmvP2Q8OT+NFeJa/PWYFAwQ3yEdkhx00D+uWyRTJRAiEA8r70WtmpEXi9TKKD6/ulUOLW0enAnyjmWuHeTMzcSPU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45080},"cordova":{"id":"cordova-plugin-geolocation","platforms":["ohos"]},"engines":{"cordovaDependencies":{"5.0.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"66ff518b49a38dae3afad6b46bc5ea3437bd763d","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-geolocation","type":"git"},"_npmVersion":"10.5.1","description":"Cordova Geolocation Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-geolocation_5.0.0_1773827190831_0.5707983684518323","host":"s3://npm-registry-packages-npm-production"}},"5.0.1":{"name":"@cordova-ohos/cordova-plugin-geolocation","version":"5.0.1","description":"Cordova Geolocation Plugin","cordova":{"id":"cordova-plugin-geolocation","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-geolocation"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-geolocation/issues"},"keywords":["cordova","geolocation","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"5.0.1":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei geolocation, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-geolocation@5.0.1","gitHead":"001479fec31b84f570eac4a0f8986609d8de1cde","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-9+4mT9MSniVlPIZ2qcNz+hVb+KcKOgf92hnkQlRTJtvx0Z8r1PGbVN4D02/fIIAgxOs/g1N55CMPdp4sVhgcDg==","shasum":"d05b9a06c0ed4b4dd52a23c47cb2ddd000d0c784","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-geolocation/-/cordova-plugin-geolocation-5.0.1.tgz","fileCount":11,"unpackedSize":58239,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA+NpsG5dqWeLTqT/hYKM9xKWaxJHh2/0qtl+PD2ZX/rAiALaZo4raNuxS/8jrLiCSxIoe65h9G6opc6HbCSAvV0QQ=="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-geolocation_5.0.1_1785140111660_0.056199483185821686"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-18T09:46:30.705Z","modified":"2026-07-27T08:15:12.048Z","5.0.0":"2026-03-18T09:46:30.974Z","5.0.1":"2026-07-27T08:15:11.785Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-geolocation/issues"},"author":{"name":"Huawei geolocation, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","geolocation","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-geolocation"},"description":"Cordova Geolocation Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-plugin-geolocation</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-geolocation@5.0.0](https://www.npmjs.com/package/cordova-plugin-geolocation/v/5.0.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-geolocation](#cordova-plugin-geolocation)\r\n  - [简介](#简介)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [从 npm 安装（推荐）](#从-npm-安装推荐)\r\n    - [指定平台安装 ohos](#指定平台安装-ohos)\r\n    - [从 GitCode 仓库安装](#从-gitcode-仓库安装)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载](#卸载)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n    - [权限要求](#权限要求)\r\n  - [使用示例](#使用示例)\r\n    - [获取当前位置](#获取当前位置)\r\n    - [监听位置变化](#监听位置变化)\r\n  - [使用说明](#使用说明)\r\n    - [配置参数（options）](#配置参数options)\r\n  - [新增特性](#新增特性)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n## 简介\r\n\r\n`cordova-plugin-geolocation` 是 Harmony Cordova 生态系统中一款核心插件，用于在 Cordova 应用中访问设备的 GPS、网络定位等功能，实现跨平台（iOS/Android/OHOS）的地理位置信息获取与监听，满足各类位置相关应用场景需求，本文档只说明在 OHOS 系统中的应用。该插件的定位是采用 W3C 定位的，实现方式：插件主要是弹窗获取用户地理位置授权后，有 webview 的定位功能实现定位，兼容 W3C。\r\n\r\n- 快速获取设备当前精确地理位置（纬度、经度、海拔、精度等）\r\n\r\n- 实时监听设备位置变化，支持动态更新位置信息\r\n\r\n- 可配置定位精度、超时时间、缓存策略，适配不同场景\r\n\r\n- 提供完善的错误处理机制，明确错误类型与解决方案\r\n\r\n- 严格遵循 Cordova 插件开发规范，兼容主流 Cordova 版本\r\n\r\n## 支持平台\r\n\r\n- **Android**：API 19 及以上（Android 4.4+）\r\n\r\n- **iOS**：10.0 及以上\r\n\r\n- **OHOS**：5.0+\r\n\r\n## 下载安装\r\n\r\n通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取。\r\n\r\n### 从 npm 安装（推荐）\r\n\r\n```bash\r\n# 使用 hcordova CLI 安装\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n# 全平台安装插件\r\nhcordova plugin add cordova-plugin-geolocation\r\n```\r\n\r\n### 指定平台安装 ohos\r\n\r\n仅为 OHOS 平台安装插件：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\nhcordova plugin add cordova-plugin-geolocation --platform ohos\r\n\r\n# 指定版本安装\r\nhcordova plugin add cordova-plugin-geolocation@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 仓库安装\r\n\r\n仅为 OHOS 平台安装插件：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\n# 默认分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-geolocation.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-geolocation.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-geolocation）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-geolocation --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n### 卸载\r\n\r\n```bash\r\n# Cordova CLI 全平台卸载\r\nhcordova plugin remove cordova-plugin-geolocation \r\n# 指定平台卸载\r\nhcordova plugin remove cordova-plugin-geolocation --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n\r\n依赖插件：无强制依赖，若需扩展定位相关功能，可根据实际需求搭配对应插件使用。\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n### 权限要求\r\n\r\n使用该插件需要配置获取地理位置权限，否则无法定位\r\n\r\n```json\r\n\"requestPermissions\": [\r\n    {\r\n    \"name\" : \"ohos.permission.LOCATION\",\r\n    \"reason\": \"$string:locationInfo\", \r\n    \"usedScene\": {\r\n        \"abilities\": [\r\n        \"EntryAbility\"\r\n        ],\r\n        \"when\": \"always\"\r\n    }\r\n    },\r\n    {\r\n    \"name\" : \"ohos.permission.APPROXIMATELY_LOCATION\",\r\n    \"reason\": \"$string:locationInfo\",\r\n    \"usedScene\": {\r\n        \"abilities\": [\r\n        \"EntryAbility\"\r\n        ],\r\n        \"when\": \"always\"\r\n    }\r\n    },\r\n    {\r\n    \"name\" : \"ohos.permission.LOCATION_IN_BACKGROUND\",\r\n    \"reason\": \"$string:locationInfo\",\r\n    \"usedScene\": {\r\n        \"abilities\": [\r\n        \"EntryAbility\"\r\n        ],\r\n        \"when\": \"always\"\r\n    }\r\n    }\r\n]\r\n```\r\n\r\n## 使用示例\r\n\r\n### 获取当前位置\r\n\r\n通过 `getCurrentPosition` 方法获取设备当前位置，适用于一次性定位场景（如用户签到）：\r\n\r\n```js\r\n// 调用获取当前位置方法\r\nnavigator.geolocation.getCurrentPosition(\r\n // 成功回调：获取位置信息\r\n function (position) {\r\n   console.log(\"定位成功，位置信息如下：\");\r\n   console.log(\"纬度：\", position.coords.latitude); // 纬度（十进制）\r\n   console.log(\"经度：\", position.coords.longitude); // 经度（十进制）\r\n   console.log(\"定位精度：\", position.coords.accuracy + \" 米\"); // 水平精度\r\n   console.log(\"海拔：\", position.coords.altitude); // 海拔（部分设备支持）\r\n   console.log(\"海拔精度：\", position.coords.altitudeAccuracy ); // 海拔精度\r\n   console.log(\"定位时间：\", new Date(position.timestamp).toLocaleString()); // 定位时间\r\n },\r\n // 失败回调：处理定位错误\r\n function (error) {\r\n   console.error(\"定位失败：\");\r\n   switch (error.code) {\r\n     case error.PERMISSION_DENIED:\r\n       console.error(\"错误码 1：用户拒绝授予定位权限\");\r\n       break;\r\n     case error.POSITION_UNAVAILABLE:\r\n       console.error(\"错误码 2：位置信息不可用（如设备无 GPS 信号）\");\r\n       break;\r\n     case error.TIMEOUT:\r\n       console.error(\"错误码 3：定位请求超时\");\r\n       break;\r\n     default:\r\n       console.error(\"错误码 4：未知错误\");\r\n       break;\r\n   }\r\n },\r\n // 配置选项：自定义定位参数\r\n {\r\n   enableHighAccuracy: true, // 是否启用高精度定位（GPS），true = 高精度（耗电），false = 低精度（网络定位）\r\n   timeout: 15000, // 定位超时时间（毫秒），超过时间未获取位置则触发失败回调\r\n   maximumAge: 0 // 位置缓存有效期（毫秒），0 = 不使用缓存，30000 = 允许使用 30 秒内的缓存位置\r\n }\r\n);\r\n```\r\n\r\n### 监听位置变化\r\n\r\n通过 `watchPosition` 方法持续监听设备位置变化，适用于轨迹跟踪、实时导航等场景：\r\n\r\n```js\r\n// 启动位置监听，返回监听 ID（用于后续停止监听）\r\nvar watchId = navigator.geolocation.watchPosition(\r\n // 成功回调：位置更新时触发\r\n function (position) {\r\n   console.log(\"位置更新：\");\r\n   console.log(\"当前纬度：\", position.coords.latitude);\r\n   console.log(\"当前经度：\", position.coords.longitude);\r\n },\r\n // 失败回调：监听错误时触发\r\n function (error) {\r\n   console.error(\"位置监听失败：\", error.message);\r\n },\r\n // 配置选项\r\n {\r\n   enableHighAccuracy: false, // 低精度模式（适合后台持续监听，降低耗电）\r\n   timeout: 30000, // 超时时间 30 秒\r\n   maximumAge: 60000 // 允许使用 1 分钟内的缓存位置，减少重复请求\r\n }\r\n);\r\n// 停止位置监听（如页面关闭、用户停止跟踪时）\r\nfunction stopLocationWatch() {\r\n if (watchId) {\r\n   navigator.geolocation.clearWatch(watchId);\r\n   watchId = null;\r\n   console.log(\"位置监听已停止\");\r\n }\r\n}\r\n```\r\n\r\n## 使用说明\r\n\r\n### 配置参数（options）\r\n\r\n| 配置项 | 类型 | 默认值 | 说明 |\r\n|---|---|---|---|\r\n| enableHighAccuracy | Boolean | false | 是否启用高精度定位（true = GPS，false = 网络定位/基站定位） |\r\n| timeout | Number | Infinity | 定位超时时间（毫秒），超过时间未获取位置则触发 errorCallback |\r\n| maximumAge | Number | 0 | 位置缓存有效期（毫秒），0 = 不使用缓存，大于 0 = 允许使用指定时间内的缓存 |\r\n\r\n## 新增特性\r\n\r\n1. 适配 OHOS 5.0+ 系统，严格遵循 OpenHarmony 开发规范；\r\n   \r\n2. 完善权限配置说明，明确 OHOS 平台所需定位权限及配置方式；\r\n   \r\n3. 补充详细错误处理方案，提供常见问题解决方案，提升开发体验；\r\n   \r\n4. 兼容 W3C 定位标准，通过 webview 实现定位，保障跨平台一致性。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-geolocation/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       ├── cpp/                  # C++ 原生代码\r\n│       │   └── BaiduGeolocation/ # 百度定位模块\r\n│       │       ├── Geolocation.cpp  # 定位功能的 C++ 实现\r\n│       │       └── Geolocation.h    # 定位功能的头文件\r\n│       └── ets/                  # ArkTS 代码（OpenHarmony API）\r\n│           └── components/       # 组件目录\r\n│               └── LocationAction/  # 定位动作组件\r\n│                   └── LocationAction.ets  # 定位功能的 ArkTS 实现\r\n├── www/                          # Web 资源目录\r\n│   ├── harmony/                  # 相关资源\r\n│   │   └──  geolocation.js       # JavaScript 定位接口（Cordova 桥接层）\r\n│   └── PositionError.js          # 定位错误码定义\r\n├── .gitignore                    # Git 忽略文件配置\r\n├── LICENSE                       # 项目开源许可证\r\n├── OAT.xml                       # OpenHarmony 审核配置文件\r\n├── package.json                  # Node.js 包配置\r\n├── plugin.xml                    # Cordova 插件描述文件（核心配置）\r\n└── README.md                     # 项目说明文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-geolocation/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-geolocation/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-plugin-geolocation 官方指南](https://www.npmjs.com/package/cordova-plugin-geolocation)\r\n\r\n- GitCode 仓库：[CPF-Cordova/cordova-plugin-geolocation](https://gitcode.com/CPF-Cordova/cordova-plugin-geolocation)\r\n","readmeFilename":"README.md"}