目录

前言：

一、权限体系核心架构

1.2 权限分类：系统授权 vs 用户授权

1.3 权限分级与版本适配

二、权限开发技术实现指南

2.1 基础配置：module.json5声明

2.2 权限申请核心API（JS/TS示例）

2.2.1 创建权限管理实例

2.2.2 拉起授权弹窗（首次申请）

2.2.3 处理用户拒绝后的二次申请

2.3 系统授权 vs 用户授权的代码差异

三、最佳实践与避坑指南

3.1 权限粒度最小化

3.2 拒绝后的优雅降级

3.3 版本兼容性适配

四、完整权限申请流程图

五、常见问题解答

Q1：为什么用户授权的权限需要声明reason和usedScene？

Q2：系统授权的权限是否100%安全？

前言：

        在鸿蒙操作系统（HarmonyOS）中，权限可以分为两大类：系统授权（system_grant）和用户授权（user_grant）。这两类权限的管理方式和申请流程有所不同。

        系统授权（system_grant）系统授权是指应用在安装时，系统自动将相应的权限授予应用，不需要用户在应用运行时单独同意。这类权限通常涉及应用的基本功能。

        用户授权（user_grant） 用户授权则需要在应用运行时通过弹窗等方式明确获得用户的同意。这类权限通常涉及用户的隐私数据或高级功能，

        每种权限都有其特定的权限级别和授权方式，开发者在使用这些权限时，应当明确告知用户权限的用途，并合理使用用户的数据。

一、权限体系核心架构

HarmonyOS权限管理遵循​“最小必要”原则，将权限分为两大核心类型，通过差异化机制平衡安全性与用户体验：

1.2 权限分类：系统授权 vs 用户授权

​分类​	​核心特征​	​适用场景​	​配置方式​	​授权流程​	​典型权限示例​
​系统授权​	自动分配、无用户感知	非敏感功能（网络、存储读写）	仅需在 module.json5 声明权限名称	应用启动时自动授予	ohos.permission.INTERNET
​用户授权​	需用户显式确认、敏感操作	涉及隐私或关键功能（相机、麦克风）	需在 module.json5 额外声明 reason/usedScene	需通过弹窗/设置页主动申请	ohos.permission.CAMERA

1.3 权限分级与版本适配

• ​权限级别​：
  • normal（普通权限）：系统自动授予或低风险用户授权（如INTERNET、MICROPHONE）
  • dangerous（高危权限）：必须用户显式授权（如CONTACTS、LOCATION）
• ​起始版本​：标注权限在哪个系统版本引入（如MICROPHONE从API 8开始支持）

二、权限开发技术实现指南

2.1 基础配置：module.json5声明

所有权限必须在应用模块配置文件中声明，格式如下：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET", // 系统授权权限只需名称
        "reason": "用于下载应用更新包",      // 用户授权权限必填申请原因
        "usedScene": "应用启动时检测更新"    // 用户授权权限必填使用场景
      },
      {
        "name": "ohos.permission.CAMERA",    // 危险权限需额外字段
        "reason": "用于扫码登录功能",
        "usedScene": "扫码支付/身份认证场景"
      }
    ]
  }
}

2.2 权限申请核心API（JS/TS示例）

2.2.1 创建权限管理实例

import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

// 1. 创建权限管理实例
const permissionManager = abilityAccessCtrl.createAtManager();

2.2.2 拉起授权弹窗（首次申请）

// 2. 拉起权限申请弹窗（用户授权类型）
const permissions = ["ohos.permission.CAMERA"];
permissionManager.requestPermissionsFromUser(
  permissions,
  (err, data) => {
    if (err) {
      console.error("权限申请失败", err);
      return;
    }
    // 处理用户授权结果（data.granted为true/false）
    if (data.granted) {
      console.log("用户已授权摄像头权限");
      this.startCamera(); // 执行需要权限的业务逻辑
    } else {
      console.log("用户拒绝授权，原因：", data.reason);
      // 可引导用户前往设置页手动授权
      this.showSettingPage();
    }
  }
);

2.2.3 处理用户拒绝后的二次申请

// 3. 用户拒绝后再次申请（需提供补充理由）
const requestAgain = () => {
  // 判断是否为用户主动拒绝（非“不再询问”状态）
  if (!data.neverAskAgain) {
    permissionManager.requestPermissionOnSetting(
      "ohos.permission.CAMERA",
      "该功能需要摄像头权限以扫描二维码支付，请授权后重试"
    );
  } else {
    // 引导用户手动前往设置页（需提供跳转指引）
    this.showSettingDialog();
  }
};

2.3 系统授权 vs 用户授权的代码差异

​场景​	系统授权（如INTERNET）	用户授权（如CAMERA）
配置差异	无需reason/usedScene字段	必须填写reason（20-200字符）和usedScene
API调用	无需主动申请，权限自动生效	必须调用requestPermissionsFromUser或requestPermissionOnSetting
用户交互	无弹窗/提示，静默获取	强制弹窗或引导至设置页

三、最佳实践与避坑指南

3.1 权限粒度最小化

• ​反例​：一次性申请所有权限（requestPermissionsFromUser(["INTERNET", "CAMERA", "LOCATION"])）
• ​正例​：按功能模块拆分权限申请（仅在用户进入“扫码支付”页面时申请CAMERA权限）

3.2 拒绝后的优雅降级

// 权限被拒时的功能降级处理
if (!data.granted) {
  // 关闭依赖权限的高级功能，保留基础功能
  this.disableCameraPreview();
  this.enableManualInputMode(); // 切换至手动输入替代方案
}

3.3 版本兼容性适配

// 检查权限是否支持（针对起始版本较高的权限）
const isCameraSupported = featureAbility.getSystemCapability("ohos.capability.Camera") !== undefined;
if (isCameraSupported && deviceInfo.getDeviceOSVersion() >= "9.0.0") {
  // 9.0+系统才支持CAMERA权限申请
  this.requestCameraPermission();
} else {
  this.showToast("当前系统不支持摄像头功能");
}

四、完整权限申请流程图

五、常见问题解答

Q1：为什么用户授权的权限需要声明reason和usedScene？

A：根据HarmonyOS隐私规范，敏感权限必须向用户清晰说明“为什么需要”（reason）和“在哪里用”（usedScene），否则可能导致权限申请被系统拦截。

Q2：系统授权的权限是否100%安全？

A：系统授权仅代表应用无需手动申请，但仍需遵循数据安全原则（如INTERNET权限获取的网络数据需加密传输）。

通过以上文档，开发者可快速掌握HarmonyOS权限管理的核心逻辑、代码实现及合规要点，实现“功能完整”与“隐私合规”的平衡。如需特定权限（如LOCATION、CONTACTS）的详细开发案例，可进一步补充说明场景需求。