caochunlei1@huawei.com

Signed-off-by: Ncaochunlei <caochunlei1@huawei.com>

zh-cn/application-dev/reference/apis/js-apis-app-ability-dialogRequest.md

+# @ohos.app.ability.dialogRequest (dialogRequest模块)
+
+dialogRequest模块用于处理模态弹框的能力，包括获取RequestInfo（用于绑定模态弹框）、获取RequestCallback（用于设置结果）。
+模态弹框是指一个系统弹出框，其特点在于：该弹出框会拦截弹框之下的页面的鼠标、键盘、触屏等事件，销毁该弹框，才能操作下面的页面。
+
+> **说明：**
+>
+>  - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+>  - 本模块接口在ServiceExtensionAbility下使用，如果ServiceExtensionAbility实现了模态弹框，则可以使用本模块的接口获取请求方的RequestInfo、RequestCallback并返回请求结果。
+
+## 导入模块
+
+```js
+import dialogRequest from '@ohos.app.ability.dialogRequest';
+```
+
+## dialogRequest.getRequestInfo
+
+getRequestInfo(want: Want): RequestInfo
+
+从Want中获取请求方的RequestInfo。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 名称 | 类型   | 必填 | 描述                        |
+| ---- | ------ | ---- | --------------------------- |
+| want  | [Want](js-apis-application-want.md) | 是   | 表示发起方请求弹框时传入的want信息。 |
+
+**返回值：**
+
+| 类型   | 说明                     |
+| ------ | ------------------------ |
+| [RequestInfo](#requestinfo) | 请求方RequestInfo,用于绑定模态窗口。 |
+
+**示例：**
+
+```ts
+   import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
+   import rpc from '@ohos.rpc';
+   import dialogRequest from '@ohos.app.ability.dialogRequest';
+
+   export default class ServiceExtAbility extends ServiceExtensionAbility {
+     onCreate(want) {
+       console.info(TAG, `onCreate, want: ${want.abilityName}`);
+     }
+
+     onRequest(want, startId) {
+       console.info(TAG, `onRequest, want: ${want.abilityName}`);
+       try {
+            var requestInfo = dialogRequest.getRequestInfo(want)
+        } catch(err) {
+            console.error('getRequestInfo err= ' + JSON.stringify(err))
+        }
+     }
+
+     onConnect(want) {
+       console.info(TAG, `onConnect, want: ${want.abilityName}`);
+     }
+
+     onDisconnect(want) {
+       console.info(TAG, `onDisconnect, want: ${want.abilityName}`);
+     }
+
+     onDestroy() {
+       console.info(TAG, `onDestroy`);
+     }
+   }
+   ```
+
+## dialogRequest.getRequestCallback
+
+getRequestCallback(want: Want): RequestCallback
+
+从Want中获取请求方的RequestCallback。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 名称 | 类型   | 必填 | 描述                        |
+| ---- | ------ | ---- | --------------------------- |
+| want  | [Want](js-apis-application-want.md) | 是   | 表示发起方请求弹框时传入的want信息。 |
+
+**返回值：**
+
+| 类型   | 说明                     |
+| ------ | ------------------------ |
+| [RequestCallback](#requestcallback) | 请求方RequestCallback,用于设置返回结果。 |
+
+**示例：**
+
+```ts
+   import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
+   import rpc from '@ohos.rpc';
+   import dialogRequest from '@ohos.app.ability.dialogRequest';
+
+   export default class ServiceExtAbility extends ServiceExtensionAbility {
+     onCreate(want) {
+       console.info(TAG, `onCreate, want: ${want.abilityName}`);
+     }
+
+     onRequest(want, startId) {
+       console.info(TAG, `onRequest, want: ${want.abilityName}`);
+       try {
+            var requestCallback = dialogRequest.getRequestCallback(want)
+        } catch(err) {
+            console.error('getRequestInfo err= ' + JSON.stringify(err))
+        }
+     }
+
+     onConnect(want) {
+       console.info(TAG, `onConnect, want: ${want.abilityName}`);
+     }
+
+     onDisconnect(want) {
+       console.info(TAG, `onDisconnect, want: ${want.abilityName}`);
+     }
+
+     onDestroy() {
+       console.info(TAG, `onDestroy`);
+     }
+   }
+   ```
+
+## RequestInfo
+
+表示发起方请求信息，作为窗口绑定模态弹框的入参。
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
+
+**示例：**
+
+```ts
+   import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
+   import rpc from '@ohos.rpc';
+   import dialogRequest from '@ohos.app.ability.dialogRequest';
+   import window from '@ohos.window';
+
+   export default class ServiceExtAbility extends ServiceExtensionAbility {
+     onCreate(want) {
+       console.info(TAG, `onCreate, want: ${want.abilityName}`);
+     }
+
+     onRequest(want, startId) {
+       console.info(TAG, `onRequest, want: ${want.abilityName}`);
+       try {
+            var requestInfo = dialogRequest.getRequestInfo(want)
+            window.bindDialogTarget(requestInfo, () => {
+                console.info('Dialog Window Need Destroy.');
+            }, (err) => {
+                if (err.code) {
+                    console.error('Failed to bind dialog target. Cause:' + JSON.stringify(err));
+                    return;
+                }
+                console.info('Succeeded in binding dialog target.');
+            });
+        } catch(err) {
+            console.error('getRequestInfo err= ' + JSON.stringify(err))
+        }
+     }
+
+     onConnect(want) {
+       console.info(TAG, `onConnect, want: ${want.abilityName}`);
+     }
+
+     onDisconnect(want) {
+       console.info(TAG, `onDisconnect, want: ${want.abilityName}`);
+     }
+
+     onDestroy() {
+       console.info(TAG, `onDestroy`);
+     }
+   }
+   ```
+
+## ResultCode
+
+模态弹框请求结果码。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore。
+
+| 名称      | 值          | 说明     |
+| ------------ | ------------------ | ---------------------- |
+| RESULT_OK            | 0          | 表示成功。          |
+| RESULT_CANCEL        | 1          | 表示失败。          |
+
+## RequestResult
+模态弹框请求结果，当前只包含结果码，即RequestResult只当前只有ResultCode这一个成员。
+
+## 属性
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
+
+| 名称 | 类型 | 可读 | 可写 | 说明 |
+| -------- | -------- | -------- | -------- | -------- |
+| result | [ResultCode](#resultcode) | 是 | 是 | 表示结果码。 |
+
+## RequestCallback
+
+用于设置模态弹框请求结果的callback接口。
+
+### RequestCallback.setRequestResult
+
+setRequestResult(result: RequestResult): void;
+
+设置请求结果
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| result | [RequestResult](#requestresult) | 是 | 模态弹框请求结果信息。 |
+
+**错误码：**
+
+| 错误码ID | 错误信息 |
+| ------- | -------------------------------- |
+| 401 | If the input parameter is not valid parameter. |
+
+以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。
+
+**示例：**
+
+```ts
+   import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
+   import rpc from '@ohos.rpc';
+   import dialogRequest from '@ohos.app.ability.dialogRequest';
+
+   export default class ServiceExtAbility extends ServiceExtensionAbility {
+     onCreate(want) {
+       console.info(TAG, `onCreate, want: ${want.abilityName}`);
+     }
+
+     onRequest(want, startId) {
+       console.info(TAG, `onRequest, want: ${want.abilityName}`);
+       try {
+            var requestCallback = dialogRequest.getRequestCallback(want);
+            let myResult = {
+                result : dialogRequest.ResultCode.RESULT_CANCEL,
+            };
+            requestCallback.setRequestResult(myResult);
+        } catch(err) {
+            console.error('getRequestInfo err= ' + JSON.stringify(err))
+        }
+     }
+
+     onConnect(want) {
+       console.info(TAG, `onConnect, want: ${want.abilityName}`);
+     }
+
+     onDisconnect(want) {
+       console.info(TAG, `onDisconnect, want: ${want.abilityName}`);
+     }
+
+     onDestroy() {
+       console.info(TAG, `onDestroy`);
+     }
+   }
+  ```
\ No newline at end of file

zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md

@@ -2123,3 +2123,105 @@ isTerminating(): boolean;
   let isTerminating = this.context.isTerminating();
   console.log('ability state :' + isTerminating);
   ```
+
+## UIAbilityContext.requestDialogService
+
+requestDialogService(want: Want, result: AsyncCallback<dialogRequest.RequestResult>): void;
+
+启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后，应用弹出模态弹框，通过调用[setRequestResult](js-apis-app-ability-dialogRequest.md#requestcallbacksetrequestresult)接口返回结果给调用者。
+
+使用规则：
+ - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。
+ - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。
+ - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| want |[Want](js-apis-application-want.md) | 是 | 启动ServiceExtensionAbility的want信息。 |
+| result | AsyncCallback<[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md)> | 是 | 执行结果回调函数。 |
+
+**示例：**
+
+  ```ts
+  import dialogRequest from '@ohos.app.ability.dialogRequest';
+
+  let want = {
+    deviceId: "",
+    bundleName: "com.example.myapplication",
+    abilityName: "AuthAccountServiceExtension"
+  };
+
+  try {
+    this.context.requestDialogService(want, (error, result) => {
+      if (error && error.code) {
+        // 处理业务逻辑错误
+        console.log('requestDialogService failed, error.code: ' + JSON.stringify(error.code) +
+        ' error.message: ' + JSON.stringify(error.message));
+        return;
+      }
+      // 执行正常业务
+      console.log("requestDialogService succeed, result = " + JSON.stringify(result));
+    });
+  } catch (paramError) {
+    // 处理入参错误异常
+    console.log('requestDialogService failed, error.code: ' + JSON.stringify(paramError.code) +
+    ' error.message: ' + JSON.stringify(paramError.message));
+  }
+  ```
+
+  ## UIAbilityContext.requestDialogService
+
+requestDialogService(want: Want): Promise<dialogRequest.RequestResult>;
+
+启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后，应用弹出模态弹框，通过调用[setRequestResult](js-apis-app-ability-dialogRequest.md#requestcallbacksetrequestresult)接口返回结果给调用者（promise形式）。
+
+使用规则：
+ - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。
+ - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。
+ - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。
+
+**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| want | [Want](js-apis-application-want.md) | 是 | 启动ServiceExtensionAbility的want信息。 |
+
+
+**返回值：**
+
+| 类型 | 说明 |
+| -------- | -------- |
+| Promise<[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md)> | Promise形式返回执行结果。
+
+**示例：**
+
+  ```ts
+import dialogRequest from '@ohos.app.ability.dialogRequest';
+
+let want = {
+    bundleName: "com.example.myapplication",
+    abilityName: "AuthAccountServiceExtension"
+};
+
+try {
+    this.context.requestDialogService(want)
+        .then((result) => {
+        // 执行正常业务
+        console.log("requestDialogService succeed, result = " + JSON.stringify(result));
+    })
+        .catch((error) => {
+        // 处理业务逻辑错误
+        console.log('requestDialogService failed, error= ' + JSON.stringify(error));
+    });
+} catch (paramError) {
+    // 处理入参错误异常
+    console.log('requestDialogService failed, error.code: ' + JSON.stringify(paramError.code) +
+                ' error.message: ' + JSON.stringify(paramError.message));
+}
+  ```