!21029 更新权限文档，增加权限组说明

Merge pull request !21029 from zengyawen/master

zh-cn/application-dev/security/Readme-CN.md

@@ -5,6 +5,7 @@
   - [访问控制授权申请指导](accesstoken-guidelines.md)
   - [访问控制权限校验指导](permission-verify-guidelines.md)
   - [应用权限列表](permission-list.md)
+  - [应用权限组列表](permission-group-list.md)
 - 用户认证
   - [用户认证开发概述](userauth-overview.md)
   - [用户认证开发指导](userauth-guidelines.md)

zh-cn/application-dev/security/accesstoken-guidelines.md

@@ -24,8 +24,8 @@
 | 标签      | 是否必填 | 说明                                                         |
 | --------- | -------- | ------------------------------------------------------------ |
 | name      | 是       | 权限名称。                                                   |
-| reason    | 否       | 描述申请权限的原因。<br/>> **说明**：当申请的权限为user_grant权限时，此字段必填。 |
-| usedScene | 否       | 描述权限使用的场景和时机。<br/>> **说明**：当申请的权限为user_grant权限时，此字段必填。 |
+| reason    | 否       | 描述申请权限的原因，可参考[权限使用理由的文案内容规范](#权限使用理由的文案内容规范)。<br/> > **说明**：当申请的权限为user_grant权限时，此字段必填。 |
+| usedScene | 否       | 描述权限使用的场景和时机。<br/> > **说明**：当申请的权限为user_grant权限时，此字段必填。 |
 | abilities | 否       | 标识需要使用到该权限的Ability，标签为数组形式。<br/>**适用模型**：Stage模型 |
 | ability   | 否       | 标识需要使用到该权限的Ability，标签为数组形式。<br/>**适用模型**：FA模型 |
 | when      | 否       | 标识权限使用的时机，值为`inuse/always`。<br/>- inuse：表示为仅允许前台使用。<br/>- always：表示前后台都可使用。 |
@@ -98,6 +98,38 @@
 }
 ```
 
+### 权限使用理由的文案内容规范
+
+当申请的权限为user_grant权限时，字段reason（申请权限的原因）必填。开发者需要在应用配置文件中，配置每一个需要使用的权限。
+
+但在实际向用户弹窗申请授权时，user_grant权限将会以[权限组](accesstoken-overview.md#权限组和子权限)向用户申请。当前支持的权限组请查看[应用权限组列表](permission-group-list.md)。
+
+**reason字段的内容写作规范及建议如下：**
+
+1. 保持句子简洁、不要加入多余的分割符号。
+
+   **建议句式**：用于某事。
+
+   **示例**：用于扫码拍照。
+
+2. 用途描述的字串建议小于72个字符（即36个中文字符，UI界面显示大约为两行）。不能超过256个字符，以免在多语言适配后体验不好。
+
+3. 如果不写，将展示默认的申请理由。
+
+**权限使用理由展示方式：**
+
+权限使用理由有两个展示途径：授权弹窗界面和“设置（Settings）”界面。“设置”的具体路径：设置-隐私-权限管理-某应用某权限详情
+
+1. 如果是申请“电话、信息、日历、通讯录、通话记录”这五个权限组中的权限，根据工信部要求，将展示具体子权限的内容与用途。
+
+   **句式**：包括子权限A和子权限B，用于某事。
+
+   **样例**：用于获取通话状态和移动网络信息，用于安全运营和统计计费服务。
+
+2. 如果是申请其他权限组中的权限。系统将使用权限组内当前被申请的第一个子权限的使用理由，作为该权限组的使用理由进行展示。组内的排序，固定按照权限管理内排列的权限组数组顺序。
+
+   举例说明：权限组A = {权限A, 权限B, 权限C}；申请传入的是{权限C, 权限B}，界面将展示权限B中的权限使用理由。
+
 ## ACL方式声明
 
 当应用需要申请`system_basic`和`system_core`等级的权限时，比应用默认权限等级`normal`更高。如果需要申请的权限等级高于应用默认的等级，需要使用ACL方式声明使用。
@@ -120,7 +152,8 @@
 
 当应用需要访问用户的隐私信息或使用系统能力时，例如获取位置信息、访问日历、使用相机拍摄照片或录制视频等，应该向用户请求授权。这需要使用 `user_grant` 类型权限。在此之前，应用需要进行权限校验，以判断当前调用者是否具备所需的权限。如果权限校验结果表明当前应用尚未被授权该权限，则应使用动态弹框授权方式，为用户提供手动授权的入口。示意效果如下图所示。
 
-图1 向用户申请授权   
+图1 向用户申请授权
+
 ![](figures/permission-read_calendar.png)
 
 > **说明**：
@@ -222,6 +255,7 @@
    ```
 
    在UI中向用户申请授权。
+
    ```typescript
    import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';
    import common from '@ohos.app.ability.common';
@@ -300,6 +334,7 @@ reqPermissions() {
     });
 }
 ```
