场景介绍

开发者可以调用 HarmonyOS 位置相关接口，获取设备实时位置，或者最近的历史位置。

对于位置敏感的应用业务，建议获取设备实时位置信息。如果不需要设备实时位置信息，并且希望尽可能的节省耗电，开发者可以考虑获取最近的历史位置。

接口说明

获取设备的位置信息，所使用的接口说明如下。

接口名	功能描述
Locator(Context context)	创建 Locator 实例对象。
RequestParam(int scenario)	根据定位场景类型创建定位请求的 RequestParam 对象。
onLocationReport(Location location)	获取定位结果。
startLocating(RequestParam request, LocatorCallback callback)	向系统发起定位请求。
requestOnce(RequestParam request, LocatorCallback callback)	向系统发起单次定位请求。
stopLocating(LocatorCallback callback)	结束定位。
getCachedLocation()	获取系统缓存的位置信息。

开发步骤

1. 应用在使用系统能力前，需要检查是否已经获取用户授权访问设备位置信息。如未获得授权，可以向用户申请需要的位置权限。

系统提供的定位权限有：

• ohos.permission.LOCATION
• ohos.permission.LOCATION_IN_BACKGROUND

访问设备的位置信息，必须申请 ohos.permission.LOCATION 权限，并且获得用户授权。

如果应用在后台运行时也需要访问设备位置，除需要将应用声明为允许后台运行外，还必须申请 ohos.permission.LOCATION_IN_BACKGROUND 权限，这样应用在切入后台之后，系统依然可以继续上报位置信息。

开发者可以在应用 config.json 文件中声明所需要的权限，示例代码如下：

   {
       "reqPermissions": [{
           "name": "ohos.permission.LOCATION",
           "reason": "$string:reason_description",
           "usedScene": {
               "ability": ["com.myapplication.LocationAbility"],
               "when": "inuse"
           }, {
           ...
           }]
       }]
   }

说明

配置字段详细说明见权限开发指导。在使用系统位置能力时，向用户动态申请位置权限，申请方式请参考动态申请权限开发步骤。

1. 实例化 Locator 对象，所有与基础定位能力相关的功能 API，都是通过 Locator 提供的。

   Locator locator = new Locator(context);

其中入参需要提供当前应用程序的 AbilityInfo 信息，便于系统管理应用的定位请求。

1. 实例化 RequestParam 对象，用于告知系统该向应用提供何种类型的位置服务，以及位置结果上报的频率。

方式一：

为了面向开发者提供贴近其使用场景的 API 使用方式，系统定义了几种常见的位置能力使用场景，并针对使用场景做了适当的优化处理，应用可以直接匹配使用，简化开发复杂度。系统当前支持场景如下表所示。

场景名称	常量定义	说明
导航场景	SCENE_NAVIGATION	适用于在户外定位设备实时位置的场景，如车载、步行导航。在此场景下，为保证系统提供位置结果精度最优，主要使用 GNSS 定位技术提供定位服务，结合场景特点，在导航启动之初，用户很可能在室内、车库等遮蔽环境， GNSS 技术很难提供位置服务。为解决此问题，我们会在 GNSS 提供稳定位置结果之前，使用系统网络定位技术，向应用提供位置服务，以在导航初始阶段提升用户体验。此场景默认以最小 1 秒间隔上报定位结果，使用此场景的应用必须申请 ohos.permission.LOCATION 权限，同时获得用户授权。
轨迹跟踪场景	SCENE_TRAJECTORY_TRACKING	适用于记录用户位置轨迹的场景，如运动类应用记录轨迹功能。主要使用 GNSS 定位技术提供定位服务。此场景默认以最小 1 秒间隔上报定位结果，并且应用必须申请 ohos.permission.LOCATION 权限，同时获得用户授权。
出行约车场景	SCENE_CAR_HAILING	适用于用户出行打车时定位当前位置的场景，如网约车类应用。此场景默认以最小 1 秒间隔上报定位结果，并且应用必须申请 ohos.permission.LOCATION 权限，同时获得用户授权。
生活服务场景	SCENE_DAILY_LIFE_SERVICE	生活服务场景，适用于不需要定位用户精确位置的使用场景，如新闻资讯、网购、点餐类应用，做推荐、推送时定位用户大致位置即可。此场景默认以最小 1 秒间隔上报定位结果，并且应用至少申请 ohos.permission.LOCATION 权限，同时获得用户授权。
无功耗场景	SCENE_NO_POWER	无功耗场景，适用于不需要主动启动定位业务。系统在响应其他应用启动定位业务并上报位置结果时，会同时向请求此场景的应用程序上报定位结果，当前的应用程序不产生定位功耗。此场景默认以最小 1 秒间隔上报定位结果，并且应用需要申请 ohos.permission.LOCATION 权限，同时获得用户授权。

