先问一个很扎心的问题:你写定位代码的时候,是不是直接调用 getCurrentLocation,拿到坐标就完事? 自测的时候站在窗边,GPS 信号好,定位又快又准;跑到室内、地下车库、写字楼深处,要么半天不回调、要么来回跳点,有时候还直接返回空坐标。用户打卡失败、选址跑偏,工单直接堆起来。

很多新手误区:定位就只有 GPS 一种来源,接口调用之后一定能拿到高精度、稳定的经纬度。 HarmonyOS 7 重构了定位子系统,对定位源优先级、权限校验、后台定位管控、回调频率做了更严格的约束。老版本很多自动兜底的逻辑被拿掉,弱网、GNSS 信号差的时候,不会悄悄切网络定位,需要我们业务层自己做降级策略。

为什么要学这套? 定位是打卡、附近服务、配送、导航的基础。单纯追求高精度不够,必须分清定位源的差异,做一套分级策略:室外优先 GNSS 高精度;室内 GNSS 失效,切换网络定位;信号极差的时候给用户友好提示,而不是一直转圈加载。同时鸿蒙 7 对后台定位、持续定位的权限审核更严,一不小心就会被应用市场驳回。

先分清鸿蒙里两种核心定位源,一句话看懂差别:

  • GNSS 定位(GPS / 北斗):卫星定位,精度高(米级),但是依赖开阔天空,室内、密闭环境几乎失效,耗电更高
  • 网络定位(基站 + Wi‑Fi):依靠周边 Wi-Fi、基站信息,精度几十米到几百米,室内可用,响应快、耗电低,但是精度不稳定

吐槽一句:很多同学为了省事,直接设置定位请求模式为高精度模式。在密闭房间里,GNSS 搜不到卫星,接口会一直等待卫星信号,几十秒超时才返回失败,用户以为 App 卡死。鸿蒙 7 不会自动帮你切换定位源!

下面是可直接运行的 ArkTS 示例,包含:单次定位、持续定位、定位源降级、防抖过滤抖动坐标、资源释放。

import { location } from '@kit.LocationKit';

// 定位结果结构
interface LocResult {
  lon: number
  lat: number
  accuracy: number
  sourceType: location.LocationSourceType
  time: number
}

@Entry
@Component
struct LocationDemoPage {
  @State locTip: string = "等待定位..."
  @State locInfo: LocResult | null = null
  private locationListenerId: number | null = null

  aboutToDisappear() {
    // 重点:页面销毁,一定要停止持续定位,不然持续耗电、内存泄漏
    if (this.locationListenerId !== null) {
      location.onceOff(this.locationListenerId).catch(err => console.error('停止定位失败', err))
      this.locationListenerId = null
    }
  }

  // 1. 单次定位,带降级策略:先尝试高精度,超时自动切换网络定位
  async function getSingleLocation() {
    this.locTip = "定位中,请稍候..."
    // 定位请求配置
    let requestOption: location.LocationRequest = {
      priority: location.LocationRequestPriority.FIRST_FIX,
      scenario: location.LocationScenario.SCENARIO_NAVIGATION,
      maxAccuracy: 100,
      timeoutMs: 8000 // 8秒超时,GNSS拿不到结果就降级
    }
    try {
      const loc = await location.getCurrentLocation(requestOption)
      this.handleLocData(loc)
    } catch (err) {
      console.warn('高精度定位超时/失败,降级使用网络定位', err)
      // 降级:强制使用网络定位
      requestOption.priority = location.LocationRequestPriority.LOW_POWER
      requestOption.timeoutMs = 5000
      try {
        const loc = await location.getCurrentLocation(requestOption)
        this.handleLocData(loc)
      } catch (err2) {
        this.locTip = "定位失败,无可用定位源,请检查定位开关与权限"
        console.error('网络定位也失败', err2)
      }
    }
  }

  // 2. 开启持续定位(适合轨迹、实时位置上报)
  function startContinuousLoc() {
    if (this.locationListenerId !== null) return
    const requestOption: location.LocationRequest = {
      priority: location.LocationRequestPriority.FIRST_FIX,
      intervalMs: 2000, // 2秒回调一次,不要设置太短,耗电爆炸
      scenario: location.LocationScenario.SCENARIO_TRACK
    }
    this.locationListenerId = location.on('locationChange', requestOption, (loc) => {
      // 防抖过滤:精度太差的点位直接丢弃
      if (loc.accuracy > 200) {
        console.info('点位精度太差,丢弃')
        return
      }
      this.handleLocData(loc)
    })
  }