+
 ## user_grant权限预授权
 应用在申请`user_grant`类型的权限默认未授权，需要通过拉起弹框由用户确认是否授予该权限。对于一些预制应用，不希望出现弹窗申请`user_grant`类型的权限，例如系统相机应用需要使用麦克风` ohos.permission.MICROPHONE`等权限，需要对麦克风等权限进行预授权，可以通过预授权的方式完成`user_grant`类型权限的授权。[预置配置文件](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json)在设备上的路径为`/system/etc/app/install_list_permission.json`，设备开机启动时会读取该配置文件，在应用安装会对在文件中配置的`user_grant`类型权限授权。预授权配置文件字段内容包括`bundleName`、`app_signature`和`permissions`。
 
@@ -308,7 +343,7 @@ reqPermissions() {
 - `permissions`字段中`name`配置为需要预授权的`user_grant`类型的权限名；`permissions`字段中`userCancellable`表示为用户是否能够取消该预授权，配置为true，表示支持用户取消授权，为false则表示不支持用户取消授权。
 
 > **说明**：
-> 
+>
 > 当前仅支持预置应用配置该文件。
 
 ```json

zh-cn/application-dev/security/accesstoken-overview.md

@@ -22,7 +22,6 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应
 - 应用在首次启动时，避免频繁弹窗申请多个权限；权限须在用户使用对应业务功能时动态申请。
 - 用户拒绝授予某个权限时，与此权限无关的其他业务功能应能正常使用，不能影响应用的正常注册或登录。
 - 业务功能所需要的权限被用户拒绝且禁止后不再提示，当用户主动触发使用此业务功能或为实现业务功能所必须时，应用程序可通过界面内文字引导，让用户主动到“系统设置”中授权。
-
 - 当前不允许应用自行定义权限，应用申请的权限应该从[已有的权限列表](permission-list.md)中选择。
 
 ## 权限的工作流程
@@ -54,6 +53,7 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应
 3：应用可以通过ACL（访问控制列表）方式申请高级别的权限，具体请参考[访问控制列表（ACL）说明](#访问控制列表acl说明)。
 
 ### 权限校验的工作流程
+
 应用在提供对外功能服务接口时，可以根据接口涉数据的敏感程度或所涉能力的安全威胁影响，在[权限定义列表](permission-list.md)选择合适的权限保护当前接口，对访问者进行权限校验。
 
 当且仅当访问者获取当前接口所需权限后，才能通过当前接口的权限校验，并正常使用当前应用提供的目标功能。
@@ -70,7 +70,7 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应
 
 3：应用可以使用权限校验接口对访问者进行鉴权，可参考[权限校验说明](permission-verify-guidelines.md)。
 
-## 权限等级说明
+## 权限等级
 
 根据接口所涉数据的敏感程度或所涉能力的安全威胁影响，ATM模块定义了不同开放范围的权限等级来保护用户隐私。
 
@@ -130,7 +130,7 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应
 - **system_core权限**
 
     system_core权限涉及到开放操作系统核心资源的访问操作。这部分系统资源是系统最核心的底层服务，如果遭受破坏，操作系统将无法正常运行。
-    
+
     鉴于该类型权限对系统的影响程度非常大，目前暂不向任何三方应用开放。
 
 ## 权限类型说明
@@ -153,6 +153,14 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应
 
     应用需要在应用商店的详情页面，向用户展示所申请的user_grant权限列表。
 
+### 权限组和子权限
+
+为了仅可能减少系统弹出的权限弹窗数量，优化交互体验，系统将逻辑紧密相关的user_grant权限组合在一起，形成多个权限组。
+
+当应用请求权限时，同一个权限组的权限将会在一个弹窗内一起请求用户授权。权限组中的某个权限，称之为该权限组的子权限。
+
+权限组和权限的归属关系并不是固定不变的，一个权限所属的权限组有可能发生变化。当前系统支持权限组请查阅[应用权限组列表](permission-group-list.md)。
+
 ### 不同权限类型的授权流程
 
 如[权限的工作流程](#权限的工作流程)所示，如果应用需要获取目标权限，那么需要先进行权限申请。
@@ -163,14 +171,14 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应
 
 - 权限授权
 
-   - 如果目标权限是system_grant类型，开发者在进行权限申请后，系统会在安装应用时自动为其进行权限预授予，开发者不需要做其他操作即可使用权限。
-   - 如果目标权限是user_grant类型，开发者在进行权限申请后，在运行时触发动态弹窗，请求用户授权，具体操作见[user_grant权限请求授权的步骤详解](#user_grant权限请求授权的步骤详解)。
+  - 如果目标权限是system_grant类型，开发者在进行权限申请后，系统会在安装应用时自动为其进行权限预授予，开发者不需要做其他操作即可使用权限。
+  - 如果目标权限是user_grant类型，开发者在进行权限申请后，在运行时触发动态弹窗，请求用户授权，具体操作见[user_grant权限请求授权的步骤详解](#user_grant权限请求授权的步骤详解)。
 
 ### user_grant权限请求授权的步骤详解
 
 在应用需要获取user_grant权限时，请完成以下步骤：
 
-1. 在配置文件中，声明应用需要请求的权限，详见[访问控制开发指导](accesstoken-guidelines.md)。
+1. 在配置文件中，声明应用需要请求的权限，详见[访问控制开发指导-配置文件权限声明](accesstoken-guidelines.md#配置文件权限声明)。
 
 2. 将应用中需要申请权限的目标对象与对应目标权限进行关联，让用户明确地知道，哪些操作需要用户向应用授予指定的权限。
 
@@ -178,10 +186,10 @@ ATM (AccessTokenManager) 是OpenHarmony上基于AccessToken构建的统一的应
 
 4. 检查用户的授权结果，确认用户已授权才可以进行下一步操作。
 
-**注意事项：** 
+**注意事项：**
 
 - 每次执行需要目标权限的操作时，应用都必须检查自己是否已经具有该权限。
-- 如需检查用户是否已向您的应用授予特定权限，可以使用[checkAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md#checkaccesstoken9)函数，此方法会返回  [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md)或[PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md)。具体的示例代码可以查看[访问控制开发指导](accesstoken-guidelines.md)。
+- 如需检查用户是否已向您的应用授予特定权限，可以使用[checkAccessToken](../reference/apis/js-apis-abilityAccessCtrl.md#checkaccesstoken9)函数，此方法会返回  [PERMISSION_GRANTED](../reference/apis/js-apis-abilityAccessCtrl.md)或[PERMISSION_DENIED](../reference/apis/js-apis-abilityAccessCtrl.md)。具体的示例代码可以查看[访问控制开发指导](accesstoken-guidelines.md#向用户申请授权)。
 - user_grant权限授权要基于用户可知可控的原则，需要应用在运行时主动调用系统动态申请权限的接口，系统弹框由用户授权，用户结合应用运行场景的上下文，识别出应用申请相应敏感权限的合理性，从而做出正确的选择。
 - 即使用户向应用授予过请求的权限，应用在调用受此权限管控的接口前，也应该先检查自己有无此权限，而不能把之前授予的状态持久化，因为用户在动态授予后还可以通过设置取消应用的权限。
 

zh-cn/application-dev/security/permission-group-list.md

+# 应用权限组列表
+
+在申请目标权限前，建议开发者先阅读[访问控制开发概述-权限组和子权限](accesstoken-overview.md#权限组和子权限)，了解权限组和子权限的概念，再合理申请对应的权限组。
+
+当前系统支持权限组如下所示，各子权限的含义请查阅[应用权限列表](permission-list.md)。
+
+## 位置信息
+
+- ohos.permission.LOCATION_IN_BACKGROUND
+- ohos.permission.LOCATION
+- ohos.permission.APPROXIMATELY_LOCATION
+
+## 相机
+
+- ohos.permission.CAMERA
+
+## 麦克风
+
+- ohos.permission.MICROPHONE
+
+## 日历
+
+- ohos.permission.READ_CALENDAR
+- ohos.permission.WRITE_CALENDAR
+- ohos.permission.READ_WHOLE_CALENDAR
+- ohos.permission.WRITE_WHOLE_CALENDAR
+
+## 健身运动
+
+- ohos.permission.ACTIVITY_MOTION
+
+## 身体传感器
+
+- ohos.permission.READ_HEALTH_DATA
+
+## 多设备协同
+
+- ohos.permission.DISTRIBUTED_DATASYNC
+
+## 电话
+
+- ohos.permission.ANSWER_CALL
+- ohos.permission.MANAGE_VOICEMAIL
+
+## 通讯录
+
+- ohos.permission.READ_CONTACTS
+- ohos.permission.WRITE_CONTACTS
+
+## 通话记录
+
+- ohos.permission.READ_CALL_LOG
+- ohos.permission.WRITE_CALL_LOG
+
+## 信息
+
+- ohos.permission.READ_CELL_MESSAGES
+- ohos.permission.READ_MESSAGES
+- ohos.permission.RECEIVE_MMS
+- ohos.permission.RECEIVE_SMS
+- ohos.permission.RECEIVE_WAP_MESSAGES
+- ohos.permission.SEND_MESSAGES
+
+## 音乐和音频
+
+- ohos.permission.WRITE_AUDIO
+- ohos.permission.READ_AUDIO
+
+## 文件
+
+- ohos.permission.READ_DOCUMENT
+- ohos.permission.WRITE_DOCUMENT
+- ohos.permission.READ_MEDIA
+- ohos.permission.WRITE_MEDIA
+
+## 图片和视频
+
+- ohos.permission.WRITE_IMAGEVIDEO
+- ohos.permission.READ_IMAGEVIDEO
+- ohos.permission.MEDIA_LOCATION
+
+## 广告跟踪
+
+- ohos.permission.APP_TRACKING_CONSENT
+
+## 读取已安装应用列表
+
+- ohos.permission.GET_INSTALLED_BUNDLE_LIST

zh-cn/application-dev/security/permission-list.md

@@ -593,6 +593,7 @@
 **ACL使能**：TRUE
 
 **起始版本**：7
+
 ## ohos.permission.ACCELEROMETER
 
 允许应用读取加速度传感器的数据。