在这里插入图片描述

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

前言

声明了权限,不代表拿到了权限。

这个误区在实际开发中很常见:module.json5 里加上了 requestPermissions,代码跑起来却还是报 Permission denied;或者权限弹窗该出现的时候没出现,不该出现的时候一直弹。根本原因通常不是写错了什么,而是没搞清楚 HarmonyOS 权限系统里,"声明"和"授权"是两件性质不同的事。

一、为什么光"声明"不够

很多开发者把 HarmonyOS 权限配置理解成一件事:往 module.json5 里写 requestPermissions。

这种理解只对了一半。

requestPermissions 的作用是向系统登记这个应用打算使用某项权限,相当于一份意向声明,系统在安装或运行时会根据这份声明去做后续处理。但后续怎么处理,完全取决于这条权限本身属于哪种授权类型。

HarmonyOS 官方文档把权限按授权方式分成两个维度来看:

第一个维度:授权主体是谁

  • system_grant(系统授权):系统在安装应用时自动完成授权,不需要用户操作
  • user_grant(用户授权):必须在运行时主动弹窗请求,由用户决定是否授予

第二个维度:权限的开放程度

  • 普通权限(normal):满足基本条件即可使用
  • 受限权限(restricted):受到额外限制,普通应用在未通过审批前不能使用,需要通过 ACL(Access Control List)机制申请开放

四种情况的组合,决定了某条权限在实际运行时能不能用、如何才能用。

二、把四种情况拆开看

2.1 system_grant:声明即生效

ohos.permission.INTERNET 是一个典型例子。这条权限的授权类型是 system_grant,应用在 module.json5 里声明之后,系统会在安装时自动授予,代码中不需要再主动请求。

这类权限的特征:操作范围有限、对用户隐私影响较低,系统可以直接决策。

开发时只需要这一步:

// module.json5
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

安装后即可直接使用,不需要调用任何运行时申请接口。

2.2 user_grant:声明 + 运行时请求,缺一不可

ohos.permission.CAMERA、ohos.permission.LOCATION、ohos.permission.READ_CONTACTS 等属于 user_grant。

这类权限影响到用户的隐私和敏感数据,系统不会自动授予,必须在运行时弹窗让用户确认。

只在 module.json5 里声明但不调用运行时申请接口,权限永远拿不到。

完整流程分三步:

第一步:module.json5 中声明

// module.json5
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:reason_camera",
        "usedScene": {
          "abilities": [
            "EntryAbility"
          ],
          "when": "inuse"
        }
      }
    ]
  }
}

reason 和 usedScene 对于 user_grant 权限是必填项,AGC 审核也会检查这两个字段是否配置合理。

第二步:运行时检查当前授权状态

在真正使用权限之前,先确认用户是否已经授过权:

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

async function checkPermission(permission: Permissions): Promise<boolean> {
  let atManager = abilityAccessCtrl.createAtManager();
  let grantStatus: abilityAccessCtrl.GrantStatus;

  // 获取当前应用的 tokenID
  let tokenId: number = 0;
  try {
    let bundleInfo = await bundleManager.getBundleInfoForSelf(
      bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
    );
    tokenId = bundleInfo.appInfo.accessTokenId;
  } catch (err) {
    return false;
  }

  // 检查授权状态
  try {
    grantStatus = await atManager.checkAccessToken(tokenId, permission);
  } catch (err) {
    return false;
  }

  return grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
}

第三步:未授权时主动请求

import { common, abilityAccessCtrl, Permissions } from '@kit.AbilityKit';

async function requestCameraPermission(context: common.UIAbilityContext): Promise<void> {
  const permissions: Array<Permissions> = ['ohos.permission.CAMERA'];
  let atManager = abilityAccessCtrl.createAtManager();

  try {
    let result = await atManager.requestPermissionsFromUser(context, permissions);
    // result.authResults[0] === 0 表示用户授权成功
    if (result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
      // 授权成功,可以继续后续操作
    } else {
      // 用户拒绝,需要引导用户去设置页面手动开启
    }
  } catch (err) {
    // 处理异常
  }
}

requestPermissionsFromUser 需要传入 UIAbilityContext,这个 context 要从 UIAbility 的生命周期中获取,不能在非 UI 上下文里直接调用。

2.3 受限权限(restricted)与 ACL 机制

受限权限是 HarmonyOS 权限体系里容易被忽略的一层。

某些高敏感权限(例如涉及精确位置、通讯录写入、通话记录等),除了需要在 module.json5 里声明并通过运行时请求外,还需要应用具备相应的证书级别,即通过 AppGallery Connect 的 ACL 权限申请审批,才能在签名证书中获得对应的 ACL 授权。

如果没有通过 ACL 申请,即使声明了、也请求了,系统也不会授权。

官方文档对受限权限有明确说明:这类权限在权限定义文件中的 availableLevel 字段不是 normal,应用需要满足特定条件才能使用。

开发阶段用调试证书时,通常不会踩到这个限制;但用正式签名证书发布的应用,如果权限声明了却一直拿不到,就需要检查是否属于受限权限、是否完成了 ACL 申请。

ACL 相关配置会在应用签名证书中体现,build-profile.json5 中也需要正确配置签名信息,确保构建时使用的是携带 ACL 授权的证书。

三、一个最小验证场景

下面是一个最小化的 UIAbility 示例,展示如何在 onCreate 之后的合适时机完成权限检查和请求,结构本身比业务逻辑更重要:

