!12698 权限弹框接口迁移资料

Merge pull request !12698 from y1585740638/request1220

!12698 权限弹框接口迁移资料
Merge pull request !12698 from y1585740638/request1220
81362690 · openharmony_ci · Gitee · 5642cf13 · d48c3b02 · 81362690
11 changed file
--- a/zh-cn/application-dev/ability-deprecated/continuationmanager.md
+++ b/zh-cn/application-dev/ability-deprecated/continuationmanager.md
@@ -124,7 +124,7 @@ continuationManager作为流转能力的入口，主要用于拉起系统中的
        if (needGrantPermission) {
            try {
                // globalThis.context即Ability.context,需提前在MainAbility.ts文件中赋值
-                await globalThis.context.requestPermissionsFromUser(permissions);
+                await atManger.requestPermissionsFromUser(globalThis.context, permissions);
            } catch (err) {
                console.error('app permission request permissions error' + JSON.stringify(err));
            }

--- a/zh-cn/application-dev/ability-deprecated/stage-ability-continuation.md
+++ b/zh-cn/application-dev/ability-deprecated/stage-ability-continuation.md
@@ -127,7 +127,7 @@
            if (needGrantPermission) {
                Logger.info("app permission needGrantPermission")
                try {
-                    await this.context.requestPermissionsFromUser(permissions)
+                    await accessManger.requestPermissionsFromUser(this.context, permissions)
                } catch (err) {
                    Logger.error(`app permission ${JSON.stringify(err)}`)
                }

--- a/zh-cn/application-dev/ability-deprecated/stage-ability.md
+++ b/zh-cn/application-dev/ability-deprecated/stage-ability.md
@@ -148,29 +148,8 @@ export default class MainAbility extends Ability {
    }
 }
 ```
-### 应用向用户申请授权
-应用需要获取用户的隐私信息或使用系统能力时，比如获取位置信息、使用相机拍摄照片或录制视频等，需要向用户申请授权。在开发过程中，首先需要明确涉及的敏感权限并在module.json5中声明需要的权限，同时通过接口`requestPermissionsFromUser`以动态弹窗的方式向用户申请授权。以访问日历为例，具体示例代码如下：
-
-在module.json5声明需要的权限：
-```json
-"requestPermissions": [
-    {
-    "name": "ohos.permission.READ_CALENDAR"
-    }
-]
-```
-通过动态弹窗向用户申请授权：
-```ts
-let context = this.context
-let permissions: Array<string> = ['ohos.permission.READ_CALENDAR']
-context.requestPermissionsFromUser(permissions).then((data) => {
-    console.log("Succeed to request permission from user with data: " + JSON.stringify(data))
-}).catch((error) => {
-    console.log("Failed to request permission from user with error: " + JSON.stringify(error))
-})
-```
 ### 系统环境变化通知
-环境变化，包括全局配置的变化和Ability配置的变化。全局配置指全局的、系统的配置，目前包括“语言”和“颜色模式”，全局配置的变化一般由“设置”中的配置项或“控制中心”中的图标触发。Ability配置指与单个Ability实例相关的配置，目前包括“displayId”（物理屏幕Id）、“屏幕分辨率”，“横竖屏”，这些配置与Ability所在的Display有关，Ability配置的变化一般由窗口触发。配置项目前均定义在[Configuration](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-configuration.md)类中。
+环境变化，包括全局配置的变化和Ability配置的变化。全局配置指全局的、系统的配置，目前包括“语言”和“颜色模式”，全局配置的变化一般由“设置”中的配置项或“控制中心”中的图标触发。Ability配置指与单个Ability实例相关的配置，目前包括“displayId”（物理屏幕Id）、“屏幕分辨率”，“横竖屏”，这些配置与Ability所在的Display有关，Ability配置的变化一般由窗口触发。配置项目前均定义在[Configuration](../reference/apis/js-apis-application-configuration.md)类中。

 对于Stage模型的应用，配置发生变化时，不会重启Ability，会触发应用的`onConfigurationUpdated(config: Configuration)`回调，若应用希望根据配置变化做相应处理，可以重写`onConfigurationUpdated`回调，若无需处理配置变化，则可以不必实现`onConfigurationUpdated`回调。应该注意的是，回调中的Configuration对象包括当前Ability所有的配置，不仅是发生变化的配置。

@@ -271,7 +250,7 @@ function getRemoteDeviceId() {
    }
 }
 ```
-向用户申请数据同步'ohos.permission.DISTRIBUTED_DATASYNC'的权限。申请授权示例代码见[应用向用户申请授权](#应用向用户申请授权)。
+向用户申请数据同步'ohos.permission.DISTRIBUTED_DATASYNC'的权限。申请授权示例代码见[abilityAccessCtrl.requestPermissionsFromUse](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9)。
 ### 指定页面启动Ability
 当Ability的启动模式设置为单例时，若Ability已被拉起，再次启动Ability会触发onNewWant回调。应用开发者可以通过want传递启动参数，比如希望指定页面启动Ability，可以通过want中的uri参数或parameters参数传递pages信息。目前，Stage模型中Ability暂时无法直接使用router的能力，可以将启动参数传递给自定义组件，在自定义组件的生命周期中调用router接口显示指定页面。具体示例代码如下：


--- a/zh-cn/application-dev/ability-deprecated/stage-call.md
+++ b/zh-cn/application-dev/ability-deprecated/stage-call.md
@@ -221,10 +221,13 @@ function getRemoteDeviceId() {
 ```
  在跨设备场景下，需要向用户申请数据同步的权限。具体示例代码如下：
 ```ts
+import abilityAccessCtrl from '@ohos.abilityAccessCtrl.d.ts';
+
 requestPermission() {
    let context = this.context
    let permissions: Array<string> = ['ohos.permission.DISTRIBUTED_DATASYNC']
-    context.requestPermissionsFromUser(permissions).then((data) => {
+    let atManager = abilityAccessCtrl.createAtManager();
+    atManager.requestPermissionsFromUser(context, permissions).then((data) => {
        console.log("Succeed to request permission from user with data: "+ JSON.stringify(data))
    }).catch((error) => {
        console.log("Failed to request permission from user with error: "+ JSON.stringify(error))

--- a/zh-cn/application-dev/faqs/faqs-file-management.md
+++ b/zh-cn/application-dev/faqs/faqs-file-management.md
@@ -77,11 +77,14 @@ getAlbums方法需要权限：ohos.permission.READ_MEDIA，从[OpenHarmony权限
 2. 在MainAbility.ts -&gt; onWindowStageCreate页面加载前需要增加用户授权代码：
     
   ```
+   import abilityAccessCtrl from '@ohos.abilityAccessCtrl.d.ts';
+   
   private requestPermissions() {
   let permissionList: Array<string> = [
     "ohos.permission.READ_MEDIA"
   ];
-   this.context.requestPermissionsFromUser(permissionList)
+   let atManager = abilityAccessCtrl.createAtManager();
+   atManager.requestPermissionsFromUser(this.context, permissionList)
     .then(data => {
       console.info(`request permission data result = ${data.authResults}`)
     })

--- a/zh-cn/application-dev/faqs/faqs-media.md
+++ b/zh-cn/application-dev/faqs/faqs-media.md
@@ -106,8 +106,12 @@ cameraInput = await this.cameraManager.createCameraInput(cameraId)
 2. 这两个权限的授权方式均为user_grant，因此需要调用requestPermissionsFromUser接口，以动态弹窗的方式向用户申请授权。
     
   ```
+   import abilityAccessCtrl from '@ohos.abilityAccessCtrl.d.ts';
+   
   let permissions: Array<string> = ['ohos.permission.READ_MEDIA','ohos.permission.WRITE_MEDIA']
-   context.requestPermissionsFromUser(permissions).then((data) => {
+   let atManager = abilityAccessCtrl.createAtManager();
+   // context为调用方UIAbility的AbilityContext
+   atManager.requestPermissionsFromUser(context, permissions).then((data) => {
       console.log("Succeed to request permission from user with data: " + JSON.stringify(data))
   }).catch((error) => {
       console.log("Failed to request permission from user with error: " + JSON.stringify(error))

--- a/zh-cn/application-dev/file-management/medialibrary-overview.md
+++ b/zh-cn/application-dev/file-management/medialibrary-overview.md
@@ -55,7 +55,7 @@ var media = mediaLibrary.getMediaLibrary(context);
 | ohos.permission.WRITE_MEDIA    | 允许应用读写用户外部存储中的媒体文件信息。 | user_grant |
 | ohos.permission.MEDIA_LOCATION | 允许应用访问用户媒体文件中的地理位置信息。 | user_grant |

-以上权限的授权方式均为user_grant（用户授权），即开发者在module.json5文件中配置对应的权限后，需要使用接口[Context.requestPermissionsFromUser](../reference/apis/js-apis-ability-context.md#abilitycontextrequestpermissionsfromuser)去校验当前用户是否已授权。如果是，应用可以直接访问/操作目标对象；否则需要弹框向用户申请授权。
+以上权限的授权方式均为user_grant（用户授权），即开发者在module.json5文件中配置对应的权限后，需要使用接口[abilityAccessCtrl.requestPermissionsFromUser](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9)去校验当前用户是否已授权。如果是，应用可以直接访问/操作目标对象；否则需要弹框向用户申请授权。

 > **说明：**<br/>即使用户曾经授予权限，应用在调用受此权限保护的接口前，也应该先检查是否有权限。不能把之前授予的状态持久化，因为用户在动态授予后还可以通过“设置”取消应用的权限。

@@ -105,13 +105,15 @@ var media = mediaLibrary.getMediaLibrary(context);
 2. 调用requestPermissionsFromUser进行权限校验，可以选择需要动态申请获取的权限。

   ```ts
-   import Ability from '@ohos.application.Ability'
+   import Ability from '@ohos.application.Ability';
+   import abilityAccessCtrl from '@ohos.abilityAccessCtrl.d.ts';
   
   export default class MainAbility extends Ability {
       onWindowStageCreate(windowStage) {
           var permissions=['ohos.permission.READ_MEDIA','ohos.permission.WRITE_MEDIA']
           var permissionRequestResult;
-           this.context.requestPermissionsFromUser(permissions,(err,result) => {
+           let atManager = abilityAccessCtrl.createAtManager();
+           atManager.requestPermissionsFromUser(this.context, permissions, (err,result) => {
               if(err){
                   console.log('requestPermissionsFromUserError: ' + JSON.stringify(err));
               }else{

--- a/zh-cn/application-dev/reference/apis/js-apis-ability-context.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-ability-context.md
@@ -1618,65 +1618,6 @@ startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions):
  }
  ```

-## AbilityContext.requestPermissionsFromUser
-
-requestPermissionsFromUser(permissions: Array&lt;string&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void;
-
-拉起弹窗请求用户授权（callback形式）。
-
-**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
-
-**参数：**
-
-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| permissions | Array&lt;string&gt; | 是 | 权限列表。 |
-| callback | AsyncCallback&lt;[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)&gt; | 是 | 回调函数，返回接口调用是否成功的结果。 |
-
-**示例：**
-
-  ```ts
-       var permissions=['com.example.permission']
-       this.context.requestPermissionsFromUser(permissions,(result) => {
-       console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
-  });
-
-  ```
-
-
-## AbilityContext.requestPermissionsFromUser
-
-requestPermissionsFromUser(permissions: Array&lt;string&gt;) : Promise&lt;PermissionRequestResult&gt;;
-
-拉起弹窗请求用户授权（promise形式）。
-
-**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
-
-**参数：**
-
-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| permissions | Array&lt;string&gt; | 是 | 权限列表。 |
-
-**返回值：**
-
-| 类型 | 说明 |
-| -------- | -------- |
-| Promise&lt;[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)&gt; | 返回一个Promise，包含接口的结果。 |
-
-**示例：**
-
-  ```ts
-   var permissions=['com.example.permission']
-       this.context.requestPermissionsFromUser(permissions).then((data) => {
-      console.log('success:' + JSON.stringify(data));
-  }).catch((error) => {
-      console.log('failed:' + JSON.stringify(error));
-  });
-
-  ```
-
-
 ## AbilityContext.setMissionLabel

 setMissionLabel(label: string, callback:AsyncCallback&lt;void&gt;): void;
@@ -1696,7 +1637,7 @@ setMissionLabel(label: string, callback:AsyncCallback&lt;void&gt;): void;

  ```ts
  this.context.setMissionLabel("test",(result) => {
-      console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
+      console.log('setMissionLabel result:' + JSON.stringify(result));
  });
  ```


--- a/zh-cn/application-dev/reference/apis/js-apis-abilityAccessCtrl.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-abilityAccessCtrl.md
@@ -556,6 +556,95 @@ promise.then(data => {
 });
 ```

+### requestPermissionsFromUser<sup>9+</sup>
+
+requestPermissionsFromUser(context: Context, permissions: Array&lt;Permissions&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void;
+
+用于拉起弹框请求用户授权。使用callback异步回调。
+
+**模型约束**：此接口仅可在Stage模型下使用。
+
+**系统能力**: SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| context | Context | 是 | 请求权限的应用ability上下文context。 |
+| permissions | Array&lt;Permissions&gt; | 是 | 权限列表。 |
+| callback | AsyncCallback&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | 是 | 回调函数，返回接口调用是否成功的结果。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)。
+| 错误码ID | 错误信息 |
+| -------- | -------- |
+| 12100001 | Parameter invalid. |
+
+**示例：**
+
+  ```js
+import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
+let atManager = abilityAccessCtrl.createAtManager();
+try {
+    atManager.requestPermissionsFromUser(this.context, ["ohos.permission.MANAGE_DISPOSED_APP_STATUS"], (err, data)=>{
+        console.info("data:" + JSON.stringify(data));
+        console.info("data permissions:" + data.permissions);
+        console.info("data authResults:" + data.authResults);
+    });
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+  ```
+
+### requestPermissionsFromUser<sup>9+</sup>
+
+requestPermissionsFromUser(context: Context, permissions: Array&lt;Permissions&gt;) : Promise&lt;PermissionRequestResult&gt;;
+
+用于拉起弹框请求用户授权。使用promise异步回调。
+
+**模型约束**：此接口仅可在Stage模型下使用。
+
+**系统能力**: SystemCapability.Security.AccessToken
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| context | Context | 是 | 请求权限的应用ability上下文context。 |
+| permissions | Array&lt;Permissions&gt; | 是 | 权限列表。 |
+
+**返回值：**
+
+| 类型 | 说明 |
+| -------- | -------- |
+| Promise&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | 返回一个Promise，包含接口的结果。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)。
+| 错误码ID | 错误信息 |
+| -------- | -------- |
+| 12100001 | Parameter invalid. |
+
+**示例：**
+
+  ```js
+import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
+let atManager = abilityAccessCtrl.createAtManager();
+try {
+    atManager.requestPermissionsFromUser(this.context, ["ohos.permission.MANAGE_DISPOSED_APP_STATUS"]).then((data) => {
+        console.info("data:" + JSON.stringify(data));
+        console.info("data permissions:" + data.permissions);
+        console.info("data authResults:" + data.authResults);
+    }).catch((err) => {
+        console.info("data:" + JSON.stringify(err));
+    })
+} catch(err) {
+    console.log(`catch err->${JSON.stringify(err)}`);
+}
+  ```
+
 ### verifyAccessToken<sup>(deprecated)</sup>

 verifyAccessToken(tokenID: number, permissionName: string): Promise&lt;GrantStatus&gt;

--- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-permissionRequestResult.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-permissionRequestResult.md
 # PermissionRequestResult

-权限请求结果对象，在调用[requestPermissionsFromUser](js-apis-inner-application-uiAbilityContext.md#abilitycontextrequestpermissionsfromuser)申请权限时返回此对象表明此次权限申请的结果。
+权限请求结果对象，在调用[requestPermissionsFromUser](js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9)申请权限时返回此对象表明此次权限申请的结果。

 > **说明：**
 > 
@@ -9,7 +9,7 @@

 ## 属性

-**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core
+**系统能力**：以下各项对应的系统能力均为SystemCapability.Security.AccessToken

 | 名称 | 类型 | 可读 | 可写 | 说明 |
 | -------- | -------- | -------- | -------- | -------- |
@@ -18,23 +18,21 @@

 ## 使用说明

-通过AbilityContext实例来获取。
+通过atManager实例来获取。

 **示例：**
 ```ts
-import UIAbility from '@ohos.app.ability.UIAbility'
-export default class MainAbility extends UIAbility {
-  onWindowStageCreate(windowStage) {
-    var permissions = ['com.example.permission']
-    var permissionRequestResult;
-    this.context.requestPermissionsFromUser(permissions, (err, result) => {
-      if (err) {
-        console.log('requestPermissionsFromUserError: ' + JSON.stringify(err));
-      } else {
-        permissionRequestResult = result;
-        console.log('permissionRequestResult: ' + JSON.stringify(permissionRequestResult));
-      }    
-    });
-  }
+import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
+let atManager = abilityAccessCtrl.createAtManager();
+try {
+  atManager.requestPermissionsFromUser(this.context, ["ohos.permission.MANAGE_DISPOSED_APP_STATUS"]).then((data) => {
+      console.info("data:" + JSON.stringify(data));
+      console.info("data permissions:" + data.permissions);
+      console.info("data authResults:" + data.authResults);
+  }).catch((err) => {
+      console.info("data:" + JSON.stringify(err));
+  })
+} catch(err) {
+  console.log(`catch err->${JSON.stringify(err)}`);
 }
 ```
\ No newline at end of file
--- a/zh-cn/application-dev/security/accesstoken-guidelines.md
+++ b/zh-cn/application-dev/security/accesstoken-guidelines.md
@@ -18,11 +18,21 @@

 ## 接口说明

-以下仅列举本指导使用的接口，更多说明可以查阅[API参考](../reference/apis/js-apis-ability-context.md)。
+以下仅列举本指导使用的接口，不同模型下使用的拉起权限弹窗的接口有差异，更多说明可以查阅[完整示例](##完整示例)。

+### FA模型
 | 接口名                                                       | 描述                                             |
 | ------------------------------------------------------------ | --------------------------------------------------- |
 | requestPermissionsFromUser(permissions: Array&lt;string&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void; | 拉起弹窗请求用户授权。 |
+> 详细可查阅[API参考](../reference/apis/js-apis-ability-context.md)
+
+
+### Stage模型
+
+| 接口名                                                       | 描述                                             |
+| ------------------------------------------------------------ | --------------------------------------------------- |
+| requestPermissionsFromUser(context: Context, permissions: Array&lt;Permissions&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void; | 拉起弹窗请求用户授权。 |
+> 详细可查阅[API参考](../reference/apis/js-apis-abilityAccessCtrl.md)

 ## 权限申请声明

@@ -149,6 +159,7 @@
 2. 调用requestPermissionsFromUser接口请求权限。运行过程中，该接口会根据应用是否已获得目标权限决定是否拉起动态弹框请求用户授权。
 3. 根据requestPermissionsFromUser接口返回值判断是否已获取目标权限。如果当前已经获取权限，则可以继续正常访问目标接口。

+### FA模型下的示例代码
 ```js
  //ability的onWindowStageCreate生命周期
  onWindowStageCreate() {
@@ -167,7 +178,30 @@

 ```
 > **说明：**
-> 动态授权申请接口的使用详见[API参考](../reference/apis/js-apis-ability-context.md)。
+> FA模型的动态授权申请接口的使用详见[API参考](../reference/apis/js-apis-ability-context.md)。
+
+### stage 模型下的示例代码
+```js
+  import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
+
+  //ability的onWindowStageCreate生命周期
+  onWindowStageCreate() {
+    var context = this.context
+    var AtManager = abilityAccessCtrl.createAtManager();
+    //requestPermissionsFromUser会判断权限的授权状态来决定是否唤起弹窗
+      AtManager.requestPermissionsFromUser(context, ["ohos.permission.MANAGE_DISPOSED_APP_STATUS"]).then((data) => {
+        console.log("data type:" + typeof(data));
+        console.log("data:" + data);
+        console.log("data permissions:" + data.permissions);
+        console.log("data result:" + data.authResults);
+      }).catch((err) => {
+          console.error('Failed to start ability', err.code);
+      })
+  }
+
+```
+> **说明：**
+> stage模型的动态授权申请接口的使用详见[API参考](../reference/apis/js-apis-abilityAccessCtrl.md)。

 ## user_grant权限预授权
 当前正常情况下，user_grant类型的权限默认不授权，需要时应通过拉起弹框由用户确认是否授予。对于一些预置应用，比如截屏应用，不希望出现弹框，则可以通过预授权的方式完成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类型权限授权。当前仅支持预置应用配置该文件。