本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

前言

在鸿蒙应用开发中，权限声明是应用上架前必须完成的步骤。如果权限声明不规范，轻则功能异常，重则应用上架申请被驳回。

本文将详细介绍：

• 权限声明的配置方法：module.json5中的requestPermissions标签

• 各字段的详细说明：name、reason、usedScene

• 多HAP场景的注意事项：权限重复声明问题

• 权限使用理由的写作规范：如何写出合规的理由

一、为什么需要声明权限？

应用在申请权限时，必须在项目的配置文件中逐个声明所需权限，否则：

1. 无法获取授权：系统不会授予未声明的权限

2. 上架申请被驳回：应用市场上架时会校验权限声明

3. 功能异常：调用需要权限的接口时会失败

二、在配置文件中声明权限

2.1 requestPermissions标签

应用必须在module.json5配置文件的requestPermissions标签中声明权限。

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:camera_permission_reason",
        "usedScene": {
          "abilities": ["CameraAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

2.2 字段说明

属性	含义	数据类型	取值范围/要求
name	需要使用的权限名称	字符串	必填，需为系统已定义的权限，参考应用权限列表
reason	申请权限的原因	字符串	申请user_grant/manual_settings权限时必填，需多语种适配。格式为$string:xxx
usedScene	权限使用的场景	对象	申请user_grant/manual_settings权限时必填，包含abilities和when两个子项

2.3 usedScene子项说明

子项	含义	说明
abilities	使用权限的UIAbility或ExtensionAbility组件名称	可选填写，可配置为多个名称的字符串数组
when	调用时机	可选填写，但如果配置此字段，只能填入固定值： - inuse：使用时 - always：始终

三、声明示例

3.1 混合权限类型声明

{
  "module": {
    "requestPermissions": [
      // 1. user_grant权限：需要填写reason和usedScene
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:approximately_location_permission_reason",
        "usedScene": {
          "abilities": ["FormAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:location_permission_reason",
        "usedScene": {
          "abilities": ["FormAbility"],
          "when": "inuse"
        }
      },
      
      // 2. system_grant权限：reason和usedScene为选填
      {
        "name": "ohos.permission.USE_BLUETOOTH"
      }
    ]
  }
}

3.2 资源文件配置

// src/main/resources/base/element/string.json
{
  "string": [
    {
      "name": "approximately_location_permission_reason",
      "value": "用于获取您的大致位置，以提供附近的商家推荐"
    },
    {
      "name": "location_permission_reason",
      "value": "用于获取您的精确位置，以提供导航服务"
    }
  ]
}

四、多HAP场景的权限声明

4.1 规则

在多HAP场景下：

• 已在entry模块中声明的权限，无需在feature模块中重复添加

• 已在feature模块中声明的权限，在entry模块也无需重复添加

• 权限将在整个应用中生效

4.2 示例说明

应用结构：
- entry模块（主模块）
- feature1模块（功能模块）
- feature2模块（功能模块）

权限声明规则：
├── entry 声明了 CAMERA 权限
├── feature1 需要使用 CAMERA → 无需再次声明
├── feature2 需要使用 CAMERA → 无需再次声明
└── 整个应用都拥有 CAMERA 权限

五、权限使用理由的文案内容规范

当申请user_grant/manual_settings权限时，字段reason（申请权限的原因）必填。规范填写的原因是：

1. 授权弹窗展示：向用户申请授权时显示

2. 设置界面展示：在"设置-隐私-权限管理"中显示

3. 上架审核依据：应用市场审核的重要材料

在实际向用户弹窗申请授权时，user_grant权限将会以权限组的形式向用户申请。

两种展示方式：

权限组类型	展示方式	示例
电话、信息、日历、通讯录、通话记录	展示具体子权限的内容与用途	"包括子权限A和子权限B，用于某事"
其他权限组	展示权限组内第一个被申请的子权限的使用理由	申请{权限C, 权限B}，展示权限B的理由

写作规范

基本原则

原则	说明
准确性	准确告知用户获取权限后用于什么场景/功能
直白性	使用直白、具体、易理解的完整短句
完整性	如果用于多个场景，需要完整描述所有场景

句式要求

建议句式：用于做某事。

正例：

• "用于视频通话"

• "用于获取您的位置以提供导航服务"

• "用于拍照和录制视频"

反例：

• "使用相机"（未明确场景）

• "获取相机权限"（未明确用途）

• "需要权限"（空洞无物）

长度要求

指标	要求
建议长度	小于72个字符（36个中文字符）
最大长度	不超过256个字符
最低要求	不能为空白字符串

5.4 多HAP场景的Reason一致性

如果应用申请的权限用于多个场景，需要确保字串的完整性，让用户了解应用使用此权限的所有场景。

场景示例：

• HAP1：视频通话功能

• HAP2：视频直播功能

• 都需申请相机权限

类型	写法	是否合格
正例	HAP1和HAP2都填写："用于视频通话、视频直播功能。"	✅
反例1	HAP1："用于视频通话功能。" HAP2："用于视频直播功能。"	未保持一致
反例2	HAP1和HAP2都填写："用于视频通话功能。"	描述不全面

5.5 多包场景的Reason优先级

如果应用内多包申请的权限名称相同，但权限使用理由不一致，系统返回的权限申请详细信息中只会显示一个权限申请理由。

优先级从高到低：

1. entry类型HAP

2. feature类型HAP

3. 应用内HSP

六、权限使用理由的展示途径

6.1 授权弹窗界面

当应用首次申请权限时，系统会弹出授权对话框，展示权限使用理由。

6.2 设置界面

用户可以在"设置-隐私-权限管理-某应用某权限详情"中查看权限使用理由。