在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀

前言

大多数开发者对定位权限的第一印象是:用户要么允许,要么拒绝。但实际上,HarmonyOS 在前台定位场景下把权限拆成了两个:ohos.permission.LOCATION(精准位置)和 ohos.permission.APPROXIMATELY_LOCATION(模糊位置)。这两个权限不是非此即彼的关系,它们可以单独授予,也可以组合授予,应用拿到的结果因此有四种情况,而不是两种。

如果代码只判断"有没有权限",就很容易在用户只授予了模糊位置时拿不到预期精度的坐标,甚至直接报错,问题出在哪里却不明显。这篇文章就专门把这件事说清楚。

一、这两个权限到底有什么区别

在 HarmonyOS 中,精准位置和模糊位置分别对应两个独立的 user_grant 权限:

权限名说明精度范围
ohos.permission.APPROXIMATELY_LOCATION模糊位置,API 9 起支持误差约 5 千米
ohos.permission.LOCATION精准位置,API 9 起支持,必须同时持有 APPROXIMATELY_LOCATIONGPS/网络精准定位

这里有一条容易被忽视的规则:申请 ohos.permission.LOCATION 时,必须同时申请 ohos.permission.APPROXIMATELY_LOCATION,否则精准位置权限无法正常授权。 这不是建议,是系统层面的强制依赖关系。

用户在系统弹框中看到的选项通常是:

  • 仅允许模糊位置
  • 允许精准位置(此时模糊位置也同时授权)
  • 拒绝

所以从应用侧来看,前台定位的授权结果有以下几种组合:

APPROXIMATELY_LOCATIONLOCATION实际能获取到的位置精度
GRANTEDGRANTED精准位置
GRANTEDDENIED仅模糊位置
DENIEDDENIED无法获取位置

第二种情况——有模糊无精准——才是最容易被忽略的。此时 geoLocationManager 的部分接口仍然可以调用,但返回的坐标精度很低,如果业务逻辑依赖精确坐标(如导航、LBS 签到),会静默地产生错误结果。

二、官方权限声明要求

在 module.json5 中,两个权限都需要声明。如果只写 LOCATION、漏掉 APPROXIMATELY_LOCATION,运行时权限申请会直接失败。

// module.json5 片段
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

几个配置细节:

  • when 填 "inuse" 表示仅前台使用,本文只讨论这个场景。后台定位需要额外申请 ohos.permission.LOCATION_IN_BACKGROUND,配置方式不同,不在本文范围内。
  • usedScene.abilities 填写实际调用定位的 Ability 名称,不要写通配符。
  • 两条权限都必须声明,缺一不可。

三、搭一个最小实践场景

目标:应用启动后,判断当前定位权限状态,分三种情况处理:

  1. 已有精准权限 → 直接获取精准坐标;
  2. 仅有模糊权限 → 告知用户精度不足,给出升级引导;
  3. 两者都没有 → 发起权限申请弹窗。

需要用到:

  • @kit.AbilityKit 中的 abilityAccessCtrl,用于查权限状态;
  • @ohos.abilityAccessCtrl 的 GrantStatus 枚举;
  • @kit.LocationKit 中的 geoLocationManager,用于获取位置;
  • UIAbility 的 onWindowStageCreate 生命周期作为入口。

四、核心代码实现

4.1 权限状态检查

这段代码的目标是在调用定位之前,先判断精准权限和模糊权限各自处于什么状态,不要把两个权限混在一起只判断一次。

// PermissionChecker.ets
import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit';

export enum LocationPermLevel {
  PRECISE,       // 精准位置
  APPROXIMATE,   // 仅模糊位置
  NONE           // 未授权
}

export async function checkLocationPermLevel(): Promise<LocationPermLevel> {
  const atManager = abilityAccessCtrl.createAtManager();

  let tokenId: number = 0;
  try {
    const bundleInfo = await bundleManager.getBundleInfoForSelf(
      bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
    );
    tokenId = bundleInfo.appInfo.accessTokenId;
  } catch (err) {
    return LocationPermLevel.NONE;
  }

  const preciseStatus = await atManager.checkAccessToken(
    tokenId,
    'ohos.permission.LOCATION' as Permissions
  );
  const approxStatus = await atManager.checkAccessToken(
    tokenId,
    'ohos.permission.APPROXIMATELY_LOCATION' as Permissions
  );

  if (preciseStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
    return LocationPermLevel.PRECISE;
  } else if (approxStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
    return LocationPermLevel.APPROXIMATE;
  }
  return LocationPermLevel.NONE;
}

真正需要关注的地方是:checkAccessToken 需要应用自身的 accessTokenId,通过 bundleManager.getBundleInfoForSelf 获取,不需要任何系统权限,普通应用可以直接调用。

4.2 权限申请

