大家好,我是[晚风依旧似温柔],新人一枚,欢迎大家关注~

前言

在移动应用开发中,“定位”是一个极其常见但又非常容易引发性能和电量问题的模块。很多时候,从表现上看,应用只是打开了一个带有地图或者获取位置的页面,一旦用户离开这个页面,开发者往往以为系统会自动回收资源。但实际上,如果未能正确处理定位的生命周期,底层的位置更新回调可能依然在后台频繁被唤醒,导致设备持续耗电、发热,甚至在日志中抛出大量异常。

本文将以 HarmonyOS 官方提供的 @kit.LocationKit(位置服务)为依据,从单次定位与持续定位的区别入手,梳理页面切换时的定位生命周期,并探讨前后台权限边界,最后给出一套标准的订阅与取消订阅的最佳实践。

一、单次定位与持续定位的核心差异

在调用 HarmonyOS 位置服务时,@ohos.geoLocationManager(或 HarmonyOS NEXT 中的 @kit.LocationKit)提供了两种获取位置的策略:单次定位与持续定位。

  1. 单次定位 (getCurrentLocation)
    这个接口用于获取当前的一次最新位置。系统会在满足精度要求或超时后返回一个 Location 对象。
    特点:用完即走,系统会在返回结果后自动停止底层的位置硬件请求,不会带来长期的耗电负担。

  2. 持续定位 (on('locationChange'))
    这个接口用于订阅位置变化。只要设备位置发生变化(或者达到设定的时间/距离间隔),系统就会持续回调给应用。
    特点:如果开发者只调用了 on 订阅,而在页面销毁或隐藏时忘记调用 off 取消订阅,底层的定位芯片就会一直保持活跃状态。这就是导致页面退出后依然耗电的罪魁祸首。

二、权限边界:前台与后台的红线

在订阅位置变化之前,必须理清 HarmonyOS 的位置权限体系。HarmonyOS 对隐私保护极为严格,定位权限分为两个维度:精度与前后台。

  • 精度权限:

    • ohos.permission.APPROXIMATELY_LOCATION(模糊位置)
    • ohos.permission.LOCATION(精确位置)
    • 注意:从 API 9 开始,申请精确位置权限的前提是必须同时申请模糊位置权限。
  • 前后台边界(关键点):

    • 默认情况下,应用申请的都是前台位置权限。这意味着,当你的应用处于前台(用户可见可用)时,locationChange 可以正常回调。
    • 当应用退到后台(例如按 Home 键回到桌面),如果应用没有申请 ohos.permission.LOCATION_IN_BACKGROUND(后台定位权限),系统会直接切断定位更新。此时如果未主动取消订阅,不仅无法获取位置,还可能导致后续前台唤醒时的状态混乱。
    • 后台定位权限通常需要上架审核的强校验,普通应用如果没有导航、运动轨迹等核心业务,通常只允许使用前台定位。

三、把定位生命周期画成流程图

为了直观理解从进入页面到退出页面的全过程,我们可以将生命周期与 ArkUI 的页面生命周期(onPageShow / onPageHide / aboutToDisappear)结合起来。

以下是标准的定位生命周期时序图:

LocationKit底层服务 ArkUI 页面 用户 LocationKit底层服务 ArkUI 页面 用户 alt [权限校验通过] [权限受限] 进入定位页面 aboutToAppear() 初始化数据 onPageShow() 页面可见 校验定位权限 (abilityAccessCtrl) on('locationChange') 订阅持续定位 持续推送 Location 经纬度 抛出异常或无回调 离开页面 (切后台/返回上一页) onPageHide() 页面隐藏 off('locationChange') 及时取消订阅 停止硬件位置更新,停止耗电 aboutToDisappear() 页面销毁释放资源

四、最小实践:一个标准的前台定位页面

接下来,我们通过一段最小实践代码,展示如何在 ArkUI 页面中规范地开始位置更新、接收经纬度,并在页面离开时及时停止定位。

1. 配置权限 (module.json5)

首先在 module.json5 中声明前台定位必需的权限:

