声明权限
====

应用在申请权限时，需在项目的配置文件中逐个声明所需权限，否则无法获取授权，并可能导致应用上架申请被驳回。

#### 在配置文件中声明权限

应用必须在[module.json5配置文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file)的requestPermissions标签中声明权限。

| 属性 | 含义 | 数据类型 | 取值范围 |
| :-- | :-- | :-- | :-- |
| name | 需要使用的权限名称。 | 字符串 | **必填**，需为系统已定义的权限，取值范围请参考[应用权限列表](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-permissions)。 |
| reason | 申请权限的原因。 | 字符串 | 
**可选填写**，该字段用于应用上架校验，申请user\_grant/manual\_settings权限时必填并需多语种适配。

格式为$string: \*\*\*。string资源引用需要在string.json文件配置标签"name": "reason"，配置样例可参考[资源文件示例](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/resource-categories-and-access#资源文件示例)。

reason填写内容可参考[权限使用理由的文案内容规范](#权限使用理由的文案内容规范)。

 |
| usedScene | 

权限使用的场景，该字段用于应用上架校验。包括abilities和when两个子项。

\- abilities：使用权限的UIAbility或者ExtensionAbility组件的名称。

\- when：调用时机。

 | 对象 | 

**申请user\_grant/manual\_settings权限时，usedScene必填，其他情况下选填。**

\- abilities：可以配置为多个UIAbility或者ExtensionAbility名称的字符串数组。

\- when：配置此字段，只能填入固定值**inuse**（使用时）或**always**（始终），不能为空。

 |

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7f/v3/2ldRoah9Ql6fRG3KxqycxQ/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073351Z&HW-CC-Expire=86400&HW-CC-Sign=18432C9516B575BF025FC2D4C3AC85EF366626286A75B8ACBCB14AA370D93BD4)

在多HAP场景下，已在[entry](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package)模块中声明的权限，无需在[feature](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package)模块中重复添加，权限将在整个应用中生效。

同理，在[feature](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package)模块中已声明的权限，在[entry](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package)模块也无需重复添加。

#### 声明样例

在[module.json5配置文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file)的requestPermissions标签中声明权限。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/13/v3/DnQcvtIzTNeIHwbMCAqXfQ/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073351Z&HW-CC-Expire=86400&HW-CC-Sign=AF7211E33A67F5F3BBFB5D2909B497B5EA3CEF1D47CED6C6F750D5062F44BA9B)

下述"name"中填入的权限仅为样例示意。请开发者根据实际需要，参照上表要求填写对应属性。

{
  "module": {
    // ···
    // 1.ohos.permission.APPROXIMATELY\_LOCATION与ohos.permission.LOCATION为user\_grant权限，reason和usedScene为必填字段。
    // 2.ohos.permission.USE\_BLUETOOTH为system\_grant权限，reason和usedScene为选填字段。
    "requestPermissions": \[
      {
        "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"
        }
      },
      {
        "name": "ohos.permission.USE\_BLUETOOTH"
      }
    \]
  }
}

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

当申请user\_grant/manual\_settings权限时，字段reason（申请权限的原因）必填。开发者需在应用配置文件中配置每个需要的权限。

但在实际向用户弹窗申请授权时，user\_grant权限将会以[权限组](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-permission-mgmt-overview#权限组和子权限)的形式向用户申请。当前支持的权限组请查看[应用权限组列表](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-permission-group-list)。

#### \[h2\]reason字段的内容写作规范及建议

1.  权限使用理由应准确告知用户获取权限后用于什么场景/功能。
    
    未明确告知用户实际使用场景/功能、权限使用理由和实际调用权限功能不符合将会导致权限申请被驳回，进而导致应用上架申请被驳回。
    
    **样例**：以申请相机权限的reason字符串为例。
    
    正例：用于视频通话/拍照。
    
    反例（未明确告知用户实际使用场景/功能）：使用相机；获取相机权限；需要权限。
    
    反例（权限使用理由和实际调用权限功能不符）：录制音频用于语音聊天；获取蓝牙权限用于多设备之间传输文件。
    
    如需了解更多权限使用理由的案例讲解，可参考[隐私合规问题小学堂——未同步告知权限的使用目的](https://developer.huawei.com/consumer/cn/forum/topic/0208158494714878699?fid=0102104600515103427)。
    
2.  字串应为直白、具体、易理解的完整短句， 用于向用户说明应用使用敏感权限的理由。句子避免使用被动语态，并以句号结尾。
    
    *   **建议句式**：用于做某事。
        
    *   **样例**：以申请相机权限的reason字符串为例。
        
        正例：用于视频通话。
        
3.  用途描述的字串建议小于72个字符（即36个中文字符，UI界面显示大约为两行）。不能超过256个字符，以保证多语言适配的体验。
    
4.  字串不能为空白字符串，即不能不填，也不能只填空格符。
    
5.  如果应用申请的权限用于多个场景，需要确保字串的完整性，让用户了解应用使用此权限的所有场景；多个HAP包内如果申请同一个权限，各个权限Reason字段需要保持场景的完整性和一致性。
    
    **样例：**
    
    应用中有2个HAP包，均需申请使用相机权限，其中HAP1提供功能场景为视频通话、HAP2提供功能场景为视频直播。
    
    正例：HAP1和HAP2中，相机权限的使用理由都填写为“用于视频通话、视频直播功能。”
    
    反例1：HAP1和HAP2中，相机权限的使用理由字段未保持完全一致。如HAP1中填写为“用于视频通话功能。”，HAP2中填写为“用于视频直播功能。”
    
    反例2：HAP1和HAP2中，相机权限的使用理由字段保持完全一致，但是描述不全面，如HAP1和HAP2中，相机权限的使用理由都填写为“用于视频通话功能。”。
    

#### \[h2\]权限使用理由展示方式

权限使用理由有两个展示途径：授权弹窗界面和“设置（Settings）”界面。“设置”的具体路径：设置-隐私-权限管理-某应用某权限详情。

1.  如果申请的是“电话、信息、日历、通讯录、通话记录”这五个权限组中的权限，根据工信部要求，将展示具体子权限的内容与用途。
    
    **句式**：包括子权限A和子权限B，用于某事。
    
    **样例**：用于获取通话状态和移动网络信息，用于安全运营和统计计费服务。
    
2.  如果是申请其他权限组中的权限，系统将使用权限组内当前被申请的第一个子权限的使用理由，作为该权限组的使用理由进行展示。组内的排序固定按照权限管理内排列的权限组数组顺序。
    
    举例说明：权限组A = {权限A, 权限B, 权限C}；申请传入的权限是{权限C, 权限B}，界面将展示权限B的权限使用理由。
    
3.  如果应用内多包申请的权限名称相同，但权限使用理由不一致，系统返回的权限申请详细信息[ReqPermissionDetail](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-bundlemanager-bundleinfo#reqpermissiondetail)中只会显示一个权限申请理由。优先级从高到低为：entry类型HAP、feature类型HAP、应用内HSP。