@capacitor/geolocation

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/geolocation是capacitor生态系统中的核心插件，利用GPS获取和追踪设备当前位置，为跨平台应用开发提供设备差异化适配能力，兼容capacitor的Android、iOS等主流移动平台及浏览器环境，本文档只说明在OpenHarmony系统中的使用。

API提供了简单的方法，利用GPS获取和追踪设备当前位置，并附带高度、航向和速度信息（如有），满足各类地理定位场景需求。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/geolocation

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/geolocation

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/geolocation",
  "classpath": "Geolocation"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Geolocation)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Geolocation
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中src/main/cpp/Geolocation目录下的Geolocation.h、Geolocation.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Geolocation目录下。

将源码中src/main/ets/components/Geolocation目录下的Geolocation.ets文件引入到capacitor模块中src/main/ets/components/Geolocation目录下。

4. 添加 ArkTS 配置

在capacitor模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

{
  "buildOption": {
    // ...
    "arkOptions": {
      "runtimeOnly": {
        "sources": [
          // ...
          "./src/main/ets/components/Geolocation/Geolocation.ets"
          // ...
        ]
      }
    }
  }
}

卸载

# 卸载 geolocation 插件
hionic plugin remove @capacitor/geolocation

约束与限制

兼容性

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

• capacitor: 8.0.0-ohos-8.0.0; SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony权限参考申请应用权限 ，需在主工程的module.json5 的requestPermissions中添加ohos.permission.LOCATION和ohos.permission.APPROXIMATELY_LOCATION权限，配置示例如下：

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

使用示例

示例1：获取当前位置

import { Geolocation } from '@capacitor/geolocation';

// 获取当前位置
const position = await Geolocation.getCurrentPosition({
  enableHighAccuracy: true,
  timeout: 10000,
  maximumAge: 0
});

if (apiButtonSectionRef.value) {
  apiButtonSectionRef.value.updateButtonResult('get-current-position', {
    status: 'success',
    data: {
      latitude: position.coords.latitude,
      longitude: position.coords.longitude,
      accuracy: position.coords.accuracy,
      altitude: position.coords.altitude,
      altitudeAccuracy: position.coords.altitudeAccuracy,
      heading: position.coords.heading,
      speed: position.coords.speed,
      timestamp: position.timestamp
    }
  });
}

使用说明

Geolocation是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用。其中watchPosition方法会监听位置变化，能耗较高，建议仅在需要时使用。

| 方法名 | 返回类型 | 描述 | 备注 | |-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|--------------------|--------------------| | getCurrentPosition(options?: PositionOptions丨 undefined) | Promise<void> | 获取设备的当前GPS位置 | 需申请定位权限 | | watchPosition(options: PositionOptions , callback: WatchPositionCallback) | Promise<CallbackID> | 设置一个位置变化的监控，监听位置变化 | 能耗较高，仅在需要时使用 | | clearWatch(options: ClearWatchOptions) | Promise<void> | 清除监听 | 需配合watchPosition使用 | | checkPermissions() | Promise<PermissionStatus> | 检查地点权限 | 无 | | requestPermissions(permissions?: GeolocationPluginPermissions丨 undefined) | Promise<PermissionStatus> | 请求地点权限 | 无 |

数据结构

Position

地理定位返回的位置信息对象，包含时间戳和GPS坐标相关数据。

| 属性名 | 类型 | 描述 | |-----------|--------|---------------------------------------| | timestamp | number | 坐标创建时间戳 | | coords | object | GPS坐标以及数据的准确性，包含latitude、longitude等属性 |

coords属性详情：

| coords子属性 | 类型 | 描述 | |------------------|--------|-----------------| | latitude | number | 纬度 | | longitude | number | 经度 | | accuracy | number | 位置精度（米） | | altitudeAccuracy | number | 海拔精度（米），可能为null | | altitude | number | 海拔高度（米），可能为null | | speed | number | 速度（米/秒），可能为null | | heading | number | 航向（度），可能为null |

PositionOptions

调用定位相关方法时的入参对象，用于配置定位参数。

| 属性名 | 类型 | 描述 | 默认值 | 备注 | |------------------------|---------|-------------------------------------------------------|---------|--------------| | enableHighAccuracy | boolean | 高精度模式（如有GPS） | false | 无 | | timeout | number | 位置更新的最大等待时间（毫秒），OpenHarmony取值范围为≥1000 | 10000 | 单位：毫秒 | | maximumAge | number | 可接受返回的缓存位置的最大时间（毫秒） | 0 | 单位：毫秒 | | minimumUpdateInterval | number | 最小更新间隔，位置更新比此间隔快时，仅间隔过时才更新 | 5000 | 单位：毫秒 | | interval | number | 希望接收位置更新的时间间隔（毫秒），平台可能无法保证及时更新 | timeout | 单位：毫秒 | | enableLocationFallback | boolean | 定位设置检查失败时，是否回退到Android框架的LocationManager（仅适用于Android） | true | 仅Android平台有效 |

ClearWatchOptions

| 属性名 | 类型 | |-----|---------------------------| | id | CallbackID |

PermissionStatus

权限检查或请求返回的结果对象，包含位置相关权限状态。

| 属性名 | 类型 | 描述 | |----------------|-----------------|-----------| | location | PermissionState | 位置的权限状态 | | coarseLocation | PermissionState | 粗略位置的权限状态 |

GeolocationPluginPermissions

请求权限时的入参对象，用于指定需要请求的权限。

| 属性名 | 类型 | 描述 | |-------------|-----------------------------|---------------| | permissions | GeolocationPermissionType[] | 需要请求的地理定位权限数组 |

类型定义

WatchPositionCallback

位置变化监听的回调函数类型，用于接收位置更新或错误信息。

(position:Position | null, err ? : any):void

CallbackID

监听回调的唯一标识，用于清除监听。

string

PermissionState

权限状态类型，用于表示权限的当前状态。

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

GeolocationPermissionType

地理定位权限类型，用于指定具体的权限。

'location' | 'coarseLocation'

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

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

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。