鸿蒙三方库 | harmony-utils之LocationUtil位置获取与订阅详解

前言

位置服务是LBS应用的核心能力，如地图导航、附近搜索、运动追踪等。@pura/harmony-utils 的 LocationUtil 封装了位置获取和订阅方法，帮助开发者轻松实现定位功能。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、LocationUtil核心API

LocationUtil 提供了以下位置服务方法：

方法	说明	返回类型	使用场景
`getCurrentLocation()`	获取当前位置	Location	单次定位
`onLocationChange(callback)`	订阅位置变化	void	实时追踪
`offLocationChange(callback)`	取消位置订阅	void	释放资源
`isLocationEnabled()`	判断定位是否开启	boolean	状态检测

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
实时订阅：支持位置变化的实时订阅

1.2 定位方式对照

定位方式	精度	耗电	适用场景
GPS定位	高（5-10m）	高	导航、运动
网络定位	中（50-200m）	低	城市服务
融合定位	自适应	自适应	通用场景

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 获取当前位置

typescript 复制代码

import { LocationUtil } from '@pura/harmony-utils';

Button('获取当前位置')
  .width('100%')
  .onClick(async () => {
    try {
      let location = await LocationUtil.getCurrentLocation();
      this.result = `纬度: ${location.latitude}\n经度: ${location.longitude}\n精度: ${location.accuracy}m`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 订阅位置变化

typescript 复制代码

Button('订阅位置变化')
  .width('100%')
  .onClick(() => {
    try {
      LocationUtil.onLocationChange((location) => {
        this.result = `实时位置更新\n纬度: ${location.latitude}\n经度: ${location.longitude}`;
      });
      this.result = '位置订阅已开启 📍';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

import { LocationUtil } from '@pura/harmony-utils';

@Entry
@Component
struct LocationDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('检查定位状态').width('100%').onClick(() => {
        try {
          let enabled = LocationUtil.isLocationEnabled();
          this.result = `定位: ${enabled ? '已开启' : '未开启'}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('获取位置').width('100%').onClick(async () => {
        try {
          let loc = await LocationUtil.getCurrentLocation();
          this.result = `纬度: ${loc.latitude}\n经度: ${loc.longitude}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 位置变化追踪

typescript 复制代码

import { LocationUtil } from '@pura/harmony-utils';

class LocationTracker {
  private callback = (location: Location) => {
    this.onLocationUpdate(location);
  };

  start() {
    LocationUtil.onLocationChange(this.callback);
  }

  stop() {
    LocationUtil.offLocationChange(this.callback);
  }

  onLocationUpdate(location: Location) {
    console.log(`位置更新: ${location.latitude}, ${location.longitude}`);
  }
}

4.2 定位状态检查

typescript 复制代码

async function ensureLocationEnabled(): Promise<boolean> {
  if (!LocationUtil.isLocationEnabled()) {
    ToastUtil.showToast('请开启定位服务');
    WantUtil.startSettings();
    return false;
  }
  return true;
}

五、注意事项

权限要求：定位需要位置权限，需动态申请
隐私合规：获取位置前需告知用户并获取同意
耗电优化：不使用时及时取消位置订阅
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
室内定位：GPS在室内可能无法定位

六、常见问题

Q1: getCurrentLocation()一直等待？

可能是定位权限未授予，或定位服务未开启，检查权限和系统设置。

Q2: 位置精度很低？

室内环境GPS信号弱，精度较低。建议在室外开阔环境测试。

Q3: 订阅位置变化不触发？

检查定位权限和定位服务是否开启，以及回调函数是否正确设置。

Q4: 如何减少定位耗电？

降低定位频率，不使用时取消订阅，使用低精度模式。

总结

LocationUtil 的位置获取和订阅方法为LBS应用提供了核心定位能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据场景选择单次定位或持续追踪。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。