# 声明权限

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

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

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

| 属性 | 含义 | 数据类型 | 取值范围 |
| --- | --- | --- | --- |
| name | 需要使用的权限名称。 | 字符串 | 必填，需为系统已定义的权限，取值范围请参考应用权限列表。 |
| reason | 申请权限的原因。 | 字符串 | 可选填写，该字段用于应用上架校验，申请user_grant/manual_settings权限时必填并需多语种适配。 格式为$string: ***。string资源引用需要在string.json文件配置标签"name": "reason"，配置样例可参考资源文件示例。 reason填写内容可参考权限使用理由的文案内容规范。 |
| usedScene | 权限使用的场景，该字段用于应用上架校验。包括abilities和when两个子项。 - abilities：使用权限的UIAbility或者ExtensionAbility组件的名称。 - when：调用时机。 | 对象 | 申请user_grant/manual_settings权限时，usedScene必填，其他情况下选填。 - abilities：可以配置为多个UIAbility或者ExtensionAbility名称的字符串数组。 - when：配置此字段，只能填入固定值inuse（使用时）或always（始终），不能为空。 |

在多HAP场景下，已在entry模块中声明的权限，无需在feature模块中重复添加，权限将在整个应用中生效。

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

#### 声明样例

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

下述"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权限将会以权限组的形式向用户申请。当前支持的权限组请查看应用权限组列表。

#### reason字段的内容写作规范及建议

1.  权限使用理由应准确告知用户获取权限后用于什么场景/功能。
    
    未明确告知用户实际使用场景/功能、权限使用理由和实际调用权限功能不符合将会导致权限申请被驳回，进而导致应用上架申请被驳回。
    
    **样例**：以申请相机权限的reason字符串为例。
    
    正例：用于视频通话/拍照。
    
    反例（未明确告知用户实际使用场景/功能）：使用相机；获取相机权限；需要权限。
    
    反例（权限使用理由和实际调用权限功能不符）：录制音频用于语音聊天；获取蓝牙权限用于多设备之间传输文件。
    
    如需了解更多权限使用理由的案例讲解，可参考隐私合规问题小学堂——未同步告知权限的使用目的。
    
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中，相机权限的使用理由都填写为“用于视频通话功能。”。
    

#### 权限使用理由展示方式

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

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