react-native-geolocation-service

本项目基于 react-native-geolocation-service开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

react-native-geolocation-service 的鸿蒙（OpenHarmony / HarmonyOS）适配包，提供单次定位、持续位置监听与定位授权能力。当前版本 5.3.1-beta.1，含原生 HAR（harmony/geolocation_service/），基于 TurboModule RNFusedLocation，鸿蒙端通过 @kit.LocationKit 的 geoLocationManager 实现定位，并通过 @ohos.abilityAccessCtrl 申请运行时权限。业务侧可继续使用原包名导入。

集成指南

npm install @hxa-rn/react-native-geolocation-service

package.json 已配置 harmony.alias 为 react-native-geolocation-service，业务代码仍按原库导入：

import Geolocation from 'react-native-geolocation-service';

peerDependencies：react-native >= 0.72

engines：Node.js >= 18

本库含原生模块，支持 Autolinking。工程已接入 Autolink 时可跳过手动注册。

需同时在 C++ 与 ETS 侧注册 Package。

1. 引入原生依赖

在 entry/oh-package.json5 添加：

"dependencies": {
  "@hxa-rn/react-native-geolocation-service": "file:../../node_modules/@hxa-rn/react-native-geolocation-service/harmony/geolocation_service.har"
}

执行 ohpm install。

2. 配置 CMakeLists

在 entry/src/main/cpp/CMakeLists.txt 添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@hxa-rn/react-native-geolocation-service/src/main/cpp" ./geolocation_service)

target_link_libraries(rnoh_app PUBLIC geolocation_service)

3. 注册 Package（C++）

在 entry/src/main/cpp/PackageProvider.cpp 中：

#include "GeolocationServicePackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<GeolocationServicePackage>(ctx),
    };
}

4. 注册 Package（ETS）

在 entry/src/main/ets/RNPackagesFactory.ets 中：

import { GeolocationServicePackage } from '@hxa-rn/react-native-geolocation-service/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new GeolocationServicePackage(ctx),
  ];
}

宿主应用 module.json5 需声明定位相关 user_grant 权限（含 reason / usedScene），详见「约束与限制」。

使用说明

建议先申请授权，再发起定位。下面是可复制的完整示例（含授权失败分支，以及 watchPosition 与 clearWatch / stopObserving 成对释放）：

import Geolocation, { PositionError } from 'react-native-geolocation-service';

async function demoLocation() {
  let auth;
  try {
    auth = await Geolocation.requestAuthorization('whenInUse');
  } catch (e) {
    console.log(e);
    return;
  }
  // 鸿蒙端：'granted' | 'denied' | 'disabled'
  if (auth !== 'granted') {
    return;
  }

  Geolocation.getCurrentPosition(
    (position) => {
      console.log(position.coords.latitude, position.coords.longitude);
    },
    (error) => {
      if (error.code === PositionError.TIMEOUT) {
        console.log('timeout', error.message);
        return;
      }
      console.log(error.code, error.message);
    },
    { enableHighAccuracy: true, timeout: 15000, maximumAge: 10000 }
  );

  const watchId = Geolocation.watchPosition(
    (position) => console.log(position),
    (error) => console.log(error.code),
    { interval: 1000, distanceFilter: 0 }
  );

  Geolocation.clearWatch(watchId);
  Geolocation.stopObserving();
}

demoLocation();

常用 options 字段（鸿蒙侧生效项）：

| 字段 | 说明 | |------|------| | enableHighAccuracy | true 时提高定位优先级 | | timeout | 超时（ms）；映射到鸿蒙 timeoutMs。小于 1000 时由原生兜底计时，不把过短超时直接传给系统 API | | maximumAge | 可接受的缓存位置最大年龄（ms） | | interval | 持续监听间隔（ms），映射为鸿蒙 timeInterval（秒） | | distanceFilter | 位移过滤（m），映射为鸿蒙 distanceInterval |

Android 特有选项（如 showLocationDialog、forceRequestLocation、forceLocationManager）以及 iOS 特有选项（如 useSignificantChanges、showsBackgroundLocationIndicator）在鸿蒙端忽略。

接口文档

