• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 获取设备的位置信息开发指导
2
3## 场景概述
4
5开发者可以调用OpenHarmony位置相关接口，获取设备实时位置，或者最近的历史位置，以及监听设备的位置变化。
6
7对于位置敏感的应用业务，建议获取设备实时位置信息。如果不需要设备实时位置信息，并且希望尽可能的节省耗电，开发者可以考虑获取最近的历史位置。
8
9## 接口说明
10
11获取设备的位置信息所使用的接口如下，详细说明参见：[Location Kit](../../reference/apis-location-kit/js-apis-geoLocationManager.md)。
12
13**表2** 获取设备的位置信息接口介绍
14
15| 接口名 | 功能描述 |
16| -------- | -------- |
17| [on(type: 'locationChange', request: LocationRequest | ContinuousLocationRequest, callback: Callback<Location>): void](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanageronlocationchange) | 开启位置变化订阅，并发起定位请求。 |
18| [off(type: 'locationChange', callback?: Callback<Location>): void](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagerofflocationchange) | 关闭位置变化订阅，并删除对应的定位请求。 |
19| [getCurrentLocation(request: CurrentLocationRequest | SingleLocationRequest, callback: AsyncCallback<Location>): void](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagergetcurrentlocation) | 获取当前位置，使用callback回调异步返回结果。|
20| [getCurrentLocation(request?: CurrentLocationRequest | SingleLocationRequest): Promise<Location>](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagergetcurrentlocation-2) | 获取当前位置，使用Promise方式异步返回结果。|
21| [getLastLocation(): Location](../../reference/apis-location-kit/js-apis-geoLocationManager.md#geolocationmanagergetlastlocation) | 获取最近一次定位结果。 |
22
23## 开发步骤
24
251. 获取设备的位置信息，需要有位置权限，位置权限申请的方法和步骤见[申请位置权限开发指导](location-permission-guidelines.md)。
26
272. 导入geoLocationManager模块，所有与基础定位能力相关的功能API，都是通过该模块提供的。
28
29   ```ts
30   import { geoLocationManager } from '@kit.LocationKit';
31   ```
323. 单次获取当前设备位置。多用于查看当前位置、签到打卡、服务推荐等场景。
33   - 方式一：获取系统缓存的最新位置。<br/>
34      如果系统当前没有缓存位置会返回错误码。<br/>
35      推荐优先使用该接口获取位置，可以减少系统功耗。<br/>
36      如果对位置的新鲜度比较敏感，可以先获取缓存位置，将位置中的时间戳与当前时间对比，若新鲜度不满足预期可以使用方式二获取位置。<br/>
37
38      ```ts
39      import { geoLocationManager } from '@kit.LocationKit';
40      import { BusinessError } from '@kit.BasicServicesKit'
41      try {
42          let location = geoLocationManager.getLastLocation();
43      } catch (err) {
44          console.error("errCode:" + JSON.stringify(err));
45      }
46      ```
47
48   - 方式二：获取当前位置。<br/>
49      首先要实例化[SingleLocationRequest](../../reference/apis-location-kit/js-apis-geoLocationManager.md#singlelocationrequest12)对象，用于告知系统该向应用提供何种类型的位置服务，以及单次定位超时时间。<br/>
50      - 设置LocatingPriority：<br/>
51         如果对位置的返回精度要求较高，建议LocatingPriority参数优先选择PRIORITY_ACCURACY，会将一段时间内精度较好的结果返回给应用。<br/>
52         如果对定位速度要求较高，建议LocatingPriority参数选择PRIORITY_LOCATING_SPEED，会将最先拿到的定位结果返回给应用。<br/>
53         两种定位策略均会同时使用GNSS定位和网络定位技术，以便在室内和户外场景下均可以获取到位置结果，对设备的硬件资源消耗较大，功耗也较大。<br/>
54      - 设置locatingTimeoutMs：<br/>
55         因为设备环境、设备所处状态、系统功耗管控策略等的影响，定位返回的时延会有较大波动，建议把单次定位超时时间设置为10秒。<br/>
56
57      以快速定位策略(PRIORITY_LOCATING_SPEED)为例，调用方式如下：<br/>
58
59      ```ts
60      import { geoLocationManager } from '@kit.LocationKit';
61      import { BusinessError } from '@kit.BasicServicesKit'
62      let request: geoLocationManager.SingleLocationRequest = {
63         'locatingPriority': geoLocationManager.LocatingPriority.PRIORITY_LOCATING_SPEED,
64         'locatingTimeoutMs': 10000
65      }
66      try {
67         geoLocationManager.getCurrentLocation(request).then((result) => { // 调用getCurrentLocation获取当前设备位置，通过promise接收上报的位置
68            console.log('current location: ' + JSON.stringify(result));
69         })
70         .catch((error:BusinessError) => { // 接收上报的错误码
71            console.error('promise, getCurrentLocation: error=' + JSON.stringify(error));
72         });
73       } catch (err) {
74         console.error("errCode:" + JSON.stringify(err));
75       }
76      ```
774. 持续定位。多用于导航、运动轨迹、出行等场景。</br>
78   首先要实例化[ContinuousLocationRequest](../../reference/apis-location-kit/js-apis-geoLocationManager.md#continuouslocationrequest12)对象，用于告知系统该向应用提供何种类型的位置服务，以及位置结果上报的频率。<br/>
79   - 设置locationScenario：<br/>
80      建议locationScenario参数优先根据应用的使用场景进行设置，该参数枚举值定义参见[UserActivityScenario](../../reference/apis-location-kit/js-apis-geoLocationManager.md#useractivityscenario12)，例如地图在导航时使用NAVIGATION参数，可以持续在室内和室外场景获取位置用于导航。</br>
81   - 设置interval：<br/>
82      表示上报位置信息的时间间隔，单位是秒，默认值为1秒。如果对位置上报时间间隔无特殊要求，可以不填写该字段。
83
84   以地图导航场景为例，调用方式如下：
85
86   ```ts
87   import { geoLocationManager } from '@kit.LocationKit';
88   let request: geoLocationManager.ContinuousLocationRequest= {
89      'interval': 1,
90      'locationScenario': geoLocationManager.UserActivityScenario.NAVIGATION
91   }
92   let locationCallback = (location:geoLocationManager.Location):void => {
93      console.log('locationCallback: data: ' + JSON.stringify(location));
94   };
95   try {
96      geoLocationManager.on('locationChange', request, locationCallback);
97   } catch (err) {
98      console.error("errCode:" + JSON.stringify(err));
99   }
100   ```
101   如果不主动结束定位可能导致设备功耗高，耗电快；建议在不需要获取定位信息时及时结束定位。
102   ```ts
103   geoLocationManager.off('locationChange', locationCallback);
104   ```
105