Skip to content

Commit cbbec14

Browse files
meimeiqinjianqi
meimei
authored and
qinjianqi
committed
!795 docs: [Issues: #IA58CL]新增react-native-amap-geolocation指导文档
* docs: [Issues: #IA58CL]新增react-native-amap-geolocation指导文档
1 parent fc82441 commit cbbec14

File tree

1 file changed

+378
-0
lines changed

1 file changed

+378
-0
lines changed

‎zh-cn/react-native-amap-geolocation.md

+378
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,378 @@
1+
<!-- {% raw %} -->
2+
> 模板版本：v0.2.2
3+
4+
<p align="center">
5+
<h1 align="center"> <code>react-native-amap-geolocation</code> </h1>
6+
</p>
7+
<p align="center">
8+
<a href="https://github.com/qiuxiang/react-native-amap-geolocation">
9+
<img src="https://img.shields.io/badge/platforms-android%20|%20ios%20|%20harmony%20-lightgrey.svg" alt="Supported platforms" />
10+
</a>
11+
<a href="https://github.com/qiuxiang/react-native-amap-geolocation/blob/main/license">
12+
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" />
13+
</a>
14+
</p>
15+
16+
17+
> [!TIP] [Github 地址](https://github.com/react-native-oh-library/react-native-amap-geolocation)
18+
19+
20+
21+
## 安装与使用
22+
23+
请到三方库的 Releases 发布地址查看配套的版本信息：[@react-native-oh-tpl/react-native-amap-geolocation Releases](https://github.com/react-native-oh-library/react-native-amap-geolocation/releases)，并下载适用版本的 tgz 包。
24+
25+
进入到工程目录并输入以下命令：
26+
27+
> [!TIP] # 处替换为 tgz 包的路径
28+
29+
<!-- tabs:start -->
30+
31+
#### **npm**
32+
33+
```bash
34+
npm install @react-native-oh-tpl/react-native-amap-geolocation@file:#
35+
```
36+
37+
#### **yarn**
38+
39+
```bash
40+
yarn add @react-native-oh-tpl/react-native-amap-geolocation@file:#
41+
```
42+
43+
<!-- tabs:end -->
44+
45+
下面的代码展示了这个库的基本使用场景：
46+
47+
> [!WARNING] 使用时 import 的库名不变。
48+
49+
```js
50+
import * as React from "react";
51+
import {
52+
Button,
53+
Platform,
54+
ScrollView,
55+
StyleSheet,
56+
Text,
57+
View,
58+
} from "react-native";
59+
import Geolocation from "react-native-amap-geolocation";
60+
61+
const style = StyleSheet.create({
62+
body: {
63+
padding: 16,
64+
paddingTop: Platform.OS === "ios" ? 48 : 16,
65+
},
66+
controls: {
67+
flexWrap: "wrap",
68+
alignItems: "flex-start",
69+
flexDirection: "row",
70+
marginBottom: 16,
71+
},
72+
button: {
73+
flexDirection: "column",
74+
marginRight: 8,
75+
marginBottom: 8,
76+
marginTop:50
77+
},
78+
result: {
79+
fontFamily: Platform.OS === "ios" ? "menlo" : "monospace",
80+
},
81+
});
82+
83+
class AmapGeoLocationDemo extends React.Component {
84+
state = { location: null };
85+
86+
componentDidMount(){
87+
Geolocation.init("aabbbcccc")
88+
}
89+
90+
start=()=>{
91+
console.log("geolocation start");
92+
Geolocation.start().then((result)=>{
93+
let location = result;
94+
this.setState({ location });
95+
console.log("geolocationupdateLocation:"+location);
96+
}).catch((error)=>{
97+
console.log(error);
98+
});
99+
};
100+
101+
stop =()=>{
102+
console.log("geolocation stop");
103+
Geolocation.stop();
104+
}
105+
106+
onceLocation= ()=>{
107+
Geolocation.setOnceLocation().then((result)=>{
108+
let location = result;
109+
this.setState({ location });
110+
console.log("geolocation onceLocation:"+location);
111+
}).catch((error)=>{
112+
console.log(error);
113+
});
114+
115+
};
116+
getLastKnownLocation= () =>{
117+
Geolocation.getLastKnownLocation().then((result)=>{
118+
let location = result;
119+
this.setState({ location });
120+
console.log("geolocation lastLocation:"+location);
121+
}).catch((error)=>{
122+
console.log(error);
123+
});
124+
}
125+
126+
setInterval10000 = ()=>{
127+
Geolocation.setInterval(10000);
128+
}
129+
setInterval2000 = ()=>{
130+
Geolocation.setInterval(2000);
131+
}
132+
setNeedAddressTrue=()=>{
133+
Geolocation.setNeedAddress(true);
134+
}
135+
setNeedAddressFalse =()=>{
136+
Geolocation.setNeedAddress(false);
137+
}
138+
139+
setLangeChinese=()=>{
140+
Geolocation.setGeoLanguage(1);
141+
}
142+
setLangeEnglish=()=>{
143+
Geolocation.setGeoLanguage(2);
144+
}
145+
render() {
146+
const { location } = this.state;
147+
return (
148+
<ScrollView contentContainerStyle={style.body}>
149+
<View style={style.button}>
150+
<Button onPress={this.start} title="start" />
151+
</View>
152+
<View style={style.button}>
153+
<Button onPress={this.stop} title="stop" />
154+
</View>
155+
<View style={style.button}>
156+
<Button onPress={this.onceLocation} title="setOnceLocation" />
157+
</View>
158+
<View style={style.button}>
159+
<Button onPress={this.getLastKnownLocation} title="getLastKnownLocation" />
160+
</View>
161+
<View style={style.button}>
162+
<Button onPress={this.setInterval2000} title="setInterval(2000)" />
163+
</View>
164+
<View style={style.button}>
165+
<Button onPress={this.setInterval10000} title="setInterval(10000)" />
166+
</View>
167+
<View style={style.button}>
168+
<Button onPress={this.setNeedAddressTrue} title="setNeedAddress(true)" />
169+
</View>
170+
<View style={style.button}>
171+
<Button onPress={this.setNeedAddressFalse} title="setNeedAddress(false)" />
172+
</View>
173+
<View style={style.button}>
174+
<Button onPress={this.setLangeChinese} title="setLangeChinese" />
175+
</View>
176+
<View style={style.button}>
177+
<Button onPress={this.setLangeEnglish} title="setLangeEnglish" />
178+
</View>
179+
<Text style={style.result}>{`${JSON.stringify(location, null, 2)}`}</Text>
180+
</ScrollView>
181+
);
182+
}
183+
}
184+
185+
export default AmapGeoLocationDemo;
186+
```
187+
188+
## 使用 Codegen
189+
190+
本库已经适配了 `Codegen` ，在使用前需要主动执行生成三方库桥接代码，详细请参考[ Codegen 使用文档](/zh-cn/codegen.md)。
191+
192+
193+
## Link
194+
195+
目前HarmonyOS暂不支持 AutoLink，所以 Link 步骤需要手动配置。
196+
197+
首先需要使用 DevEco Studio 打开项目里的HarmonyOS工程 `harmony`
198+
199+
### 在工程根目录的 `oh-package.json` 添加 overrides 字段
200+
201+
```json
202+
{
203+
...
204+
"overrides": {
205+
"@rnoh/react-native-openharmony" : "./react_native_openharmony"
206+
}
207+
}
208+
```
209+
210+
### 引入原生端代码
211+
212+
目前有两种方法：
213+
214+
1. 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
215+
2. 直接链接源码。
216+
217+
方法一：通过 har 包引入（推荐）
218+
219+
> [!TIP] har 包位于三方库安装路径的 `harmony` 文件夹下。
220+
221+
打开 `entry/oh-package.json5`，添加以下依赖
222+
223+
```json
224+
"dependencies": {
225+
"@rnoh/react-native-openharmony": "file:../react_native_openharmony",
226+
"@react-native-oh-tpl/react-native-amap-geolocation": "file:../../node_modules/@react-native-oh-tpl/react-native-amap-geolocation/harmony/amap_geolocation.har"
227+
}
228+
```
229+
230+
点击右上角的 `sync` 按钮
231+
232+
或者在终端执行：
233+
234+
```bash
235+
cd entry
236+
ohpm install
237+
```
238+
239+
方法二：直接链接源码
240+
241+
> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](/zh-cn/link-source-code.md)
242+
243+
### 在 ArkTs 侧引入 AmapGeolocationPackage
244+
245+
打开 `entry/src/main/ets/RNPackagesFactory.ts`，添加：
246+
247+
```diff
248+
...
249+
+ import {AmapGeolocationPackage} from '@react-native-oh-tpl/react-native-amap-geolocation';
250+
251+
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
252+
return [
253+
new SamplePackage(ctx),
254+
+ new AmapGeolocationPackage(ctx)
255+
];
256+
}
257+
```
258+
259+
### 运行
260+
261+
点击右上角的 `sync` 按钮
262+
263+
或者在终端执行：
264+
265+
```bash
266+
cd entry
267+
ohpm install
268+
```
269+
270+
然后编译、运行即可。
271+
272+
## 约束与限制
273+
274+
### 兼容性
275+
276+
要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和 手机 ROM。
277+
278+
请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[@react-native-oh-tpl/react-native-amap-geolocation Releases](https://github.com/react-native-oh-library/react-native-amap-geolocation/releases)
279+
280+
281+
## 属性
282+
283+
> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。
284+
285+
> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
286+
287+
| Name | Description | Type | Required | Platform | HarmonyOS Support |
288+
| ---- | ----------- | ---- | -------- | -------- | ------------------ |
289+
| code | 错误代码 | number | yes | iOS/Android | yes |
290+
| message | 错误信息 | string | yes | iOS/Android | yes |
291+
| android | Android平台 | string | yes | iOS/Android | yes |
292+
| iOS | iOS平台 | string | yes | iOS/Android | yes |
293+
| accuracy | 定位精度 (米) | number | yes | iOS/Android | yes |
294+
| altitude | 海拔（米），需要 GPS | number | yes | iOS/Android | yes |
295+
| altitudeAccuracy | 海拔精度 | number | yes | iOS/Android | yes |
296+
| latitude | 经度，[-180, 180] | number | yes | iOS/Android | yes |
297+
| longitude | 纬度，[-90, 90] | number | yes | iOS/Android | yes |
298+
| speed | 移动速度（米/秒），需要 GPS | number | yes | iOS/Android | yes |
299+
| coordinateType | 坐标系类型 | string | yes | Android | yes |
300+
| errorInfo | 错误信息 | string | yes | iOS/Android | yes |
301+
| heading | 移动方向，需要 GPS | number | yes | iOS/Android | yes |
302+
| locationDetail | 定位信息描述 | string | yes | Android | yes |
303+
| timestamp | 定位时间（毫秒） | number | yes | iOS/Android | yes |
304+
| distanceFilter | 位置信息的距离过滤器，用于限制位置更新的触发频率 | number | yes | iOS/Android | yes |
305+
| enableHighAccuracy | 是否启用高精度模式来获取位置信息。 | boolean | yes | iOS/Android | yes |
306+
| maximumAge | 获取位置信息的最大缓存时间 | number | yes | iOS/Android | yes |
307+
| timeout | 获取位置信息的超时时间 | number | yes | iOS/Android | yes |
308+
| address | 详细地址 | number | yes | iOS/Android | yes |
309+
|city | 城市 | string | yes | iOS/Android | yes |
310+
| cityCode | 城市编码 | string | yes | iOS/Android | yes |
311+
| country | 国家 | string | yes | iOS/Android | yes |
312+
| district | 地区 | string | yes | iOS/Android | yes |
313+
| poiName | 兴趣点 | string | yes | iOS/Android | yes |
314+
| province | 省份 | string | yes | iOS/Android | yes |
315+
| street | 街道 | string | yes | iOS/Android | yes |
316+
| streetNumber | 门牌号 | string | yes | iOS/Android | yes |
317+
318+
319+
## API
320+
321+
> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。
322+
323+
> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。
324+
325+
| Name | Description | Type | Required | Platform | HarmonyOS Support |
326+
| ---- | ----------- | ---- | -------- | -------- |-------------------|
327+
| init | 初始化 SDK | Promise<void> | yes| iOS/Android | yes |
328+
| isStarted | 获取当前是否正在定位的状态 | boolean | yes | Android | no |
329+
| setAllowsBackgroundLocationUpdates | 是否允许后台定位 | void | yes | iOS | yes |
330+
| setDesiredAccuracy | 设定期望的定位精度（米） | void | yes | iOS | yes |
331+
| setDistanceFilter | 设定定位的最小更新距离（米） | void | yes | iOS | yes |
332+
| setGeoLanguage | 设置逆地理信息的语言，目前支持中文和英文 | void | yes | iOS/Android | yes |
333+
| setGpsFirst | 设置首次定位是否等待卫星定位结果 | void | yes | Android | no |
334+
| setGpsFirstTimeout | 设置优先返回卫星定位信息时等待卫星定位结果的超时时间（毫秒） | void | yes | Android | no |
335+
| setHttpTimeout | 设置联网超时时间（毫秒） | void | yes | Android | no |
336+
| setInterval | 设置发起定位请求的时间间隔（毫秒），默认 2000，最小值为 1000 | void | yes | Android | yes |
337+
| setLocatingWithReGeocode | 连续定位是否返回逆地理编码 | void | yes | iOS | yes |
338+
| setLocationCacheEnable | 设置是否使用缓存策略 | void | yes | Android | no |
339+
| setLocationMode | 设置定位模式 | void | yes | Android | no |
340+
| setLocationPurpose | 设置定位场景 | void | yes | Android | no |
341+
| setLocationTimeout | 指定单次定位超时时间（秒） | void | yes | iOS | yes |
342+
| setMockEnable | 设置是否允许模拟位置 | void | yes | Android | no |
343+
| setNeedAddress | 设置是否返回地址信息，默认返回地址信息 | void | yes | Android | yes |
344+
| setOnceLocation | 设置是否单次定位 | void | yes | Android | yes |
345+
| setOnceLocationLatest | 设置定位是否等待 WiFi 列表刷新 | void | yes | Android | no |
346+
| setOpenAlwaysScanWifi | 设置是否开启wifi始终扫描 | void | yes | Android | no |
347+
| setPausesLocationUpdatesAutomatically | 指定定位是否会被系统自动暂停 | void | yes | iOS | no |
348+
| setReGeocodeTimeout | 指定单次定位逆地理超时时间（秒）最小值是 2s。注意在单次定位请求前设置。 | void | yes | iOS | no |
349+
| setSensorEnable | 设置是否使用设备传感器 | void | yes | Android | no |
350+
| setWifiScan | 设置是否允许调用 WiFi 刷新 | void | yes | Android | no |
351+
| start | 开始持续定位 | void | yes | iOS/Android | yes |
352+
| stop | 停止持续定位 | void | yes | iOS/Android | yes |
353+
354+
## 遗留问题
355+
356+
- [ ] isStarted()接口获取当前是否正在定位的状态,harmony暂不支持[issue#2](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/2)
357+
- [ ] setGpsFirst()接口获取当前是否正在定位的状态,harmony暂不支持[issue#3](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/3)
358+
- [ ] setGpsFirstTimeout()接口获取当前是否正在定位的状态,harmony暂不支持[issue#4](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/4)
359+
- [ ] setHttpTimeout()接口获取当前是否正在定位的状态,harmony暂不支持[issue#5](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/5)
360+
- [ ] setMockEnable()接口获取当前是否正在定位的状态,harmony暂不支持[issue#6](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/6)
361+
- [ ] setOnceLocationLatest()接口获取当前是否正在定位的状态,harmony暂不支持[issue#7](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/7)
362+
- [ ] setOpenAlwaysScanWifi()接口获取当前是否正在定位的状态,harmony暂不支持[issue#8](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/8)
363+
- [ ] setPausesLocationUpdatesAutomatically()接口获取当前是否正在定位的状态,harmony暂不支持[issue#9](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/9)
364+
- [ ] setReGeocodeTimeout()接口获取当前是否正在定位的状态,harmony暂不支持[issue#10](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/10)
365+
- [ ] setSensorEnable()接口获取当前是否正在定位的状态,harmony暂不支持[issue#11](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/11)
366+
- [ ] setWifiScan()接口获取当前是否正在定位的状态,harmony暂不支持[issue#12](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/12)
367+
- [ ] setLocationCacheEnable()接口获取当前是否正在定位的状态,harmony暂不支持[issue#13](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/13)
368+
- [ ] setLocationMode()接口获取当前是否正在定位的状态,harmony暂不支持[issue#14](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/14)
369+
- [ ] setLocationPurpose()接口获取当前是否正在定位的状态,harmony暂不支持[issue#15](https://github.com/react-native-oh-library/react-native-amap-geolocation/issues/15)
370+
371+
372+
## 其他
373+
374+
## 开源协议
375+
376+
本项目基于 [The MIT License (MIT)](https://github.com/qiuxiang/react-native-amap-geolocation/blob/main/license) ，请自由地享受和参与开源。
377+
378+
<!-- {% endraw %} -->

0 commit comments

Comments
 (0)