大网数据广告活动
OpenHarmony 设备与应用开发

声明权限

· 52CE 我爱测

当申请user_grant/manual_settings权限时,字段reason(申请权限的原因)必填。开发者需在应用配置文件中配置每个需要的权限。

声明权限

应用在申请权限时,需在项目的配置文件中逐个声明所需权限,否则无法获取授权。

在配置文件中声明权限

应用必须在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(始终),不能为空。
requiredFeature 权限声明生效所需的设备特性。当设备不支持该特性时,将不会声明此权限。 字符串 可选填写,仅对系统应用生效。长度不超过64个字符,只能包含字母、数字和英文句点,且必须以字母开头。
起始版本:26.0.0

说明:

在多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. 保持句子简洁,不要加入多余的分割符号。

    建议句式:用于某事。

    示例:用于扫码拍照。

  2. 用途描述的字串建议小于72个字符(即36个中文字符,UI界面显示大约为两行)。不能超过256个字符,以保证多语言适配的体验。

  3. 如果不填写,将展示默认的申请理由。

权限使用理由展示方式

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

  1. 如果申请的是“电话、信息、日历、通讯录、通话记录”这五个权限组中的权限,根据工信部要求,将展示具体子权限的内容与用途。

    句式:包括子权限A和子权限B,用于某事。

    样例:用于获取通话状态和移动网络信息,用于安全运营和统计计费服务。

  2. 如果是申请其他权限组中的权限,系统将使用权限组内当前被申请的第一个子权限的使用理由,作为该权限组的使用理由进行展示。组内的排序固定按照权限管理内排列的权限组数组顺序。

    举例说明:权限组A = {权限A, 权限B, 权限C};申请传入的权限是{权限C, 权限B},界面将展示权限B的权限使用理由。

  3. 如果应用内多包申请的权限名称相同,但权限使用理由不一致,系统返回的权限申请详细信息ReqPermissionDetail中只会显示一个权限申请理由。优先级从高到低为:entry类型HAP、feature类型HAP、应用内HSP。

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。