"requestPermissions": [
  {
    "name": "ohos.permission.APPROXIMATELY_LOCATION",
    "reason": "$string:location_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.LOCATION",
    "reason": "$string:location_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

2. 页面代码实现 (ArkTS)

这段代码的核心在于:不使用匿名函数订阅,并在 onPageHide 中精准取消订阅。

import { geoLocationManager } from '@kit.LocationKit';
import { abilityAccessCtrl, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct LocationLifecyclePage {
  @State latitude: number = 0;
  @State longitude: number = 0;
  @State locationStatus: string = '未定位';

  // 核心注意点1:必须将回调函数提取为类的成员变量,以便后续精准 off
  private locationChangeCallback = (location: geoLocationManager.Location): void => {
    this.latitude = location.latitude;
    this.longitude = location.longitude;
    this.locationStatus = `定位更新中: ${new Date().toLocaleTimeString()}`;
    console.info(`[Location] 经纬度更新: ${this.latitude}, ${this.longitude}`);
  }

  // 页面显示时,申请权限并开始订阅
  onPageShow() {
    this.requestPermissionsAndStartLocation();
  }

  // 核心注意点2:页面隐藏时,必须取消订阅,防止后台耗电
  onPageHide() {
    this.stopLocationUpdate();
  }

  // 组件即将销毁时,作为兜底再次确保取消订阅
  aboutToDisappear() {
    this.stopLocationUpdate();
  }

  private requestPermissionsAndStartLocation() {
    let context = getContext(this) as common.UIAbilityContext;
    let atManager = abilityAccessCtrl.createAtManager();
    
    // 动态申请模糊位置和精确位置权限
    atManager.requestPermissionsFromUser(context, [
      'ohos.permission.APPROXIMATELY_LOCATION',
      'ohos.permission.LOCATION'
    ]).then((data) => {
      let authResults = data.authResults;
      // 0 代表已授权 (abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED)
      if (authResults.includes(0)) {
        this.startLocationUpdate();
      } else {
        this.locationStatus = '用户拒绝了定位权限';
      }
    }).catch((err: BusinessError) => {
      console.error(`[Location] 权限申请失败: ${err.code}, ${err.message}`);
    });
  }

  private startLocationUpdate() {
    let requestInfo: geoLocationManager.LocationRequest = {
      priority: geoLocationManager.LocationRequestPriority.ACCURACY, // 精度优先
      timeInterval: 2, // 每 2 秒更新一次
      distanceInterval: 0 // 距离间隔 0 米
    };

    try {
      // 开始订阅位置变化
      geoLocationManager.on('locationChange', requestInfo, this.locationChangeCallback);
      this.locationStatus = '已开启持续定位';
    } catch (err) {
      let error = err as BusinessError;
      console.error(`[Location] 订阅异常: ${error.code}, ${error.message}`);
    }
  }

  private stopLocationUpdate() {
    try {
      // 核心注意点3:传入具体的回调函数引用,只取消当前页面的订阅
      geoLocationManager.off('locationChange', this.locationChangeCallback);
      this.locationStatus = '已停止定位';
      console.info('[Location] 成功取消订阅');
    } catch (err) {
      let error = err as BusinessError;
      console.error(`[Location] 取消订阅异常: ${error.code}, ${error.message}`);
    }
  }

  build() {
    Column({ space: 20 }) {
      Text('Location 生命周期测试')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
      
      Text(`状态: ${this.locationStatus}`)
        .fontSize(16)
        .fontColor(Color.Gray)

      Text(`纬度: ${this.latitude}`)
        .fontSize(20)
      
      Text(`经度: ${this.longitude}`)
        .fontSize(20)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

五、几个关键点拆开看

1. 为什么绑定在 onPageShow/onPageHide 而不是 aboutToAppear/aboutToDisappear?

如果你的页面在应用的路由栈中被压入下层(例如从“地图页”跳转到了“详情页”),此时“地图页”的 aboutToDisappear 并不会触发,因为页面实例依然保留在内存中。如果将 off 写在 aboutToDisappear 里,跳转到详情页时定位依然在后台持续耗电。
绑定在 onPageHide 能够保证:只要用户看不见这个页面,定位就会立即停止。 当用户返回该页面触发 onPageShow 时,再重新发起订阅。这是性能与电量管理的最佳平衡点。

2. 致命错误:使用匿名函数进行订阅

很多开发者为了图方便,会这样写代码:

// 错误示范
geoLocationManager.on('locationChange', requestInfo, (location) => {
    this.latitude = location.latitude;
});

这种写法会导致在调用 off 时,由于无法提供对应的回调函数引用,开发者只能调用 geoLocationManager.off('locationChange')(不传回调参数)。
注意: 如果不传回调参数,系统会解绑该应用下所有对 locationChange 的订阅!如果你的应用有多个模块同时依赖定位,这种操作会导致其他模块的定位功能瞬间瘫痪。因此,必须提前定义一个具名函数或类成员函数引用,并在 off 时精准传入。

3. 异常权限处理:中途被撤销权限

假设用户在持续定位的过程中,通过系统设置强行收回了应用的定位权限。此时底层服务将不再推送位置,但应用层可能并不知道。为了增加健壮性,除了处理权限申请的异常,还可以在业务侧增加一个超时检测机制(例如几秒内没有回调则提示用户检查系统设置或网络状态)。

六、容易踩坑的地方

根据官方接口约束和实际开发场景,这里整理了几个极易引起误解的点:

  1. 模拟器与真机的差异:
    在 DevEco Studio 的模拟器(Emulator)中,持续定位可能无法像真机那样随真实环境变化产生回调,通常需要手动在模拟器扩展控制面板中注入 Mock 坐标。如果发现 locationChange 不触发,请先确认是在真机测试还是模拟器测试。
  2. 频率参数的优先级:
    在 LocationRequest 中有 timeInterval (时间间隔) 和 distanceInterval (距离间隔)。官方文档指出,系统底层会综合判断,并不保证绝对按照设定的毫秒数精准回调。如果系统判断位置未发生有效物理位移,或者信号较差,回调频率可能会低于开发者设定的频率。
  3. API 版本的变更:
    如果你参考了较老的代码,可能会看到 @ohos.geolocation 模块,这个模块已废弃。当前推荐使用的是 @kit.LocationKit 中的 @ohos.geoLocationManager。

七、实际项目中怎么排查页面耗电问题?

如果测试反馈应用有严重的后台耗电现象,建议按照以下顺序进行排查:

  1. 查引用:全局搜索 geoLocationManager.on('locationChange',找出所有发起订阅的地方。
  2. 查配对:检查每一个 on 是否都有对应、确切的 off 逻辑。
  3. 查生命周期:检查 off 是不是挂载了错误的生命周期(比如压栈时未触发销毁,导致 off 没执行)。
  4. 查参数:检查 off 是否传入了具体的回调引用,确保没有误杀其他模块的定位,也没有因为引用不一致导致“解绑失败”。

八、最后整理一下

  1. 只要业务不需要后台静默获取位置,坚决不要申请后台定位权限,这不仅增加了上架审核风险,也容易因为漏写逻辑导致严重耗电。
  2. 页面可见时订阅 (onPageShow),页面隐藏时解绑 (onPageHide) 是绝大多数位置服务模块的标准解法。
  3. 严格管理回调函数引用,杜绝在 on 接口中使用匿名箭头函数。

定位服务的接口虽然简单,但它牵涉到设备的底层硬件资源。作为开发者,我们需要养成“随用随取,用完即还”的良好习惯。如果你正在做包含复杂路由跳转的地图或位置打卡页面,不妨回头检查一下你的路由栈里,是不是还有几个被隐藏的页面正在偷偷向你要着经纬度数据呢?

参考资料

  1. 《LocationKit 开发指南:获取设备位置信息》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/location-current-location-V5

  2. 《LocationKit API 参考:@ohos.geoLocationManager (位置服务)》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/js-apis-geolocationmanager-V5

  3. 《AbilityKit 开发指南:向用户申请授权》
    华为开发者联盟
    链接:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/request-user-authorization-V5

如果觉得有帮助,别忘了点个赞+关注支持一下~
喜欢记得关注,别让好内容被埋没~

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