以导航场景为例，实例化方式如下：

   RequestParam requestParam = new RequestParam(RequestParam.SCENE_NAVIGATION);

方式二：

如果定义的现有场景类型不能满足所需的开发场景，系统提供了基本的定位优先级策略类型。

策略类型	常量定义	说明
定位精度优先策略	PRIORITY_ACCURACY	定位精度优先策略主要以 GNSS 定位技术为主，在开阔场景下可以提供纳米级的定位精度，具体性能指标依赖用户设备的定位硬件能力，但在室内等强遮蔽定位场景下，无法提供准确的位置服务。应用必须申请 ohos.permission.LOCATION 权限，同时获得用户授权。
快速定位优先策略	PRIORITY_FAST_FIRST_FIX	快速定位优先策略会同时使用GNSS定位、基站定位和 WLAN、蓝牙定位技术，以便室内和户外场景下，通过此策略都可以获得位置结果，当各种定位技术都有提供位置结果时，系统会选择其中精度较好的结果返回给应用。因为对各种定位技术同时使用，对设备的硬件资源消耗较大，功耗也较大。应用必须申请 ohos.permission.LOCATION 权限，同时获得用户授权。
低功耗定位优先策略	PRIORITY_LOW_POWER	低功耗定位优先策略主要使用基站定位和 WLAN、蓝牙定位技术，也可以同时提供室内和户外场景下的位置服务，因为其依赖周边基站、可见 WLAN、蓝牙设备的分布情况，定位结果的精度波动范围较大，如果对定位结果精度要求不高，或者使用场景多在有基站、可见 WLAN、蓝牙设备高密度分布的情况下，推荐使用，可以有效节省设备功耗。应用至少申请 ohos.permission.LOCATION 权限，同时获得用户授权。

以定位精度优先策略为例，实例化方式如下：

   RequestParam requestParam = new RequestParam(RequestParam.PRIORITY_ACCURACY,0,0);

后两个入参用于限定系统向应用上报定位结果的频率，分别为位置上报的最小时间间隔，和位置上报的最小距离间隔，开发者可以参考 API 具体说明进行开发。

1. 实例化 LocatorCallback 对象，用于向系统提供位置上报的途径。

应用需要自行实现系统定义好的回调接口，并将其实例化。系统在定位成功确定设备的实时位置结果时，会通过 onLocationReport 接口上报给应用。应用程序可以在 onLocationReport 接口的实现中完成自己的业务逻辑。

   MyLocatorCallback locatorCallback = new MyLocatorCallback();

    
   public class MyLocatorCallback implements LocatorCallback {
       @Override
       public void onLocationReport(Location location) {
       }

    
       @Override
       public void onStatusChanged(int type) {
       }

    
       @Override
       public void onErrorReport(int type) {
       }
   }

1. 启动定位。

   locator.startLocating(requestParam, locatorCallback);

如果应用不需要持续获取位置结果，可以使用如下方式启动定位，系统会上报一次实时定位结果后，自动结束应用的定位请求。应用不需要执行结束定位。

   locator.requestOnce(requestParam, locatorCallback);

1. （可选）结束定位。

   locator.stopLocating(locatorCallback);

如果应用使用场景不需要实时的设备位置，可以获取系统缓存的最近一次历史定位结果。

   locator.getCachedLocation();

此接口的使用需要应用向用户申请 LOCATION 位置权限。