1# @ohos.app.ability.dialogRequest (dialogRequest模块)
2
3dialogRequest模块用于处理模态弹框的能力，包括获取RequestInfo（用于绑定模态弹框）、获取RequestCallback（用于设置结果）。
4模态弹框是指一个系统弹出框，其特点在于：该弹出框会拦截弹框之下的页面的鼠标、键盘、触屏等事件，销毁该弹框，才能操作下面的页面。
5
6> **说明：**
7>
8>  - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
9>  - 本模块接口可以在ServiceExtensionAbility下使用，如果ServiceExtensionAbility实现了模态弹框，则可以使用本模块的接口获取请求方的RequestInfo、RequestCallback并返回请求结果。
10
11## 导入模块
12
13```ts
14import { dialogRequest } from '@kit.AbilityKit';
15```
16
17## dialogRequest.getRequestInfo
18
19getRequestInfo(want: Want): RequestInfo
20
21> **说明：**
22>
23>  该接口可以在ServiceExtensionAbility下使用，如果ServiceExtensionAbility实现了模态弹框，则能从Want中获取请求方的RequestInfo。其他场景使用该接口，均无法获取返回值。
24
25从Want中获取请求方的RequestInfo。
26
27**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
28
29**参数：**
30
31| 参数名 | 类型   | 必填 | 说明                        |
32| ---- | ------ | ---- | --------------------------- |
33| want  | [Want](js-apis-app-ability-want.md) | 是   | 表示发起方请求弹框时传入的want信息。 |
34
35**返回值：**
36
37| 类型   | 说明                     |
38| ------ | ------------------------ |
39| [RequestInfo](#requestinfo) | 请求方RequestInfo,用于绑定模态窗口。 |
40
41**错误码**：
42
43以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
44
45| 错误码ID | 错误信息 |
46| ------- | -------- |
47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
48
49**示例：**
50
51```ts
52import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
53
54export default class EntryAbility extends UIAbility {
55  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
56    try {
57      let requestInfo = dialogRequest.getRequestInfo(want);
58    } catch (err) {
59      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
60    }
61  }
62}
63```
64
65## dialogRequest.getRequestCallback
66
67getRequestCallback(want: Want): RequestCallback
68
69从Want中获取请求方的RequestCallback。
70
71> **说明：**
72>
73>  该接口可以在ServiceExtensionAbility下使用，如果ServiceExtensionAbility实现了模态弹框，则能从Want中获取请求方的RequestCallback。其他场景使用该接口，均无法获取返回值。
74
75**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
76
77**参数：**
78
79| 参数名 | 类型   | 必填 | 说明                        |
80| ---- | ------ | ---- | --------------------------- |
81| want  | [Want](js-apis-app-ability-want.md) | 是   | 表示发起方请求弹框时传入的want信息。 |
82
83**返回值：**
84
85| 类型   | 说明                     |
86| ------ | ------------------------ |
87| [RequestCallback](#requestcallback) | 请求方RequestCallback,用于设置返回结果。 |
88
89**错误码**：
90
91以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
92
93| 错误码ID | 错误信息 |
94| ------- | -------- |
95| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
96
97**示例：**
98
99```ts
100import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
101
102export default class EntryAbility extends UIAbility {
103  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
104    try {
105      let requestCallback = dialogRequest.getRequestCallback(want);
106    } catch(err) {
107      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
108    }
109  }
110}
111```
112
113## WindowRect<sup>10+</sup>
114
115表示模态弹框的属性。
116
117**模型约束**：此接口仅可在Stage模型下使用。
118
119**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
120
121| 名称 | 类型   | 必填 | 说明                        |
122| ---- | ------ | ---- | --------------------------- |
123| left  | number | 是   | 弹框边框的左上角的X坐标。 |
124| top  | number | 是   | 弹框边框的左上角的Y坐标。 |
125| width  | number | 是   | 弹框的宽度。 |
126| height  | number | 是   | 弹框的高度。 |
127
128## RequestInfo
129
130表示发起方请求信息，作为窗口绑定模态弹框的入参。
131
132**模型约束**：此接口仅可在Stage模型下使用。
133
134**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
135
136| 名称      | 类型       | 必填   | 说明     |
137| ------------ | ------------------| ------ | ---------------------- |
138| windowRect<sup>10+</sup>            | [WindowRect](#windowrect10)    | 否   | 表示模态弹框的位置属性。          |
139
140**示例：**
141
142```ts
143import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
144
145export default class EntryAbility extends UIAbility {
146  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
147    try {
148      let requestInfo = dialogRequest.getRequestInfo(want);
149      console.info(`getRequestInfo windowRect=, ${JSON.stringify(requestInfo.windowRect)}` );
150    } catch(err) {
151      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
152    }
153  }
154}
155```
156
157## ResultCode
158
159模态弹框请求结果码。
160
161**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
162
163| 名称      | 值          | 说明     |
164| ------------ | ------------------ | ---------------------- |
165| RESULT_OK            | 0          | 表示成功。          |
166| RESULT_CANCEL        | 1          | 表示失败。          |
167
168## RequestResult
169模态弹框请求结果，包含结果码ResultCode和请求结果ResultWant。
170
171### 属性
172
173**模型约束**：此接口仅可在Stage模型下使用。
174
175**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
176
177| 名称 | 类型 | 只读 | 可选 | 说明 |
178| -------- | -------- | -------- | -------- | -------- |
179| result | [ResultCode](#resultcode) | 否 | 否 | 表示结果码。 |
180| want<sup>10+</sup> | [Want](js-apis-app-ability-want.md)  | 否 | 是 | 表示Want类型信息，如ability名称，包名等。 |
181
182## RequestCallback
183
184用于设置模态弹框请求结果的callback接口。
185
186**模型约束**：此接口仅可在Stage模型下使用。
187
188### RequestCallback.setRequestResult
189
190setRequestResult(result: RequestResult): void
191
192设置请求结果
193
194**模型约束**：此接口仅可在Stage模型下使用。
195
196**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore
197
198**参数：**
199
200| 参数名 | 类型 | 必填 | 说明 |
201| -------- | -------- | -------- | -------- |
202| result | [RequestResult](#requestresult) | 是 | 模态弹框请求结果信息。 |
203
204**错误码**：
205
206以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
207
208| 错误码ID | 错误信息 |
209| ------- | -------- |
210| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
211
212**示例：**
213
214```ts
215import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
216
217export default class EntryAbility extends UIAbility {
218  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
219    try {
220      let requestCallback = dialogRequest.getRequestCallback(want);
221      let myResult: dialogRequest.RequestResult = {
222        result : dialogRequest.ResultCode.RESULT_CANCEL,
223      };
224      requestCallback.setRequestResult(myResult);
225    } catch(err) {
226      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
227    }
228  }
229}
230```