  // 统一处理定位数据
  private handleLocData(loc: location.Location) {
    const sourceName = loc.sourceType === location.LocationSourceType.GNSS ? "GNSS卫星" : "网络定位"
    this.locInfo = {
      lon: loc.longitude,
      lat: loc.latitude,
      accuracy: loc.accuracy,
      sourceType: loc.sourceType,
      time: loc.timeStamp
    }
    this.locTip = `定位成功,来源:${sourceName},精度:${loc.accuracy.toFixed(2)}米`
  }

  build() {
    Column() {
      Text(this.locTip).fontSize(16).margin({bottom: 16})
      if (this.locInfo) {
        Text(`经度:${this.locInfo.lon.toFixed(6)}`)
        Text(`纬度:${this.locInfo.lat.toFixed(6)}`)
      }
      Button("单次获取位置")
        .onClick(()=> this.getSingleLocation())
        .margin({bottom:12})
      Button("开启持续定位")
        .onClick(()=> this.startContinuousLoc())
        .margin({bottom:12})
      Button("关闭持续定位")
        .onClick(async ()=>{
          if(this.locationListenerId) {
            await location.onceOff(this.locationListenerId)
            this.locationListenerId = null
            this.locTip = "已关闭持续定位"
          }
        })
    }.width('100%').padding(24)
  }
}

关键语句拆解

  1. priority 优先级: FIRST_FIX:优先快速拿到第一 fixes,适合单次打卡;LOW_POWER 低功耗模式,优先网络定位;
  2. timeoutMs 超时时间:鸿蒙 7 这里超时是硬限制。如果 GNSS 搜星困难,超时之后业务代码主动降级是唯一可靠方案;系统不会自动切源;
  3. onceOff(listenerId):持续定位必须保存 listenerId,不用的时候调用 onceOff 注销。如果忘记注销,页面退出之后定位服务还在后台跑,耗电严重,审核容易判定为违规后台行为;
  4. 精度过滤 loc.accuracy:网络定位偶尔会飘出几百米的坏点,直接丢弃,避免坐标抖动。

HarmonyOS 7 高频踩坑清单

  1. ❌ 误区:一直使用高精度模式,不做降级 现象:室内场景一直加载、长时间超时,用户体验很差。 ✅ 方案:设置合理超时,捕获异常之后,自动切换低功耗网络定位,并且在 UI 上告诉用户当前是网络定位,精度较低。
  2. ❌ 持续定位 intervalMs 设置过小(500ms、1000ms) 现象:功耗飙升,手机发热,应用市场审核判定滥用定位。 ✅ 规范:轨迹上报最低建议 2000ms 以上,非导航场景不要高频回调。
  3. ❌ 权限只申请 ohos.permission.LOCATION,忽略后台定位权限 如果 App 退到后台还需要定位,鸿蒙 7 必须额外申请 ohos.permission.LOCATION_IN_BACKGROUND,并且在 module.json5 配置后台定位的 usedScene。缺少这个权限,切后台之后定位回调直接停止。
  4. ❌ 不处理定位开关关闭的场景 用户系统设置直接关掉定位总开关,调用 getCurrentLocation 直接抛出异常。一定要捕获异常,提示用户去系统打开定位服务。
  5. ❌ 直接使用原始定位坐标,不配合坐标系转换 定位组件输出是 WGS84,如果要丢进之前讲的 MapComponent,记得转 GCJ02,不然点位漂移!
  6. ❌ 持续定位监听不注销,listenerId 丢失 listenerId 一旦丢失,你再也无法关闭定位,只能重启 App。一定要用变量保存,页面销毁强制注销。
  7. ❌ 批量上报点位,不做防抖、去抖动 走路的时候 GNSS 定位会小幅来回跳动,如果直接把每一个回调的坐标都上传,轨迹线锯齿严重。可以加简单逻辑:相邻两点距离小于 5 米,就丢弃新点位。

项目复盘总结

之前做一个外勤打卡项目,一开始定位代码全部写死高精度 GNSS 模式。很多外勤人员在商场、地下室打卡,经常定位超时失败。 在鸿蒙旧版本,部分机型会悄悄切网络定位兜底;升级鸿蒙 7 之后,系统不再自动兜底,大量打卡失败反馈。 后面加上超时捕获、自动降级网络定位、精度过滤坏点,同时 UI 区分卫星定位 / 网络定位,用户知道当前定位精度,工单数量直接下降一大半。

开发规范:

  • 区分单次定位和持续定位;持续定位必须保存 listenerId,用完注销;
  • 高精度模式设置超时,捕获失败自动降级低功耗网络定位;
  • 对返回坐标做精度过滤,丢弃精度过大的飘点;
  • 后台持续定位,必须声明后台定位权限,严格控制回调间隔。
Logo

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

更多推荐