申请时必须把两个权限一起传入 requestPermissionsFromUser,由系统统一弹框给用户选择。

// 在 UIAbility 中调用
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';

async function requestLocationPermissions(context: common.UIAbilityContext): Promise<void> {
  const atManager = abilityAccessCtrl.createAtManager();
  const permissions: Permissions[] = [
    'ohos.permission.APPROXIMATELY_LOCATION',
    'ohos.permission.LOCATION'
  ];

  const result = await atManager.requestPermissionsFromUser(context, permissions);

  // result.authResults 按 permissions 数组顺序对应
  const approxGranted = result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
  const preciseGranted = result.authResults[1] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;

  if (preciseGranted) {
    // 用户选择了精准位置
    console.info('已获取精准位置权限');
  } else if (approxGranted) {
    // 用户选择了仅模糊位置
    console.info('仅获取模糊位置权限,坐标精度约 5km');
  } else {
    // 用户拒绝
    console.info('位置权限被拒绝');
  }
}

result.authResults 的顺序和传入 permissions 数组的顺序一一对应,所以传入顺序要固定,不要在不同地方用不同顺序传入同一批权限,否则下标判断会乱。

4.3 在页面中组合使用

// LocationPage.ets
import { checkLocationPermLevel, LocationPermLevel } from './PermissionChecker';
import { geoLocationManager } from '@kit.LocationKit';
import { common } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';

@Entry
@Component
struct LocationPage {
  @State locationText: string = '点击按钮获取位置';
  @State permLevel: LocationPermLevel = LocationPermLevel.NONE;

  private context = getContext(this) as common.UIAbilityContext;

  async aboutToAppear(): Promise<void> {
    this.permLevel = await checkLocationPermLevel();
  }

  async handleGetLocation(): Promise<void> {
    if (this.permLevel === LocationPermLevel.NONE) {
      // 跳转系统设置或重新申请
      promptAction.showToast({ message: '请先授予位置权限' });
      return;
    }

    const request: geoLocationManager.CurrentLocationRequest = {
      // 精准权限时优先使用高精度优先策略
      priority: this.permLevel === LocationPermLevel.PRECISE
        ? geoLocationManager.LocationRequestPriority.ACCURACY
        : geoLocationManager.LocationRequestPriority.LOW_POWER,
      scenario: geoLocationManager.LocationRequestScenario.UNSET,
      timeoutMs: 10000
    };

    try {
      const location = await geoLocationManager.getCurrentLocation(request);
      this.locationText =
        `纬度:${location.latitude.toFixed(6)}\n` +
        `经度:${location.longitude.toFixed(6)}\n` +
        `精度:${location.accuracy} 米\n` +
        `权限级别:${this.permLevel === LocationPermLevel.PRECISE ? '精准' : '模糊'}`;
    } catch (err) {
      this.locationText = `获取失败:${JSON.stringify(err)}`;
    }
  }

  build() {
    Column({ space: 16 }) {
      if (this.permLevel === LocationPermLevel.APPROXIMATE) {
        Text('当前仅授予模糊位置权限,坐标精度约 5 千米。如需精准定位,请前往系统设置修改权限。')
          .fontSize(14)
          .fontColor('#FF6B00')
          .padding(12)
      }

      Text(this.locationText)
        .fontSize(16)
        .padding(16)

      Button('获取当前位置')
        .onClick(() => {
          this.handleGetLocation();
        })
    }
    .width('100%')
    .padding(24)
  }
}

这里选择把 permLevel 存到组件状态里,而不是每次点击都重新检查,原因是权限状态变化只发生在用户主动操作系统设置后。如果需要感知用户从设置回来后的权限变化,可以在 onForeground 生命周期中重新调用 checkLocationPermLevel() 刷新状态。

五、几个关键点拆开看

5.1 LOCATION 依赖 APPROXIMATELY_LOCATION,这是系统强制的

官方文档明确说明,申请 ohos.permission.LOCATION 时必须同时申请 ohos.permission.APPROXIMATELY_LOCATION。只申请前者会导致权限申请弹框无法正常弹出,或者权限始终处于 DENIED 状态。很多初次接触 HarmonyOS 定位权限的开发者会单独申请 LOCATION,这是最常见的失误。

5.2 requestPermissionsFromUser 的弹框由系统控制,开发者无法自定义

系统会根据传入的权限列表以及用户历史授权状态,决定弹框的展示形式。如果用户此前已经永久拒绝了位置权限,再次调用 requestPermissionsFromUser 时系统不会再次弹框,authResults 会直接返回 DENIED。这种情况下,引导用户去系统设置页手动开启是唯一的路径。

可以通过 context.startAbility 跳转到系统设置的应用权限页,具体 want 参数可参考官方的"应用隐私保护指导"相关文档。本文不展开这个分支,但实际项目里需要处理。

