当前位置：首页 > news >正文

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

news 2026/7/23 4:14:19

前言

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

ohpminstall@pura/harmony-utils

2.2 获取当前位置

import{LocationUtil}from'@pura/harmony-utils';Button('获取当前位置').width('100%').onClick(async()=>{try{letlocation=awaitLocationUtil.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@Componentstruct LocationDemo{@Stateresult:string='';build(){Column({space:12}){Button('检查定位状态').width('100%').onClick(()=>{try{letenabled=LocationUtil.isLocationEnabled();this.result=`定位:${enabled?'已开启':'未开启'}`;}catch(e){this.result='异常: '+e;}});Button('获取位置').width('100%').onClick(async()=>{try{letloc=awaitLocationUtil.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';classLocationTracker{privatecallback=(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 定位状态检查

asyncfunctionensureLocationEnabled():Promise<boolean>{if(!LocationUtil.isLocationEnabled()){ToastUtil.showToast('请开启定位服务');WantUtil.startSettings();returnfalse;}returntrue;}