@react-native-ohos/react-native-amap-geolocation
v1.4.0
Published
ReactNative geolocation module for Harmony
Readme
模板版本：v0.4.2
本项目基于 react-native-amap-geolocation 开发。
该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-amap-geolocation 版本所属关系如下：
| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 |
| ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- |
| @react-native-ohos/react-native-amap-geolocation | ~ 1.4.0 | GitCode Releases | 0.82./0.84. | 是 | API12+ | 1.2.3 | master |
| @react-native-ohos/react-native-amap-geolocation | ~ 1.3.0 | GitCode Releases | 0.77.* | 否 | API12+ | 1.2.3 | br_rnoh0.77 |
| @react-native-ohos/react-native-amap-geolocation | ~ 1.2.4 | GitCode Releases | 0.72.* | 是 | API12+ | 1.2.3 | br_rnoh0.72 |
| @react-native-oh-tpl/react-native-amap-geolocation | <= 1.2.3-0.0.5@deprecated | GitHub Releases(deprecated) | 0.72.* | 否 | API12+ | 1.2.3 | sig |
简介
一个基于高德SDK获取定位的React Native库。
1. 安装与使用
进入到工程目录并输入以下命令：
npm
npm install @react-native-ohos/react-native-amap-geolocationyarn
yarn add @react-native-ohos/react-native-amap-geolocation下面的代码展示了这个库的基本使用场景：
[!WARNING] 使用时 import 的库名不变。
import * as React from "react";
import {
Button,
Platform,
ScrollView,
StyleSheet,
Text,
View,
} from "react-native";
import {
Geolocation, setInterval, addLocationListener,
setGeoLanguage, setDistanceFilter, init, setNeedAddress, start,
stop, setLocationTimeout, setOnceLocation, GeoLanguage
} from "react-native-amap-geolocation";
const style = StyleSheet.create({
body: {
padding: 16,
paddingTop: Platform.OS === "ios" ? 48 : 16,
},
button: {
flexDirection: "column",
marginRight: 8,
marginBottom: 5,
marginTop: 5
},
result: {
fontFamily: Platform.OS === "ios" ? "menlo" : "monospace",
},
});
class AmapGeoLocationDemo extends React.Component {
state = {
location: null, needAddressText: "setNeedAddress(false)",
language: "setLanguage(chinese)", interval: "setInterval(默认2000)", onceText: "setOnceLocation(false) 设置单次定位",
startText: "start 持续定位", timeoutText: "setLocationTimeout 设置请求定位超时时间",distanceText:"setDistanceFilter(0) 设置定位的最小更新距离"
};
watchId = 0;
needAddress = true;
currLanguage = GeoLanguage.ZH;
currInterval = false;
onceLocationJudge = false;
timeout5000 = false;
distanseJudge = true;
init = () => {
console.log("rn AMapLocationManagerImpl init");
init("5f7389b845cbd89b1c32e24f526728f4").then(() => {
console.log("rn AMapLocationManagerImpl init success");
});
};
addLocationListener = () => {
console.log("rn AMapLocationManagerImpl addLocationListener");
addLocationListener((locationData) => {
console.log("rn AMapLocationManagerImpl callback success:" + JSON.stringify(locationData, null, 2));
let location = locationData;
this.setState({ location: location });
});
};
setDistanceFilter = () => {
console.log("rn AMapLocationManagerImpl setDistanceFilter");
this.distanseJudge = !this.distanseJudge;
if (this.distanseJudge) {
setDistanceFilter(0);
this.setState({ distanceText: "setDistanceFilter(0) 设置定位的最小更新距离" });
} else {
setDistanceFilter(1);
this.setState({ distanceText: "setDistanceFilter(1) 设置定位的最小更新距离" });
}
};
setLocationTimeout = () => {
console.log("rn AMapLocationManagerImpl setLocationTimeout");
this.timeout5000 = !this.timeout5000;
if (this.timeout5000) {
setLocationTimeout(5000);
this.setState({ timeoutText: "setLocationTimeout(5000) 设置请求定位超时时间" });
} else {
setLocationTimeout(10000);
this.setState({ timeoutText: "setLocationTimeout(10000) 设置请求定位超时时间" });
}
};
start = () => {
console.log("rn AMapLocationManagerImpl start");
start();
};
stop = () => {
console.log("rn AMapLocationManagerImpl stop");
stop();
}
onceLocation = () => {
this.onceLocationJudge = !this.onceLocationJudge;
if (this.onceLocationJudge) {
setOnceLocation(true);
this.setState({ onceText: "setOnceLocation(true) 设置单次定位", startText: "start 单次定位" });
} else {
setOnceLocation(false);
this.setState({ onceText: "setOnceLocation(false) 设置单次定位", startText: "start 持续定位" });
}
console.log("rn AMapLocationManagerImpl current onceLocation:" + this.onceLocationJudge);
};
setInterval = () => {
if (this.currInterval) {
setInterval(2000);
this.setState({ interval: "setInterval:2000" });
} else {
setInterval(10000);
this.setState({ interval: "setInterval:10000" });
}
this.currInterval = !this.currInterval;
}
setNeedAddress = () => {
this.needAddress = !this.needAddress;
console.log("rn AMapLocationManagerImpl setNeedAddress:" + this.needAddress);
if (this.needAddress) {
setNeedAddress(true);
this.setState({ needAddressText: "setNeedAddress(true)" });
} else {
setNeedAddress(false);
this.setState({ needAddressText: "setNeedAddress(false)" });
}
}
setLanguage = () => {
// default = 0,chinese = 1, engilish=2;
console.log("rn AMapLocationManagerImpl setLanguage");
if (this.currLanguage == GeoLanguage.ZH) {
this.currLanguage = GeoLanguage.EN;
setGeoLanguage(GeoLanguage.EN);
this.setState({ language: "setLanguage(engilish)" });
} else {
this.currLanguage = GeoLanguage.ZH;
setGeoLanguage(GeoLanguage.ZH);
this.setState({ language: "setLanguage(chinese)" });
}
}
updateLocationState(location: any) {
console.log("rn AMapLocationManagerImpl updateLocationState");
if (location) {
this.setState({ location: location });
console.log(location);
}
}
getCurrentPosition = () => {
Geolocation.getCurrentPosition(
(position) => this.updateLocationState(position),
(error) => this.updateLocationState(error)
);
};
watchPosition = () => {
if (!this.watchId) {
this.watchId = Geolocation.watchPosition(
(position) => this.updateLocationState(position),
(error) => this.updateLocationState(error)
);
console.log("rn AMapLocationManagerImpl watchPosition watchId:" + this.watchId);
}
};
clearWatch = () => {
if (this.watchId) {
console.log("rn AMapLocationManagerImpl clearWatch watchId:" + this.watchId);
Geolocation.clearWatch(this.watchId);
this.watchId = 0;
}
stop();
this.setState({ location: null });
};
render() {
const location = this.state.location;
const needAddressText = this.state.needAddressText;
const language = this.state.language;
const currInterval = this.state.interval;
const onceText = this.state.onceText;
const startText = this.state.startText;
const timeoutText = this.state.timeoutText;
const distanceText = this.state.distanceText;
return (
<ScrollView contentContainerStyle={style.body}>
<View style={style.button}>
<Button onPress={this.init} title="init 初始化接口" />
</View>
<View style={style.button}>
<Button onPress={this.addLocationListener} title="addLocationListener 设置监听回调,原生接口不设置监听回调,text不会显示数据" />
</View>
<View style={style.button}>
<Button onPress={this.setDistanceFilter} title={distanceText} />
</View>
<View style={style.button}>
<Button onPress={this.setLocationTimeout} title={timeoutText} />
</View>
<View style={style.button}>
<Button onPress={this.onceLocation} title={onceText} />
</View>
<View style={style.button}>
<Button onPress={this.start} title={startText} />
</View>
<View style={style.button}>
<Button onPress={this.stop} title="stop 结束持续定位" />
</View>
<View style={style.button}>
<Button onPress={this.setInterval} title={currInterval} />
</View>
<View style={style.button}>
<Button onPress={this.setNeedAddress} title={needAddressText} />
</View>
<View style={style.button}>
<Button onPress={this.setLanguage} title={language} />
</View>
<View style={style.button}>
<Button onPress={this.getCurrentPosition} title="Geolocation.getCurrentPosition 获取当前位置，相当于单次请求" />
</View>
<View style={style.button}>
<Button onPress={this.watchPosition} title="Geolocation.watchPosition 开启持续定位" />
</View>
<View style={style.button}>
<Button onPress={this.clearWatch} title="Geolocation.clearWatch 结束持续定位" />
</View>
<Text style={style.result}>{`${JSON.stringify(location, null, 2)}`}</Text>
</ScrollView>
);
}
}
export default AmapGeoLocationDemo;2. Link
| | 是否支持autolink | RN框架版本 | |--------------------------------------|-----------------|------------| | ~ 1.4.0 | 是 | 0.82./0.84. | | ~ 1.3.0 | 否 | 0.77.* | | ~ 1.2.4 | 是 | 0.72.* | | <= 1.2.3-0.0.5@deprecated | 否 | 0.72.* |
使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md
如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。
此步骤为手动配置原生依赖项的指导。
首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。
2.1. Overrides RN SDK
为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。
关于该字段的作用请阅读官方说明：
{
"overrides": {
"@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // Path to local har package
// "@rnoh/react-native-openharmony" : "./react_native_openharmony" // Point to source code path
}
}2.2. 引入原生端代码
目前有两种方法：
- 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
- 直接链接源码。
方法一：通过 har 包引入（推荐）
[!TIP] har 包位于三方库安装路径的
harmony文件夹下。
打开 entry/oh-package.json5，添加以下依赖
"dependencies": {
"@react-native-ohos/react-native-amap-geolocation": "file:../../node_modules/@react-native-ohos/react-native-amap-geolocation/harmony/amap_geolocation.har"
}点击右上角的 sync 按钮
或者在终端执行：
cd entry
ohpm install方法二：直接链接源码
[!TIP] 如需使用直接链接源码，请参考直接链接源码说明
2.3. 配置 CMakeLists 和引入 AMapGeolocationPackage
若使用的是 <= 1.2.3-0.0.5 版本，请跳过本章。
打开 entry/src/main/cpp/CMakeLists.txt，添加：
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
# RNOH_BEGIN: manual_package_linking_1
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-amap-geolocation/src/main/cpp" ./amap_geolocation)
# RNOH_END: manual_package_linking_1
# RNOH_BEGIN: manual_package_linking_2
+ target_link_libraries(rnoh_app PUBLIC rnoh_amap_geolocation)
# RNOH_END: manual_package_linking_2打开 entry/src/main/cpp/PackageProvider.cpp，添加：
#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
+ #include "AMapGeolocationPackage.h"
using namespace rnoh;
std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
return {
std::make_shared<RNOHGeneratedPackage>(ctx),
+ std::make_shared<AMapGeolocationPackage>(ctx),
};
}2.4. 在 ArkTS 侧引入 AMapGeolocationPackage
打开 entry/src/main/ets/RNPackagesFactory.ts，添加：
...
+ import {AMapGeolocationPackage} from '@react-native-ohos/react-native-amap-geolocation/ts';
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
return [
new SamplePackage(ctx),
+ new AMapGeolocationPackage(ctx)
];
}2.5. 运行
点击右上角的 sync 按钮
或者在终端执行：
cd entry
ohpm install然后编译、运行即可。
3. 约束与限制
3.1. 兼容性
本文档内容基于以下环境验证通过：
- RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
- RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
- RNOH:0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.120 SP7;
- RNOH:0.84.1; SDK: HarmonyOS 6.0.2 Release SDK; IDE: 6.0.2 Release; ROM:7.0.0.100 SP9;
3.2. 权限要求
在 entry 目录下的module.json5中添加权限
打开 entry/src/main/module.json5，添加：
...
"requestPermissions": [
{
"name": "ohos.permission.LOCATION",
"reason": "$string:Access_Location",
"usedScene": {
"when":"inuse"
}
},
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:Access_AppRoximatelyLocation",
"usedScene": {
"when":"inuse"
}
},
{
"name": "ohos.permission.INTERNET",
}
]在 entry 目录下添加位置权限的原因
打开 entry/src/main/resources/base/element/string.json，添加：
...
{
"string": [
{
"name": "Access_Location",
"value": "access Location"
},
{
"name": "Access_AppRoximatelyLocation",
"value": "access AppRoximatelyLocation"
}
]
}4. 属性
[!TIP] "Platform"列表示该属性在原三方库上支持的平台。
[!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
| Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- |---------------|----------| -------- |-------------------| | init | 初始化 SDK(参数为字符串key) | Promise | yes | iOS/Android | yes | | addLocationListener | 添加定位监听函数 | EmitterSubscription | yes | iOS/Android | yes | | isStarted | 获取当前是否正在定位的状态(由于平台限制单次模式下返回false) | boolean | no | Android | yes | | setAllowsBackgroundLocationUpdates | 是否允许后台定位 | void | no | iOS | no | | setDesiredAccuracy | 设定期望的定位精度（米） | void | no | iOS | no | | setDistanceFilter | 设定定位的最小更新距离（米） | void | no | iOS | yes | | setGeoLanguage | 设置逆地理信息的语言，目前支持中文和英文 | void | no | iOS/Android | yes | | setGpsFirst | 设置首次定位是否等待卫星定位结果 | void | no | Android | no | | setGpsFirstTimeout | 设置优先返回卫星定位信息时等待卫星定位结果的超时时间（毫秒） | void | no | Android | no | | setHttpTimeout | 设置联网超时时间（毫秒） | void | no | Android | no | | setInterval | 设置发起定位请求的时间间隔（毫秒），默认 2000，最小值为 1000 | void | no | Android | yes | | setLocatingWithReGeocode | 连续定位是否返回逆地理编码 | void | no | iOS | no | | setLocationCacheEnable | 设置是否使用缓存策略 | void | no | Android | yes | | setLocationMode | 设置定位模式(参数为字符串枚举值) | void | no | Android | yes | | setLocationPurpose | 设置定位场景 | void | no | Android | no | | setLocationTimeout | 指定单次定位超时时间（秒） | void | yes | iOS | yes | | setMockEnable | 设置是否允许模拟位置 | void | no | Android | no | | setNeedAddress | 设置是否返回地址信息，默认返回地址信息 | void | yes | Android | yes | | setOnceLocation | 设置是否单次定位 | void | no | Android | yes | | setOnceLocationLatest | 设置定位是否等待 WiFi 列表刷新 | void | no | Android | no | | setOpenAlwaysScanWifi | 设置是否开启wifi始终扫描 | void | no | Android | no | | setPausesLocationUpdatesAutomatically | 指定定位是否会被系统自动暂停 | void | no | iOS | no | | setReGeocodeTimeout | 指定单次定位逆地理超时时间（秒）最小值是 2s。注意在单次定位请求前设置。 | void | no | iOS | no | | setSensorEnable | 设置是否使用设备传感器 | void | no | Android | no | | setWifiScan | 设置是否允许调用 WiFi 刷新 | void | no | Android | no | | start | 开始持续定位 | void | no | iOS/Android | yes | | stop | 停止持续定位 | void | no | iOS/Android | yes | | GeoLanguage | 逆地理信息语言枚举常量：ZH=中文(1), EN=英文(2) | GeoLanguage.ZH/GeoLanguage.EN | no | iOS/Android | yes | | Geolocation.getCurrentPosition | 获取当前位置信息 | void | no | iOS/Android | yes | | Geolocation.watchPosition | 注册监听器进行持续定位 | number | no | iOS/Android | yes | | Geolocation.clearWatch | 移除位置监听 | void | no | iOS/Android | yes |
setLocationMode 定位模式枚举值
setLocationMode(mode) 的 mode 参数为以下三个枚举值，对应不同的定位优先级：
| 枚举值 | 含义 | 鸿蒙映射（LocationRequestPriority） |
| ------ | ---- | ----------------------------------- |
| LocationMode.Battery_Saving | 低功耗模式，仅使用网络定位（依赖基站、WLAN、蓝牙） | LOW_POWER |
| LocationMode.Device_Sensors | 仅设备模式，以 GNSS 卫星定位为主，精度优先 | ACCURACY |
| LocationMode.Hight_Accuracy | 高精度模式，同时使用 GNSS 定位和网络定位，优先返回首次定位结果（默认值） | FIRST_FIX |
[!NOTE] 修改定位模式后需重新调用
start()生效。
5. 遗留问题
- [ ] setGpsFirst()接口获取当前是否正在定位的状态,harmony暂不支持issue#3
- [ ] setGpsFirstTimeout()接口获取当前是否正在定位的状态,harmony暂不支持issue#4
- [ ] setHttpTimeout()接口获取当前是否正在定位的状态,harmony暂不支持issue#5
- [ ] setMockEnable()接口获取当前是否正在定位的状态,harmony暂不支持issue#6
- [ ] setOnceLocationLatest()接口获取当前是否正在定位的状态,harmony暂不支持issue#7
- [ ] setOpenAlwaysScanWifi()接口获取当前是否正在定位的状态,harmony暂不支持issue#8
- [ ] setPausesLocationUpdatesAutomatically()接口获取当前是否正在定位的状态,harmony暂不支持issue#9
- [ ] setReGeocodeTimeout()接口获取当前是否正在定位的状态,harmony暂不支持issue#10
- [ ] setSensorEnable()接口获取当前是否正在定位的状态,harmony暂不支持issue#11
- [ ] setWifiScan()接口获取当前是否正在定位的状态,harmony暂不支持issue#12
- [ ] setLocationPurpose()接口获取当前是否正在定位的状态,harmony暂不支持issue#15
- [ ] setLocatingWithReGeocode()接口获取当前是否正在定位的状态设置连续定位是否返回逆地理编码,harmony暂不支持issue#19
- [ ] setDesiredAccuracy()接口设定期望的定位精度,harmony暂不支持issue#22
- [ ] setAllowsBackgroundLocationUpdates()接口是否允许后台定位,harmony暂不支持issue#23
6. 目录结构
/rntpc_react-native-amap-geolocation # 项目根目录
├── harmony # 鸿蒙适配代码
│ └─ amap_geolocation.har # har包
│ └─ amap_geolocation # 鸿蒙适配核心代码
│ └─ Index.ets # 鸿蒙适配代码入口
│ └─ src/main/ets
│ └─ AMapGeolocationModule # TurboModule接口
├── src # RN代码
│ └─ index.js # 入口文件
│ └─ NativeRNAMapGeolocation.ts 桥接TurboModule
├── README_en.md # 英文安装使用方法
├── README.md # 中文安装使用方法 7. 贡献代码
使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR 。
8. 开源协议
本项目基于 The MIT License (MIT) ，请自由地享受和参与开源。