{"_id":"@capacitor-ohos/geolocation","_rev":"2-77524b59d1217412234b4b79b833bdcc","name":"@capacitor-ohos/geolocation","dist-tags":{"latest":"8.0.2"},"versions":{"8.0.1":{"name":"@capacitor-ohos/geolocation","version":"8.0.1","keywords":["capacitor","plugin","native"],"author":{"url":"Group","name":"Huawei Device Co., Ltd and iSoftStone Information Technology"},"license":"MIT","_id":"@capacitor-ohos/geolocation@8.0.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-geolocation/issues"},"dist":{"shasum":"333fa4f1b11a61663f5c334a7cde67a22b0c962e","tarball":"https://registry.npmjs.org/@capacitor-ohos/geolocation/-/geolocation-8.0.1.tgz","fileCount":10,"integrity":"sha512-12+WQICgtxaABcsujZboWanPLkzq6teQWTUyUQV44dJRKgMZTqayCWmB8BMElpfskPl6picct/43WXYE8m13Yw==","signatures":[{"sig":"MEUCIQCKUDCmyCWx5F4Ug2nxZK8cL8qRxIVNvAbb1TW6U6lWlwIgD5sc9h+ho8TtfXBMxmrLNaG1LqHGcnSHnEX+xr7tc1s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47745},"gitHead":"f5cfe3db093bc5141dc5616c9ba99f58836875c6","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"capacitor":{"id":"@capacitor/geolocation","platforms":["openharmony"]},"repository":{"url":"gitcode:CPF-Ionic/capacitor-geolocation","type":"git"},"_npmVersion":"10.5.1","description":"The Geolocation API provides simple methods for getting and tracking the current position of the device using GPS, along with altitude, heading, and speed information if available.","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/geolocation_8.0.1_1777541471408_0.0656121498404656","host":"s3://npm-registry-packages-npm-production"}},"8.0.2":{"name":"@capacitor-ohos/geolocation","version":"8.0.2","description":"The Geolocation API provides simple methods for getting and tracking the current position of the device using GPS, along with altitude, heading, and speed information if available.","capacitor":{"id":"@capacitor/geolocation","platforms":["openharmony"]},"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-geolocation"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-geolocation/issues"},"keywords":["capacitor","plugin","native"],"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","_id":"@capacitor-ohos/geolocation@8.0.2","gitHead":"ae9a5cb631eb9b4841f781a5f45e5a1f25bc173a","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-oQO50yBiCP4vzxRAIKYtruEf+FfJr6rUBzwzrwqJvmbx+NOCfPL99KAax/hN04UHk1yk0DjpBQpYFV8mzUh/wQ==","shasum":"af562010b8f693f6c9d783012c63671feef1e63b","tarball":"https://registry.npmjs.org/@capacitor-ohos/geolocation/-/geolocation-8.0.2.tgz","fileCount":10,"unpackedSize":47963,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDNdTcv13kkcgOUSANDXJ6bcbb/+JPhspWprI6lJKLljQIhALDYsMWTqnR+PTxO11DiOSBhyDngaaeTXbqho0vYfp7q"}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/geolocation_8.0.2_1784791688672_0.4484036355085832"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T09:31:11.345Z","modified":"2026-07-23T07:28:09.090Z","8.0.1":"2026-04-30T09:31:11.563Z","8.0.2":"2026-07-23T07:28:08.899Z"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-geolocation/issues"},"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","keywords":["capacitor","plugin","native"],"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-geolocation"},"description":"The Geolocation API provides simple methods for getting and tracking the current position of the device using GPS, along with altitude, heading, and speed information if available.","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"readme":"# <center>@capacitor/geolocation</center>\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本项目基于 [@capacitor/geolocation@8.0.0](https://www.npmjs.com/package/@capacitor/geolocation/v/8.0.0) 开发。\r\n\r\n## 简介\r\n\r\n@capacitor/geolocation是capacitor生态系统中的核心插件，利用GPS获取和追踪设备当前位置，为跨平台应用开发提供设备差异化适配能力，兼容capacitor的Android、iOS等主流移动平台及浏览器环境，本文档只说明在OpenHarmony系统中的使用。\r\n\r\nAPI提供了简单的方法，利用GPS获取和追踪设备当前位置，并附带高度、航向和速度信息（如有），满足各类地理定位场景需求。\r\n\r\n## 支持平台\r\n\r\n- **OpenHarmony**：5.0+\r\n\r\n## 下载安装\r\n\r\n通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。\r\n\r\n### 命令行安装（推荐）\r\n\r\n安装hionic CLI：\r\n\r\n```bash\r\nnpm install -g hionic\r\n```\r\n\r\n以下两种方式中**任选其一**即可，无需重复操作：\r\n\r\nnpm安装：\r\n\r\n```bash\r\n# 安装插件\r\nnpm install @capacitor/geolocation\r\n\r\n# 同步插件\r\nhionic sync openharmony\r\n```\r\n\r\nhionic CLI安装：\r\n\r\n```bash\r\nhionic plugin add @capacitor/geolocation\r\n```\r\n\r\n### 手动引入安装\r\n\r\n根据插件源码中 `plugin.xml` 配置在项目中引入插件：\r\n\r\n#### 1. 添加插件配置\r\n\r\n根据 `plugin.xml` 的 `config-json` 项，通过 `target` 字段找到 `entry` 模块中 `capacitor.plugins.json` 文件，并根据 `param`\r\n标签添加配置如下：\r\n\r\n```json\r\n{\r\n  \"pkg\": \"@capacitor/geolocation\",\r\n  \"classpath\": \"Geolocation\"\r\n}\r\n```\r\n\r\n#### 2. 修改 CMake 配置\r\n\r\n根据 `plugin.xml` 的 `CMakeLists` 项，通过 `modules-name` 字段找到模块 `capacitor`，路径为 `target` 字段的\r\n`CMakeLists.txt` 文件，并添加 `add_subdirectory` 和 `target_link_libraries` 如下：\r\n\r\n```cmake\r\n#START_ADD_SUBDIRECTORY\r\n// ...\r\nadd_subdirectory(Geolocation)\r\n// ...\r\n#END_ADD_SUBDIRECTORY\r\n\r\n// ...\r\n\r\ntarget_link_libraries(capacitor PUBLIC\r\n  \"-Wl,--whole-archive\"\r\n  // ...\r\n  Geolocation\r\n  // ...\r\n  \"-Wl,--no-whole-archive\"\r\n)\r\n```\r\n\r\n#### 3. 复制源码文件\r\n\r\n根据 `plugin.xml` 的 `source-file` 项，根据 `src` 字段找到需要复制的文件，并根据 `modules-name` 字段和 `target-dir`\r\n字段找到文件复制的具体模块和目录：\r\n\r\n将源码中src/main/cpp/Geolocation目录下的Geolocation.h、Geolocation.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Geolocation目录下。\r\n\r\n将源码中src/main/ets/components/Geolocation目录下的Geolocation.ets文件引入到capacitor模块中src/main/ets/components/Geolocation目录下。\r\n\r\n#### 4. 添加 ArkTS 配置\r\n\r\n在`capacitor`模块的`build-profile.json5`文件中，`buildOption/arkOptions/runtimeOnly/sources`配置项数组中加入步骤 3 中拷贝的\r\nets 文件路径：\r\n\r\n```json\r\n{\r\n  \"buildOption\": {\r\n    // ...\r\n    \"arkOptions\": {\r\n      \"runtimeOnly\": {\r\n        \"sources\": [\r\n          // ...\r\n          \"./src/main/ets/components/Geolocation/Geolocation.ets\"\r\n          // ...\r\n        ]\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## 卸载\r\n\r\n```bash\r\n# 卸载 geolocation 插件\r\nhionic plugin remove @capacitor/geolocation\r\n```\r\n\r\n## 约束与限制\r\n\r\n### 兼容性\r\n\r\n在以下版本中已测试通过：\r\n\r\n- capacitor: 8.0.0-ohos-8.0.0; SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;\r\n\r\n### 权限要求\r\n\r\nOpenHarmony权限参考[申请应用权限](https://docs.openharmony.cn/pages/v6.0/zh-cn/device-dev/subsystems/subsys-security-rightmanagement.md)\r\n，需在主工程的`module.json5`\r\n的requestPermissions中添加ohos.permission.LOCATION和ohos.permission.APPROXIMATELY_LOCATION权限，配置示例如下：\r\n\r\n```json\r\n{\r\n  \"requestPermissions\": [\r\n    {\r\n      \"name\": \"ohos.permission.LOCATION\",\r\n      \"reason\": \"$string:EntryAbility_location\",\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:EntryAbility_location\",\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### 示例1：获取当前位置\r\n\r\n```typescript\r\nimport { Geolocation } from '@capacitor/geolocation';\r\n\r\n// 获取当前位置\r\nconst position = await Geolocation.getCurrentPosition({\r\n  enableHighAccuracy: true,\r\n  timeout: 10000,\r\n  maximumAge: 0\r\n});\r\n\r\nif (apiButtonSectionRef.value) {\r\n  apiButtonSectionRef.value.updateButtonResult('get-current-position', {\r\n    status: 'success',\r\n    data: {\r\n      latitude: position.coords.latitude,\r\n      longitude: position.coords.longitude,\r\n      accuracy: position.coords.accuracy,\r\n      altitude: position.coords.altitude,\r\n      altitudeAccuracy: position.coords.altitudeAccuracy,\r\n      heading: position.coords.heading,\r\n      speed: position.coords.speed,\r\n      timestamp: position.timestamp\r\n    }\r\n  });\r\n}\r\n```\r\n\r\n## 使用说明\r\n\r\nGeolocation是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用。其中watchPosition方法会监听位置变化，能耗较高，建议仅在需要时使用。\r\n\r\n| 方法名                                                                                                                     | 返回类型                                                 | 描述                 | 备注                 |\r\n|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|--------------------|--------------------|\r\n| getCurrentPosition(options?: [PositionOptions](#positionoptions)丨 undefined)                                            | Promise&lt;[Position](#Position)&gt;                         | 获取设备的当前GPS位置       | 需申请定位权限            |\r\n| maximumAge             | number  | 可返回的缓存位置的最大有效期限（毫秒）                                   | 0       | 单位：毫秒        |\r\n\r\n| watchPosition(options: [PositionOptions](#positionoptions) , callback: [WatchPositionCallback](#watchpositioncallback)) | Promise&lt;[CallbackID](#callbackid)&gt;             | 设置一个位置变化的监控，监听位置变化 | 能耗较高，仅在需要时使用       |\r\n| clearWatch(options: [ClearWatchOptions](#clearwatchoptions))                                                            | Promise&lt;void&gt;                                  | 清除监听               | 需配合watchPosition使用 |\r\n| checkPermissions()                                                                                                      | Promise&lt;[PermissionStatus](#permissionstatus)&gt; | 检查地点权限             | 无                  |\r\n| requestPermissions(permissions?: [GeolocationPluginPermissions](#geolocationpluginpermissions)丨 undefined)              | Promise&lt;[PermissionStatus](#permissionstatus)&gt; | 请求地点权限             | 无                  |\r\n\r\n### 数据结构\r\n\r\n#### Position\r\n\r\n地理定位返回的位置信息对象，包含时间戳和GPS坐标相关数据。\r\n\r\n| 属性名       | 类型     | 描述                                    |\r\n|-----------|--------|---------------------------------------|\r\n| timestamp | number | 坐标创建时间戳                               |\r\n| coords    | object | GPS坐标以及数据的准确性，包含latitude、longitude等属性 |\r\n\r\ncoords属性详情：\r\n\r\n| coords子属性        | 类型     | 描述              |\r\n|------------------|--------|-----------------|\r\n| latitude         | number | 纬度              |\r\n| longitude        | number | 经度              |\r\n| accuracy         | number | 位置精度（米）         |\r\n| altitudeAccuracy | number | 海拔精度（米），可能为null |\r\n| altitude         | number | 海拔高度（米），可能为null |\r\n| speed            | number | 速度（米/秒），可能为null |\r\n| heading          | number | 航向（度），可能为null   |\r\n\r\n#### PositionOptions\r\n\r\n调用定位相关方法时的入参对象，用于配置定位参数。\r\n\r\n| 属性名                    | 类型      | 描述                                                    | 默认值     | 备注           |\r\n|------------------------|---------|-------------------------------------------------------|---------|--------------|\r\n| enableHighAccuracy     | boolean | 高精度模式（如有GPS）                                          | false   | 无            |\r\n| timeout                | number  | 位置更新的最大等待时间（毫秒），OpenHarmony取值范围为≥1000                 | 10000   | 单位：毫秒        |\r\n| maximumAge             | number  | 可接受返回的缓存位置的最大时间（毫秒）                                   | 0       | 单位：毫秒        |\r\n| minimumUpdateInterval  | number  | 最小更新间隔，位置更新比此间隔快时，仅间隔过时才更新                            | 5000    | 单位：毫秒        |\r\n| interval               | number  | 希望接收位置更新的时间间隔（毫秒），平台可能无法保证及时更新                        | timeout | 单位：毫秒        |\r\n| enableLocationFallback | boolean | 定位设置检查失败时，是否回退到Android框架的LocationManager（仅适用于Android） | true    | 仅Android平台有效 |\r\n\r\n#### ClearWatchOptions\r\n\r\n| 属性名 | 类型                        |\r\n|-----|---------------------------|\r\n| id  | [CallbackID](#callbackid) |\r\n\r\n#### PermissionStatus\r\n\r\n权限检查或请求返回的结果对象，包含位置相关权限状态。\r\n\r\n| 属性名            | 类型              | 描述        |\r\n|----------------|-----------------|-----------|\r\n| location       | PermissionState | 位置的权限状态   |\r\n| coarseLocation | PermissionState | 粗略位置的权限状态 |\r\n\r\n#### GeolocationPluginPermissions\r\n\r\n请求权限时的入参对象，用于指定需要请求的权限。\r\n\r\n| 属性名         | 类型                          | 描述            |\r\n|-------------|-----------------------------|---------------|\r\n| permissions | GeolocationPermissionType[] | 需要请求的地理定位权限数组 |\r\n\r\n### 类型定义\r\n\r\n#### WatchPositionCallback\r\n\r\n位置变化监听的回调函数类型，用于接收位置更新或错误信息。\r\n\r\n```\r\n(position:Position | null, err ? : any):void\r\n```\r\n\r\n#### CallbackID\r\n\r\n监听回调的唯一标识，用于清除监听。\r\n\r\n```\r\nstring\r\n```\r\n\r\n#### PermissionState\r\n\r\n权限状态类型，用于表示权限的当前状态。\r\n\r\n```typescript\r\n'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'\r\n```\r\n\r\n#### GeolocationPermissionType\r\n\r\n地理定位权限类型，用于指定具体的权限。\r\n\r\n```typescript\r\n'location' | 'coarseLocation'\r\n```\r\n\r\n## 目录结构\r\n\r\n```plaintext\r\n|---- 目录\r\n|     |---- src/main  # 插件的实现代码\r\n|           |----cpp  # C++ 代码\r\n|           |----ets   # ArkTS 代码\r\n|     |---- README.md          # 说明文档\r\n|     |---- package.json       # 配置文件\r\n|     |---- plugin.xml         # 插件配置文件\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Ionic/capacitor-geolocation/issues)\r\n，当然，也非常欢迎发 [PR](https://gitcode.com/CPF-Ionic/capacitor-geolocation/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **MIT License** 开源，详见 [LICENSE](./LICENSE) 文件。","readmeFilename":"README.md"}