import { UIAbility, abilityAccessCtrl, bundleManager, Want, AbilityConstant, Permissions, common } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  private windowStage: window.WindowStage | null = null;

  onWindowStageCreate(windowStage: window.WindowStage): void {
    this.windowStage = windowStage;
    windowStage.loadContent('pages/Index');

    // 在页面加载后执行权限检查,此时可以获取到正确的 context
    this.checkAndRequestPermissions();
  }

  private async checkAndRequestPermissions(): Promise<void> {
    const permission: Permissions = 'ohos.permission.CAMERA';
    const atManager = abilityAccessCtrl.createAtManager();

    // 先检查当前授权状态
    let bundleInfo = await bundleManager.getBundleInfoForSelf(
      bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
    );
    let tokenId = bundleInfo.appInfo.accessTokenId;
    let grantStatus = await atManager.checkAccessToken(tokenId, permission);

    if (grantStatus !== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
      // 未授权时发起请求
      let result = await atManager.requestPermissionsFromUser(
        this.context as common.UIAbilityContext,
        [permission]
      );
      console.info('权限请求结果:' + JSON.stringify(result.authResults));
    }
  }
}

这段代码的核心逻辑:先查再请求,而不是每次启动直接弹窗。对用户来说体验更自然,对开发者来说也便于根据状态分支处理。

四、几个关键点拆开说

4.1 checkAccessToken 和 requestPermissionsFromUser 不能混用职责

checkAccessToken 只负责查状态,不会触发弹窗;requestPermissionsFromUser 才会触发系统弹窗。如果把查询和请求的逻辑混在一起处理,很容易出现"权限明明没授,却没有弹窗"的情况——因为根本没调到请求接口。

4.2 用户拒绝后再次请求的行为

用户在弹窗里点了"拒绝"之后,如果应用直接再次调用 requestPermissionsFromUser,系统在某些情况下会直接返回拒绝,不再弹窗。官方建议:检测到权限被拒绝后,应引导用户去应用设置页面手动开启,而不是反复弹窗。

4.3 reason 字段不只是审核用的

reason 字段会在系统权限弹窗中向用户展示,解释申请该权限的原因。如果这里写的说明和应用实际用途差距很大,不仅影响用户的授权意愿,审核阶段也可能被打回。

4.4 when 字段的选项影响权限使用范围

usedScene.when 有两个值:inuse(仅在前台使用)和 always(前后台均可使用)。如果应用需要在后台持续获取位置,却只申请了 inuse,后台运行时权限会被系统收回。

五、容易踩坑的地方

① 把 system_grant 的权限走了 user_grant 的流程

对 ohos.permission.INTERNET 这类 system_grant 权限调用 requestPermissionsFromUser,系统不会报错,但弹窗不会出现,authResults 会直接返回已授权——因为系统安装时就给了。问题不在这里,在于开发者误以为这个弹窗就是用户授权的标准流程,后来换成 user_grant 权限时忘了处理用户拒绝分支。

② 签名证书没有携带对应的 ACL 授权

调试阶段用 debug 证书通常不受 ACL 限制,但换成发布证书后受限权限就会一直拿不到。这类问题的特征是:本地 debug 没问题,发布版本一直失败。排查时要检查签名证书的权限配置,而不是代码逻辑。

③ 在非 UIAbility context 里调用 requestPermissionsFromUser

requestPermissionsFromUser 要求传入的 context 具有展示系统弹窗的能力,在 ServiceExtensionAbility 或者工具类里直接调用通常会失败或行为异常。这个接口需要在 UIAbility 中使用。

④ 只在第一次启动时检查权限

用户可以随时在系统设置里撤销权限,应用运行期间权限状态可能发生变化。建议在每次真正使用该权限的功能之前(比如打开相机前、获取位置前),都先做一次 checkAccessToken 校验,而不是只在启动时检查一次。

六、排查权限问题的顺序

遇到 Permission denied 或权限弹窗不出现时,可以按这个顺序排查:

  1. 确认 module.json5 里有没有声明
    连声明都没有,系统会直接拒绝,不走后续流程

  2. 确认这条权限属于 system_grant 还是 user_grant
    可以在 HarmonyOS 官方权限列表文档中查到每条权限的 grantMode

  3. 如果是 user_grant,确认是否调用了 requestPermissionsFromUser
    很多问题就出在这一步缺失

  4. 确认是否属于受限权限
    如果权限文档中标注了受限,检查是否完成了 AGC 侧的 ACL 申请

  5. 确认签名证书是否携带了对应权限的 ACL 授权
    特别是从 debug 切换到 release 签名之后

  6. 确认 requestPermissionsFromUser 的 context 类型是否正确
    传入的必须是 UIAbilityContext

  7. 确认 reason 和 usedScene 字段是否正确填写
    user_grant 权限缺少这两个字段,弹窗可能无法正常触发

开发经验总结

  • HarmonyOS 权限系统的核心分层是:声明(module.json5)→ 授权类型(system_grant / user_grant)→ 是否受限(普通 / ACL)。三个维度都要对,权限才能真正可用。

  • system_grant 声明即生效,不需要运行时请求;user_grant 声明之后还需要主动调用 requestPermissionsFromUser,两步缺一不可。

  • 受限权限在没有通过 ACL 审批前,无论代码怎么写,系统都不会授权,这是证书级别的限制,不是代码层面能绕过的。

  • 权限状态在应用运行期间可以被用户撤销,建议在每次使用敏感功能前都检查一次当前状态,而不是只在启动时检查。

  • debug 证书和 release 证书在受限权限行为上可能表现不同,上架前务必用正式签名证书在真机上完整验证一遍权限流程。


如果你正在接入 user_grant 权限,可以重点观察一下自己的代码里有没有处理用户拒绝后的分支——这个分支缺失的情况很普遍,而且在测试阶段因为习惯点"允许",往往不容易发现。

❤️ 如果本文帮到了你…

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

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

更多推荐