diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-dialogRequest.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-dialogRequest.md new file mode 100644 index 0000000000000000000000000000000000000000..557a9b69837c19c6aaa3b95888cc40a8c7db570e --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-dialogRequest.md @@ -0,0 +1,262 @@ +# @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 diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md index 0a24658cf47337925f77eaec288655e4384cd7c3..d8d636c72e57b581a41dcfcafbcabb7342b9f49a 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md @@ -2132,3 +2132,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)); +} + ```