一、Location Kit 服务

1.1 定位技术

位置子系统使用多种定位技术提供服务：

定位技术	说明	精度
GNSS定位	基于GPS、GLONASS、北斗、Galileo等导航卫星	高
基站定位	根据设备当前驻网基站和相邻基站位置估算	较低
WLAN/蓝牙定位	根据周围WLAN、蓝牙设备位置估算	依赖设备分布密度

注意：定位过程具体使用哪些定位系统，取决于用户设备的硬件能力。

1.2 坐标系统

系统以1984年世界大地坐标系统（WGS-84）为参考，使用经度、纬度数据描述地球上的一个位置。

说明：本模块能力仅支持WGS-84坐标系。如需转换成其他坐标系，请参考坐标转换工具。

1.3 扩展功能

功能	说明
地理围栏	虚拟地理边界，当设备进入/离开特定区域时接收通知
正地理编码	根据地址获取地点的经纬度
逆地理编码	获取经纬度对应的地点信息

二、限制

2.1 基本要求

要求	说明
位置开关	用户必须主动开启位置开关，否则系统不提供定位服务
权限申请	应用必须向用户申请位置访问权限（敏感数据）
主动请求	应用需主动发起请求，并在业务结束时主动结束

2.2 设备能力

设备类型	定位能力
有定位芯片	GNSS定位能力
无定位芯片但有WLAN/蜂窝网络	WLAN定位、基站定位能力

2.3 支持的设备

设备类型	支持
Phone	✅
Tablet	✅
PC/2in1	✅
Wearable	✅

2.4 支持的国家/地区

设备类型	支持地区
Wearable	特定国家和地区（见附录）
其他设备	仅中国境内（不含港澳台）

三、核心接口

接口	功能描述
on('locationChange')	开启位置变化订阅，并发起定位请求
off('locationChange')	关闭位置变化订阅，并删除对应的定位请求
getCurrentLocation()	获取当前位置（callback/Promise）
getLastLocation()	获取最近一次定位结果
isLocationEnabled()	判断位置服务是否已经开启

四、开发步骤

4.1 导入模块

import { geoLocationManager } from '@kit.LocationKit';
import { BusinessError } from '@kit.BasicServicesKit';

4.2 判断位置开关状态

try {
  let locationEnabled = geoLocationManager.isLocationEnabled();
  console.info('位置开关状态: ' + locationEnabled);
} catch (err) {
  console.error("errCode:" + err.code + ", message:" + err.message);
}

提示：如果位置开关未开启，可以调用requestGlobalSwitch拉起全局开关设置弹框，引导用户打开位置开关。

4.3 获取设备位置信息

方式一：获取系统缓存的最新位置

推荐优先使用该接口获取位置，可以减少系统功耗。

try {
  let location = geoLocationManager.getLastLocation();
  console.info('缓存位置: ' + JSON.stringify(location));
} catch (err) {
  console.error("errCode:" + JSON.stringify(err));
}

注意：如果系统当前没有缓存位置会返回错误码。如果对位置的新鲜度比较敏感，可以先获取缓存位置，将位置中的时间戳与当前时间对比，若不满足预期再使用方式二获取位置。

方式二：单次获取当前位置（SingleLocationRequest）

定位策略选择：

策略	适用场景	说明
PRIORITY_ACCURACY	对精度要求较高	将一段时间内精度较好的结果返回
PRIORITY_LOCATING_SPEED	对定位速度要求较高	将最先拿到的定位结果返回

注意：两种定位策略均会同时使用GNSS定位和网络定位技术，室内和户外场景均可获取位置结果，但对硬件资源消耗较大，功耗也较大。

超时时间建议：建议设置为10秒（设备环境、状态、系统功耗管控策略等会影响定位返回时延）。

let request: geoLocationManager.SingleLocationRequest = {
  'locatingPriority': geoLocationManager.LocatingPriority.PRIORITY_LOCATING_SPEED,
  'locatingTimeoutMs': 10000  // 10秒
}

try {
  geoLocationManager.getCurrentLocation(request).then((result) => {
    console.info('当前位置: ' + JSON.stringify(result));
  }).catch((error: BusinessError) => {
    console.error('getCurrentLocation error: ' + JSON.stringify(error));
  });
} catch (err) {
  console.error("errCode:" + JSON.stringify(err));
}

4.4 持续定位（ContinuousLocationRequest）

多用于导航、运动轨迹、出行等场景。

参数：

参数	说明
interval	上报位置信息的时间间隔，单位秒，默认1秒
locationScenario	应用使用场景（如NAVIGATION）

场景参数（UserActivityScenario）：

场景	说明
NAVIGATION	导航场景，可持续在室内和室外获取位置

let request: geoLocationManager.ContinuousLocationRequest = {
  'interval': 1,
  'locationScenario': geoLocationManager.UserActivityScenario.NAVIGATION
}

let locationCallback = (location: geoLocationManager.Location): void => {
  console.info('位置更新: ' + JSON.stringify(location));
};

try {
  geoLocationManager.on('locationChange', request, locationCallback);
} catch (err) {
  console.error("errCode:" + JSON.stringify(err));
}

4.5 结束定位

说你：如果不主动结束定位可能导致设备功耗高、耗电快。建议在不需要获取定位信息时及时结束定位。

// 需要与on接口传入的回调函数保持一致
geoLocationManager.off('locationChange', locationCallback);

五、定位策略对比

策略	适用场景	精度	速度	功耗
PRIORITY_ACCURACY	签到打卡、服务推荐	高	慢	高
PRIORITY_LOCATING_SPEED	快速定位需求	中	快	高