1# @ohos.app.ability.dialogRequest (dialogRequest) 2 3The dialogRequest module provides APIs related to modal dialog box processing, including obtaining the request information (used to bind a modal dialog box) and request callback (used to set the request result). 4 5A modal dialog box is a system-level dialog box that blocks interactions such as mouse clicks, keyboard input, and touch events on the underlying page. The page can only be interacted with after the modal dialog box is closed. 6 7> **NOTE** 8> 9> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 10> - The APIs provided by this module are used in ServiceExtensionAbilities. For a ServiceExtensionAbility that implements modal dialog boxes, you can use the APIs to obtain the request information and request callback and return the request result. 11 12## Modules to Import 13 14```ts 15import { dialogRequest } from '@kit.AbilityKit'; 16``` 17 18## dialogRequest.getRequestInfo 19 20getRequestInfo(want: Want): RequestInfo 21 22> **NOTE** 23> 24> This API can be used by a ServiceExtensionAbility. If the ServiceExtensionAbility implements modal dialog boxes, the request information can be obtained from Want. If this API is used in other scenarios, no return value is obtained. 25 26Obtains the request information from Want. 27 28**System capability**: SystemCapability.Ability.AbilityRuntime.Core 29 30**Parameters** 31 32| Name| Type | Mandatory| Description | 33| ---- | ------ | ---- | --------------------------- | 34| want | [Want](js-apis-app-ability-want.md) | Yes | Want passed in the request for a modal dialog box.| 35 36**Return value** 37 38| Type | Description | 39| ------ | ------------------------ | 40| [RequestInfo](#requestinfo) | RequestInfo object obtained, which is used to bind a modal dialog box.| 41 42**Error codes** 43 44For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 45 46| ID| Error Message| 47| ------- | -------- | 48| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 49 50**Example** 51 52```ts 53import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit'; 54 55export default class EntryAbility extends UIAbility { 56 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 57 try { 58 let requestInfo = dialogRequest.getRequestInfo(want); 59 } catch (err) { 60 console.error(`getRequestInfo err= ${JSON.stringify(err)}`); 61 } 62 } 63} 64``` 65 66## dialogRequest.getRequestCallback 67 68getRequestCallback(want: Want): RequestCallback 69 70Obtains the request callback from Want. 71 72> **NOTE** 73> 74> This API can be used by a ServiceExtensionAbility. If the ServiceExtensionAbility implements modal dialog boxes, the request callback can be obtained from Want. If this API is used in other scenarios, no return value is obtained. 75 76**System capability**: SystemCapability.Ability.AbilityRuntime.Core 77 78**Parameters** 79 80| Name| Type | Mandatory| Description | 81| ---- | ------ | ---- | --------------------------- | 82| want | [Want](js-apis-app-ability-want.md) | Yes | Want passed in the request for a modal dialog box.| 83 84**Return value** 85 86| Type | Description | 87| ------ | ------------------------ | 88| [RequestCallback](#requestcallback) | RequestCallback object obtained, which is used to set the return result.| 89 90**Error codes** 91 92For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 93 94| ID| Error Message| 95| ------- | -------- | 96| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 97 98**Example** 99 100```ts 101import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit'; 102 103export default class EntryAbility extends UIAbility { 104 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 105 try { 106 let requestCallback = dialogRequest.getRequestCallback(want); 107 } catch(err) { 108 console.error(`getRequestInfo err= ${JSON.stringify(err)}`); 109 } 110 } 111} 112``` 113 114## WindowRect<sup>10+</sup> 115 116Defines the location attributes of a modal dialog box. 117 118**Model restriction**: This API can be used only in the stage model. 119 120**System capability**: SystemCapability.Ability.AbilityRuntime.Core 121 122| Name| Type | Read-only| Optional| Description | 123| ---- | ------ | ---- | ----| --------------------------- | 124| left | number | No | No|X-coordinate of the upper left corner of the dialog box.| 125| top | number | No | No|Y-coordinate of the upper left corner of the dialog box.| 126| width | number | No | No| Width of the dialog box, in px.| 127| height | number | No | No|Height of the dialog box, in px.| 128 129## RequestInfo 130 131Defines the request information, which is used as an input parameter for binding the modal dialog box. 132 133**Model restriction**: This API can be used only in the stage model. 134 135**System capability**: SystemCapability.Ability.AbilityRuntime.Core 136 137| Name | Type | Read-only| Optional | Description | 138| ------------ | --------| ------ | ----- | ----------------- | 139| windowRect<sup>10+</sup> | [WindowRect](#windowrect10) | No| Yes | Location attributes of a modal dialog box. | 140 141**Example** 142 143```ts 144import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit'; 145 146export default class EntryAbility extends UIAbility { 147 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 148 try { 149 let requestInfo = dialogRequest.getRequestInfo(want); 150 console.info(`getRequestInfo windowRect=, ${JSON.stringify(requestInfo.windowRect)}` ); 151 } catch(err) { 152 console.error(`getRequestInfo err= ${JSON.stringify(err)}`); 153 } 154 } 155} 156``` 157 158## ResultCode 159 160Enumerates the result codes of the request for the modal dialog box. 161 162**System capability**: SystemCapability.Ability.AbilityRuntime.Core 163 164| Name | Value | Description | 165| ------------ | ------------------ | ---------------------- | 166| RESULT_OK | 0 | The request succeeds. | 167| RESULT_CANCEL | 1 | The request fails. | 168 169## RequestResult 170Defines the result of the request for the modal dialog box. It contains **ResultCode** and **ResultWant**. 171 172### Properties 173 174**Model restriction**: This API can be used only in the stage model. 175 176**System capability**: SystemCapability.Ability.AbilityRuntime.Core 177 178| Name| Type| Read-only| Optional| Description| 179| -------- | -------- | -------- | -------- | -------- | 180| result | [ResultCode](#resultcode) | No| No| Result code of the request.| 181| want<sup>10+</sup> | [Want](js-apis-app-ability-want.md) | No| Yes| Want information, such as the ability name and bundle name.| 182 183## RequestCallback 184 185Provides a callback for setting the modal dialog box request result. 186 187**Model restriction**: This API can be used only in the stage model. 188 189### RequestCallback.setRequestResult 190 191setRequestResult(result: RequestResult): void 192 193Sets the result of the request for the modal dialog box. 194 195**Model restriction**: This API can be used only in the stage model. 196 197**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore 198 199**Parameters** 200 201| Name| Type| Mandatory| Description| 202| -------- | -------- | -------- | -------- | 203| result | [RequestResult](#requestresult) | Yes| Request result to set.| 204 205**Error codes** 206 207For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 208 209| ID| Error Message| 210| ------- | -------- | 211| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 212 213**Example** 214 215```ts 216import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit'; 217 218export default class EntryAbility extends UIAbility { 219 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 220 try { 221 let requestCallback = dialogRequest.getRequestCallback(want); 222 let myResult: dialogRequest.RequestResult = { 223 result : dialogRequest.ResultCode.RESULT_CANCEL, 224 }; 225 requestCallback.setRequestResult(myResult); 226 } catch(err) { 227 console.error(`getRequestInfo err= ${JSON.stringify(err)}`); 228 } 229 } 230} 231``` 232