5.3 模糊权限下 accuracy 字段的含义

当用户只授予了模糊位置权限时,geoLocationManager.getCurrentLocation 返回的 location.accuracy 并不能简单地用于判断定位是否"足够精准"——该字段在模糊位置模式下的实际语义与精准定位场景不同,不要直接用这个数值做业务判断。判断精度是否满足业务需要,应该在获取位置之前先判断权限级别,而不是获取位置之后再看 accuracy。

5.4 checkAccessToken 只是快照,不是监听

checkAccessToken 返回的是当前时刻的权限状态快照。如果用户在系统设置里动态修改了权限,应用内缓存的状态不会自动更新。建议在每次需要调用定位功能之前(而不只是在页面初始化时),都重新检查一次权限状态。

5.5 CurrentLocationRequest 的 priority 和 scenario 组合

LocationRequestPriority 和 LocationRequestScenario 是两个独立字段,官方文档说明两者同时设置时以 scenario 为准。如果只设置 priority 而把 scenario 设为 UNSET,则以 priority 生效。上面代码选择的就是后者,行为比较可预测。

六、容易踩坑的地方

module.json5 漏写 APPROXIMATELY_LOCATION

这是最高频的问题。LOCATION 单独声明时,运行时权限申请在某些设备或系统版本上会静默失败,也有可能弹框出来但用户选择精准位置后 authResults 仍返回 DENIED。先检查 module.json5 里两个权限是否都有声明。

requestPermissionsFromUser 必须在 UIAbility 的上下文中调用

如果把权限申请逻辑封装在一个普通的工具类里,要确保传入的 context 是 UIAbilityContext,而不是 ApplicationContext 或其他上下文类型。用错 context 类型会导致弹框无法弹出。

忘记处理"仅模糊位置"这个中间态

代码只写了"有权限"和"无权限"两个分支,而漏掉了"仅模糊权限"这个情况,是最容易产生静默错误的地方。用户感觉授权了,应用也没有报错,但坐标精度始终在几千米级别。一定要把三种状态都处理到位。

权限弹框不会重复弹出

在 HarmonyOS 中,如果用户选择了"拒绝且不再询问",后续调用 requestPermissionsFromUser 不会再弹框。如果应用没有处理这个情况,用户会看到一个没有任何反应的界面,体验很差。这里需要检查 authResults 并给出跳转设置的引导。

七、实际项目中怎么排查

如果运行时位置功能表现异常,可以按下面顺序逐步排查:

  1. 先看 module.json5:确认 APPROXIMATELY_LOCATION 和 LOCATION 都已声明,when 为 "inuse",abilities 填写正确。

  2. 看 checkAccessToken 的返回值:把两个权限的状态都打出来,而不只是 LOCATION 一个。确认是精准授权、仅模糊授权,还是全部拒绝。

  3. 看 requestPermissionsFromUser 的 authResults:按数组下标核对每个权限的授权结果,注意顺序要和 permissions 入参一致。

  4. 看系统设置里的权限状态:有时候代码看起来没问题,但用户设备上该应用的权限曾经被永久拒绝过。直接去"设置 → 隐私 → 权限管理"里看当前应用的位置权限状态。

  5. 看 geoLocationManager 是否 enabled:调用 geoLocationManager.isLocationEnabled() 确认设备定位总开关是否开启。权限已经授予但定位总开关关闭时,getCurrentLocation 会抛出错误码,需要引导用户开启系统定位。

  6. 最后看业务逻辑:确认上面都没问题之后,再排查坐标使用逻辑是否混淆了精准/模糊两种精度来源。

开发经验总结

  • LOCATION 和 APPROXIMATELY_LOCATION 是两个独立的 user_grant 权限,二者需要同时声明并同时申请,缺少 APPROXIMATELY_LOCATION 时精准定位权限无法正常授予。
  • 前台定位权限的授权结果有三种有意义的状态:精准、仅模糊、全部拒绝,三种都要在代码里有明确处理,不能只区分"有"和"没有"。
  • 权限状态检查是快照而非监听,建议在每次调用定位前重新检查,而不是只在页面加载时检查一次。
  • 用户永久拒绝后系统不再弹框,需要在代码里判断这个情况并给出跳转设置的引导,否则用户体验会出问题。

如果你的应用目前只判断了 LOCATION 一个权限,可以查一下在"仅模糊位置"状态下,业务逻辑里所有依赖坐标精度的地方是否都有对应的降级处理——这类问题通常不报错,但坐标偏差在实际设备上会非常明显。

❤️ 如果本文帮到了你…

  • 请点个赞,让我知道你还在坚持阅读技术长文!
  • 请收藏本文,因为你以后一定还会用上!
  • 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