公开入口见 src/index.js / src/Geolocation.native.js。

requestAuthorization(authorizationLevel)

• 功能：请求定位授权（iOS / Harmony 可用）。
• 参数：authorizationLevel：'whenInUse' | 'always'。
• 返回：Promise<string>，鸿蒙端为 'granted' | 'denied' | 'disabled'（无 'restricted'，受限场景归并为 'denied'）。
• 注意：鸿蒙上 'always' 与 'whenInUse' 均申请前台定位权限；系统定位开关关闭时返回 'disabled'。

getCurrentPosition(success, error?, options?)

• 功能：单次获取当前位置。
• 参数：成功回调、可选失败回调、可选 options。
• 返回：无（回调风格）。成功回调收到位置对象；失败回调收到 { code, message }。
• 注意：需已具备定位权限；maximumAge / timeout 等由鸿蒙 TurboModule 处理。

watchPosition(success, error?, options?)

• 功能：持续监听位置变化。
• 参数：成功回调、可选失败回调、可选 options。
• 返回：number（watchId）。底层通过 startObserving 与事件 geolocationDidChange / geolocationError 推送更新。

clearWatch(watchId)

• 功能：移除指定监听。
• 参数：watchId: number。
• 返回：无。无效或已清除的 watchId 静默忽略。

stopObserving()

• 功能：停止全部持续定位并清理监听。
• 参数：无。
• 返回：无。

setRNConfiguration(config)

• 功能：配置入口（与上游一致）。
• 注意：JS 层为 no-op，配置不生效。

PositionError

从包导出的错误码常量：

| 常量 | 值 | |------|----| | PERMISSION_DENIED | 1 | | POSITION_UNAVAILABLE | 2 | | TIMEOUT | 3 | | PLAY_SERVICE_NOT_AVAILABLE | 4 | | SETTINGS_NOT_SATISFIED | 5 | | INTERNAL_ERROR | -1 |

成功位置对象主要字段：coords（含 latitude / longitude / accuracy / altitude / heading / speed / altitudeAccuracy）、timestamp、mocked、provider。鸿蒙端 mocked 恒为 false，provider 固定为 'gps'；altitudeAccuracy 在可用时填充，否则为 null。

约束与限制

| 项 | 说明 | |----|------| | RN / RNOH | peerDependencies 要求 react-native >= 0.72；Demo 使用 [email protected] 与 @react-native-oh/[email protected] | | HarmonyOS SDK | Demo（example / example_auto）compatibleSdkVersion 为 6.0.1(21) | | Node.js | >= 18；运行 Example 建议 >= 20（见 example/package.json engines） | | 权限 | HAR 声明 ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.LOCATION（均为 user_grant）及 ohos.permission.INTERNET；宿主 module.json5 需同步声明并填写 reason / usedScene | | 架构 | 含原生 HAR harmony/geolocation_service，TurboModule RNFusedLocation，支持 Autolinking | | 后台定位 | 未适配：requestAuthorization('always') 不会申请 ohos.permission.LOCATION_IN_BACKGROUND | | 定位开关 | 系统定位关闭时，getCurrentPosition / watchPosition 可能返回 SETTINGS_NOT_SATISFIED（5） | | 平台选项 | Android / iOS 特有选项在鸿蒙端忽略；首次定位前建议调用 requestAuthorization('whenInUse') |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18（运行 Example 建议 >= 20，见 example/package.json） | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 21+（example/harmony 的 compatibleSdkVersion 为 6.0.1(21)） |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-geolocation-service.git
cd react-native-geolocation-service
git checkout br_rnoh0.72

2. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

4. 安装鸿蒙依赖

cd harmony
ohpm install

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 首次构建请在 File → Project Structure → Signing Configs 勾选 Automatically generate signature，Apply 后 Sync
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 已预置 Autolinking Package 注册、Metro alias 与 HAR 依赖，无需手动 Link。编 HAP 前必须先执行 npm run dev。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

欢迎在 AtomGit 提交 Issue。也可通过 GitCode 反馈：

• https://gitcode.com/hxa-rn/react-native-geolocation-service
• https://gitcode.com/hxa-rn/react-native-geolocation-service/issues