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

2301_79533122

9人浏览 · 2026-07-22 19:11:11

2301_79533122 · 2026-07-22 19:11:11 发布

前言

位置服务是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 安装依赖

ohpm install @pura/harmony-utils

2.2 获取当前位置

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 订阅位置变化

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

在这里插入图片描述

三、完整页面示例

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 位置变化追踪

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 定位状态检查

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