1# @ohos.promptAction (弹窗)
2
3创建并显示文本提示框、对话框和操作菜单。
4
5> **说明:**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8>
9> 该模块不支持在[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)的文件声明处使用,即不能在UIAbility的生命周期中调用,需要在创建组件实例后使用。
10>
11> 本模块功能依赖UI的执行上下文,不可在UI上下文不明确的地方使用,参见[UIContext](js-apis-arkui-UIContext.md#uicontext)说明。建议在<!--Del-->除[ServiceExtension](../../application-models/serviceextensionability.md)等<!--DelEnd-->无UI界面的场景外,均使用UIContext中的弹窗方法。
12>
13> 从API version 10开始,可以通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getPromptAction](js-apis-arkui-UIContext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](js-apis-arkui-UIContext.md#promptaction)对象。
14
15## 导入模块
16
17```ts
18import { promptAction } from '@kit.ArkUI';
19```
20
21## promptAction.showToast
22
23showToast(options: ShowToastOptions): void
24
25创建并显示文本提示框。
26
27**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
28
29**系统能力:** SystemCapability.ArkUI.ArkUI.Full
30
31**参数:**
32
33| 参数名     | 类型                                    | 必填   | 说明      |
34| ------- | ------------------------------------- | ---- | ------- |
35| options | [ShowToastOptions](#showtoastoptions) | 是    | 文本弹窗选项。 |
36
37**错误码:**
38
39以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。
40
41| 错误码ID   | 错误信息 |
42| --------- | ------- |
43| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.   |
44| 100001    | Internal error. |
45
46**示例:**
47
48```ts
49import { promptAction } from '@kit.ArkUI'
50import { BusinessError } from '@kit.BasicServicesKit';
51
52@Entry
53@Component
54struct toastExample {
55  build() {
56    Column() {
57      Button('Show toast').fontSize(20)
58        .onClick(() => {
59          try {
60            promptAction.showToast({
61              message: 'Hello World',
62              duration: 2000
63            });
64          } catch (error) {
65            let message = (error as BusinessError).message
66            let code = (error as BusinessError).code
67            console.error(`showToast args error code is ${code}, message is ${message}`);
68          };
69        })
70    }.height('100%').width('100%').justifyContent(FlexAlign.Center)
71  }
72}
73```
74API version 11及之前Toast样式。
75
76![zh-cn_image_0001](figures/toast-api11.gif)
77
78API version 12及之后Toast样式。
79
80![zh-cn_image_0001](figures/toast-api12.gif)
81
82## promptAction.showDialog
83
84showDialog(options: ShowDialogOptions): Promise&lt;ShowDialogSuccessResponse&gt;
85
86创建并显示对话框,对话框响应后异步返回结果。
87
88**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
89
90**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
91
92**参数:**
93
94| 参数名     | 类型                                      | 必填   | 说明     |
95| ------- | --------------------------------------- | ---- | ------ |
96| options | [ShowDialogOptions](#showdialogoptions) | 是    | 对话框选项。 |
97
98**返回值:**
99
100| 类型                                       | 说明       |
101| ---------------------------------------- | -------- |
102| Promise&lt;[ShowDialogSuccessResponse](#showdialogsuccessresponse)&gt; | 对话框响应结果。 |
103
104**错误码:**
105
106以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。
107
108| 错误码ID   | 错误信息 |
109| --------- | ------- |
110| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.   |
111| 100001    | Internal error. |
112
113**示例:**
114
115```ts
116import { promptAction } from '@kit.ArkUI'
117import { BusinessError } from '@kit.BasicServicesKit';
118
119try {
120  promptAction.showDialog({
121    title: 'Title Info',
122    message: 'Message Info',
123    buttons: [
124      {
125        text: 'button1',
126        color: '#000000'
127      },
128      {
129        text: 'button2',
130        color: '#000000'
131      }
132    ],
133  })
134    .then(data => {
135      console.info('showDialog success, click button: ' + data.index);
136    })
137    .catch((err:Error) => {
138      console.info('showDialog error: ' + err);
139    })
140} catch (error) {
141  let message = (error as BusinessError).message
142  let code = (error as BusinessError).code
143  console.error(`showDialog args error code is ${code}, message is ${message}`);
144};
145```
146
147![zh-cn_image_0002](figures/zh-cn_image_0002.gif)
148
149## promptAction.showDialog
150
151showDialog(options: ShowDialogOptions, callback: AsyncCallback&lt;ShowDialogSuccessResponse&gt;):void
152
153创建并显示对话框,对话框响应结果异步返回。
154
155**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
156
157**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
158
159**参数:**
160
161| 参数名      | 类型                                       | 必填   | 说明           |
162| -------- | ---------------------------------------- | ---- | ------------ |
163| options  | [ShowDialogOptions](#showdialogoptions)  | 是    | 页面显示对话框信息描述。 |
164| callback | AsyncCallback&lt;[ShowDialogSuccessResponse](#showdialogsuccessresponse)&gt; | 是    | 对话框响应结果回调。   |
165
166**错误码:**
167
168以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。
169
170| 错误码ID   | 错误信息 |
171| --------- | ------- |
172| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.   |
173| 100001    | Internal error. |
174
175**示例:**
176
177```ts
178import { promptAction } from '@kit.ArkUI';
179import { BusinessError } from '@kit.BasicServicesKit';
180
181try {
182  promptAction.showDialog({
183    title: 'showDialog Title Info',
184    message: 'Message Info',
185    buttons: [
186      {
187        text: 'button1',
188        color: '#000000'
189      },
190      {
191        text: 'button2',
192        color: '#000000'
193      }
194    ]
195  }, (err, data) => {
196    if (err) {
197      console.info('showDialog err: ' + err);
198      return;
199    }
200    console.info('showDialog success callback, click button: ' + data.index);
201  });
202} catch (error) {
203  let message = (error as BusinessError).message
204  let code = (error as BusinessError).code
205  console.error(`showDialog args error code is ${code}, message is ${message}`);
206};
207```
208
209![zh-cn_image_0004](figures/zh-cn_image_0004.gif)
210
211当弹窗的showInSubWindow属性为true时,弹窗可显示在窗口外。
212
213```ts
214import { promptAction } from '@kit.ArkUI';
215import { BusinessError } from '@kit.BasicServicesKit';
216
217try {
218  promptAction.showDialog({
219    title: 'showDialog Title Info',
220    message: 'Message Info',
221    isModal: true,
222    showInSubWindow: true,
223    buttons: [
224      {
225        text: 'button1',
226        color: '#000000'
227      },
228      {
229        text: 'button2',
230        color: '#000000'
231      }
232    ]
233  }, (err, data) => {
234    if (err) {
235      console.info('showDialog err: ' + err);
236      return;
237    }
238    console.info('showDialog success callback, click button: ' + data.index);
239  });
240} catch (error) {
241  let message = (error as BusinessError).message
242  let code = (error as BusinessError).code
243  console.error(`showDialog args error code is ${code}, message is ${message}`);
244};
245```
246
247![zh-cn_image_0002_showinsubwindow](figures/zh-cn_image_0002_showinsubwindow.jpg)
248
249
250
251## promptAction.showActionMenu
252
253showActionMenu(options: ActionMenuOptions, callback: AsyncCallback&lt;ActionMenuSuccessResponse&gt;):void
254
255创建并显示操作菜单,菜单响应结果异步返回。
256
257**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
258
259**系统能力:** SystemCapability.ArkUI.ArkUI.Full260
261**参数:**
262
263| 参数名      | 类型                                       | 必填   | 说明        |
264| -------- | ---------------------------------------- | ---- | --------- |
265| options  | [ActionMenuOptions](#actionmenuoptions)  | 是    | 操作菜单选项。   |
266| callback | AsyncCallback&lt;[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 是    | 菜单响应结果回调。 |
267
268**错误码:**
269
270以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。
271
272| 错误码ID   | 错误信息 |
273| --------- | ------- |
274| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.   |
275| 100001    | Internal error. |
276
277**示例:**
278
279```ts
280import { promptAction } from '@kit.ArkUI';
281import { BusinessError } from '@kit.BasicServicesKit';
282
283try {
284  promptAction.showActionMenu({
285    title: 'Title Info',
286    buttons: [
287      {
288        text: 'item1',
289        color: '#666666'
290      },
291      {
292        text: 'item2',
293        color: '#000000'
294      },
295    ]
296  }, (err, data) => {
297    if (err) {
298      console.info('showActionMenu err: ' + err);
299      return;
300    }
301    console.info('showActionMenu success callback, click button: ' + data.index);
302  })
303} catch (error) {
304  let message = (error as BusinessError).message
305  let code = (error as BusinessError).code
306  console.error(`showActionMenu args error code is ${code}, message is ${message}`);
307};
308```
309
310![zh-cn_image_0005](figures/zh-cn_image_0005.gif)
311
312## promptAction.showActionMenu
313
314showActionMenu(options: ActionMenuOptions): Promise&lt;ActionMenuSuccessResponse&gt;
315
316创建并显示操作菜单,菜单响应后异步返回结果。
317
318**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
319
320**系统能力:** SystemCapability.ArkUI.ArkUI.Full
321
322**参数:**
323
324| 参数名     | 类型                                      | 必填   | 说明      |
325| ------- | --------------------------------------- | ---- | ------- |
326| options | [ActionMenuOptions](#actionmenuoptions) | 是    | 操作菜单选项。 |
327
328**返回值:**
329
330| 类型                                       | 说明      |
331| ---------------------------------------- | ------- |
332| Promise&lt;[ActionMenuSuccessResponse](#actionmenusuccessresponse)&gt; | 菜单响应结果。 |
333
334**错误码:**
335
336以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。
337
338| 错误码ID   | 错误信息 |
339| --------- | ------- |
340| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.   |
341| 100001    | Internal error. |
342
343**示例:**
344
345```ts
346import { promptAction } from '@kit.ArkUI';
347import { BusinessError } from '@kit.BasicServicesKit';
348
349try {
350  promptAction.showActionMenu({
351    title: 'showActionMenu Title Info',
352    buttons: [
353      {
354        text: 'item1',
355        color: '#666666'
356      },
357      {
358        text: 'item2',
359        color: '#000000'
360      },
361    ]
362  })
363    .then(data => {
364      console.info('showActionMenu success, click button: ' + data.index);
365    })
366    .catch((err:Error) => {
367      console.info('showActionMenu error: ' + err);
368    })
369} catch (error) {
370  let message = (error as BusinessError).message
371  let code = (error as BusinessError).code
372  console.error(`showActionMenu args error code is ${code}, message is ${message}`);
373};
374```
375
376![zh-cn_image_0006](figures/zh-cn_image_0006.gif)
377
378## promptAction.openCustomDialog<sup>11+</sup>
379
380openCustomDialog(options: CustomDialogOptions): Promise&lt;number&gt;
381
382打开自定义弹窗。
383
384<!--Del-->不支持在ServiceExtension中使用。<!--DelEnd-->
385
386暂不支持isModal = true与showInSubWindow = true同时使用。
387
388弹窗宽度在设备竖屏时默认为 所在窗口宽度 - 左右margin(16vp,设备为2in1时为40vp),最大默认宽度为400vp。
389
390**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
391
392**系统能力:** SystemCapability.ArkUI.ArkUI.Full
393
394**参数:**
395
396| 参数名  | 类型                                          | 必填 | 说明               |
397| ------- | --------------------------------------------- | ---- | ------------------ |
398| options | [CustomDialogOptions](#customdialogoptions11) | 是   | 自定义弹窗的内容。 |
399
400**返回值:**
401
402| 类型                  | 说明                                  |
403| --------------------- | ------------------------------------- |
404| Promise&lt;number&gt; | 返回供closeCustomDialog使用的对话框id。 |
405
406**错误码:**
407
408以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。
409
410| 错误码ID | 错误信息                           |
411| -------- | ---------------------------------- |
412| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.   |
413| 100001   | Internal error. |
414
415**示例:**
416
417```ts
418import { promptAction } from '@kit.ArkUI'
419import { BusinessError } from '@kit.BasicServicesKit'
420
421@Entry
422@Component
423struct Index {
424  private customDialogComponentId: number = 0
425
426  @Builder
427  customDialogComponent() {
428    Column() {
429      Text('弹窗').fontSize(30)
430      Row({ space: 50 }) {
431        Button("确认").onClick(() => {
432          try {
433            promptAction.closeCustomDialog(this.customDialogComponentId)
434          } catch (error) {
435            let message = (error as BusinessError).message;
436            let code = (error as BusinessError).code;
437            console.error(`closeCustomDialog error code is ${code}, message is ${message}`);
438          }
439        })
440        Button("取消").onClick(() => {
441          try {
442            promptAction.closeCustomDialog(this.customDialogComponentId)
443          } catch (error) {
444            let message = (error as BusinessError).message;
445            let code = (error as BusinessError).code;
446            console.error(`closeCustomDialog error code is ${code}, message is ${message}`);
447          }
448        })
449      }
450    }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween)
451  }
452
453  build() {
454    Row() {
455      Column({ space: 20 }) {
456        Text('组件内弹窗')
457          .fontSize(30)
458          .onClick(() => {
459            promptAction.openCustomDialog({
460              builder: () => {
461                this.customDialogComponent()
462              },
463              onWillDismiss: (dismissDialogAction: DismissDialogAction) => {
464                console.info("reason" + JSON.stringify(dismissDialogAction.reason))
465                console.log("dialog onWillDismiss")
466                if (dismissDialogAction.reason == DismissReason.PRESS_BACK) {
467                  dismissDialogAction.dismiss()
468                }
469                if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) {
470                  dismissDialogAction.dismiss()
471                }
472              }
473            }).then((dialogId: number) => {
474              this.customDialogComponentId = dialogId
475            })
476              .catch((error: BusinessError) => {
477                console.error(`openCustomDialog error code is ${error.code}, message is ${error.message}`)
478              })
479          })
480      }
481      .width('100%')
482    }
483    .height('100%')
484  }
485}
486
487```
488该示例定义了弹窗样式,如宽度、高度、背景色、阴影等等。
489```ts
490import { promptAction } from '@kit.ArkUI'
491
492let customDialogId: number = 0
493
494@Builder
495function customDialogBuilder() {
496  Column() {
497    Text('Custom dialog Message').fontSize(10)
498    Row() {
499      Button("确认").onClick(() => {
500        promptAction.closeCustomDialog(customDialogId)
501      })
502      Blank().width(50)
503      Button("取消").onClick(() => {
504        promptAction.closeCustomDialog(customDialogId)
505      })
506    }
507  }
508}
509
510@Entry
511@Component
512struct Index {
513  @State message: string = 'Hello World'
514
515  @Builder
516  customDialogComponent() {
517    customDialogBuilder()
518  }
519
520  build() {
521    Row() {
522      Column() {
523        Text(this.message)
524          .fontSize(50)
525          .fontWeight(FontWeight.Bold)
526          .onClick(() => {
527            promptAction.openCustomDialog({
528              builder: () => {
529                this.customDialogComponent()
530              },
531              keyboardAvoidMode: KeyboardAvoidMode.NONE,
532              showInSubWindow: false,
533              offset: { dx: 5, dy: 5 },
534              backgroundColor: 0xd9ffffff,
535              cornerRadius: 20,
536              width: '80%',
537              height: 200,
538              borderWidth: 1,
539              borderStyle: BorderStyle.Dashed, //使用borderStyle属性,需要和borderWidth属性一起使用
540              borderColor: Color.Blue, //使用borderColor属性,需要和borderWidth属性一起使用
541              shadow: ({
542                radius: 20,
543                color: Color.Grey,
544                offsetX: 50,
545                offsetY: 0
546              }),
547            }).then((dialogId: number) => {
548              customDialogId = dialogId
549            })
550          })
551      }
552      .width('100%')
553    }
554    .height('100%')
555  }
556}
557```
558![zh-cn_image_0007](figures/zh-cn_image_0007.gif)
559
560## promptAction.closeCustomDialog<sup>11+</sup>
561
562closeCustomDialog(dialogId: number): void
563
564关闭自定义弹窗。
565
566**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
567
568**系统能力:** SystemCapability.ArkUI.ArkUI.Full
569
570**参数:**
571
572| 参数名   | 类型   | 必填 | 说明                             |
573| -------- | ------ | ---- | -------------------------------- |
574| dialogId | number | 是   | openCustomDialog返回的对话框id。 |
575
576**错误码:**
577
578以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。
579
580| 错误码ID | 错误信息                           |
581| -------- | ---------------------------------- |
582| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.   |
583| 100001   | Internal error. |
584
585**示例:**
586
587示例请看[promptAction.openCustomDialog](#promptactionopencustomdialog11)的示例。
588
589## ShowToastOptions
590
591文本提示框的选项。
592
593**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
594
595| 名称                    | 类型                                                         | 必填 | 说明                                                         |
596| ----------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
597| message                 | string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource类型) | 是   | 显示的文本信息。<br>**说明:** <br/>默认字体为'Harmony Sans',不支持设置其他字体。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
598| duration                | number                                                       | 否   | 默认值1500ms,取值区间:1500ms-10000ms。若小于1500ms则取默认值,若大于10000ms则取上限值10000ms。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
599| bottom                  | string&nbsp;\|&nbsp;number                                   | 否   | 设置弹窗底部边框距离导航条的高度,ToastShowMode.TOP_MOST模式下,软键盘拉起时,如果bottom值过小,toast要被软键盘遮挡时,会自动避让至距离软键盘80vp处。ToastShowMode.DEFAULT模式下,软键盘拉起时,会上移软键盘的高度。<br/>默认值:80vp<br/>**说明:** <br/>当底部没有导航条时,bottom为设置弹窗底部边框距离窗口底部的高度。<br/>设置对齐方式alignment后,bottom不生效。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
600| showMode<sup>11+</sup>  | [ToastShowMode](#toastshowmode11)                            | 否   | 设置弹窗是否显示在应用之上。<br>默认值:ToastShowMode.DEFAULT,默认显示在应用内。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
601| alignment<sup>12+</sup> | [Alignment](arkui-ts/ts-appendix-enums.md#alignment)         | 否   | 对齐方式。<br/>默认值:undefined,默认底部偏上位置。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。         |
602| offset<sup>12+</sup>    | [Offset](arkui-ts/ts-types.md#offset)                        | 否   | 在对齐方式上的偏移。<br/>默认值:{ dx: 0, dy: 0 },默认没有偏移。<br/>**说明:** <br/>只支持设置px类型的数值,如需设置vp,可以将vp改成px传入。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
603| backgroundColor<sup>12+</sup>    | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否   | 文本提示框背板颜色。<br/>默认值:Color.Transparent<br/>**说明:** <br/>当设置了backgroundColor为非透明色时,backgroundBlurStyle需要设置为BlurStyle.NONE,否则颜色显示将不符合预期效果。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
604| textColor<sup>12+</sup>    | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否   | 文本提示框文本颜色。<br/>默认值:Color.Black<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
605| backgroundBlurStyle<sup>12+</sup>    | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | 否   | 文本提示框背板模糊材质。<br/>默认值:BlurStyle.COMPONENT_ULTRA_THICK<br/>**说明:** <br/>设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时,则不要设置backgroundColor,否则颜色显示将不符合预期效果。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
606| shadow<sup>12+</sup>    | [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions对象说明)&nbsp;\|&nbsp;[ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否   | 文本提示框背板阴影。<br/>默认值:ShadowStyle.OUTER_DEFAULT_MD<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
607| enableHoverMode<sup>14+</sup>    | boolean                       | 否   | 是否响应悬停态。<br/>默认值:False,默认不响应。<br/>**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。 |
608| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](arkui-ts/ts-appendix-enums.md#hovermodeareatype14)         | 否   | 响应悬停态时,弹窗的显示区域。<br/>默认值:HoverModeAreaType.BOTTOM_SCREEN,默认显示在下半屏。<br/>**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。         |
609
610## ToastShowMode<sup>11+</sup>
611
612设置弹窗显示模式,默认显示在应用内,支持显示在应用之上。
613
614**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
615
616**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
617
618| 名称     | 值   | 说明                   |
619| -------- | ---- | ---------------------- |
620| DEFAULT  | 0    | Toast 显示在应用内。   |
621| TOP_MOST | 1    | Toast 显示在应用之上。 |
622
623## ShowDialogOptions
624
625对话框的选项。
626
627**系统能力:** SystemCapability.ArkUI.ArkUI.Full
628
629| 名称                              | 类型                                                         | 必填 | 说明                                                         |
630| --------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
631| title                             | string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource类型) | 否   | 标题文本。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
632| message                           | string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource类型) | 否   | 内容文本。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
633| buttons                           | Array&lt;[Button](#button)&gt;                               | 否   | 对话框中按钮的数组,结构为:{text:'button',&nbsp;color:&nbsp;'\#666666'},支持大于1个按钮。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
634| alignment<sup>10+</sup>           | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否   | 弹窗在竖直方向上的对齐方式。<br/>默认值:DialogAlignment.Default<br/>**说明**:<br/>若在UIExtension中设置showInSubWindow为true, 弹窗将基于UIExtension的宿主窗口对齐。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
635| offset<sup>10+</sup>              | [Offset](arkui-ts/ts-types.md#offset)                        | 否   | 弹窗相对alignment所在位置的偏移量。<br/>默认值:{&nbsp;dx:&nbsp;0&nbsp;,&nbsp;dy:&nbsp;0&nbsp;}<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
636| maskRect<sup>10+</sup>            | [Rectangle](arkui-ts/ts-methods-alert-dialog-box.md#rectangle8类型说明) | 否   | 弹窗遮蔽层区域,在遮蔽层区域内的事件不透传,在遮蔽层区域外的事件透传。<br/>默认值:{ x: 0, y: 0, width: '100%', height: '100%' } <br/>**说明:**<br/>showInSubWindow为true时,maskRect不生效。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
637| showInSubWindow<sup>11+</sup>     | boolean                                                      | 否   | 某弹框需要显示在主窗口之外时,是否在子窗口显示此弹窗。<br/>默认值:false,弹窗显示在应用内,而非独立子窗口。<br/>**说明**:showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
638| isModal<sup>11+</sup>             | boolean                                                      | 否   | 弹窗是否为模态窗口,模态窗口有蒙层,非模态窗口无蒙层。<br/>默认值:true,此时弹窗有蒙层。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
639| backgroundColor<sup>12+</sup>     | [ResourceColor](arkui-ts/ts-types.md#resourcecolor)          | 否   | 弹窗背板颜色。<br/>默认值:Color.Transparent<br/>**说明:** <br/>当设置了backgroundColor为非透明色时,backgroundBlurStyle需要设置为BlurStyle.NONE,否则颜色显示将不符合预期效果。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
640| backgroundBlurStyle<sup>12+</sup> | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | 否   | 弹窗背板模糊材质。<br/>默认值:BlurStyle.COMPONENT_ULTRA_THICK<br/>**说明:** <br/>设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时,则不要设置backgroundColor,否则颜色显示将不符合预期效果。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
641| shadow<sup>12+</sup>              | [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions对象说明)&nbsp;\|&nbsp;[ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否   | 设置弹窗背板的阴影。<br /> 当设备为2in1时,默认场景下获焦阴影值为ShadowStyle.OUTER_FLOATING_MD,失焦为ShadowStyle.OUTER_FLOATING_SM<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
642| enableHoverMode<sup>14+</sup>     | boolean                                                      | 否   | 是否响应悬停态。<br />默认值:false,默认不响应。<br/>**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。            |
643| hoverModeArea<sup>14+</sup>       | [HoverModeAreaType](arkui-ts/ts-appendix-enums.md#hovermodeareatype14) | 否   | 悬停态下弹窗默认展示区域。<br />默认值:HoverModeAreaType.BOTTOM_SCREEN<br/>**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。 |
644
645## ShowDialogSuccessResponse
646
647对话框的响应结果。
648
649**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
650
651**系统能力:**  SystemCapability.ArkUI.ArkUI.Full
652
653| 名称  | 类型   | 必填 | 说明                            |
654| ----- | ------ | ---- | ------------------------------- |
655| index | number | 是   | 选中按钮在buttons数组中的索引。 |
656
657## ActionMenuOptions
658
659操作菜单的选项。
660
661**系统能力:** SystemCapability.ArkUI.ArkUI.Full
662
663| 名称                          | 类型                                                         | 必填 | 说明                                                         |
664| ----------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
665| title                         | string&nbsp;\|&nbsp;[Resource](arkui-ts/ts-types.md#resource类型) | 否   | 标题文本。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
666| buttons                       | [[Button](#button),[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?] | 是   | 菜单中菜单项按钮的数组,结构为:{text:'button',&nbsp;color:&nbsp;'\#666666'},支持1-6个按钮。按钮数量大于6个时,仅显示前6个按钮,之后的按钮不显示。<br/>**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
667| showInSubWindow<sup>11+</sup> | boolean                                                      | 否   | 某弹框需要显示在主窗口之外时,是否在子窗口显示此弹窗。<br/>默认值:false,在子窗口不显示弹窗。<br/>**说明**:<br/> - showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。 <br/> - 若在UIExtension中设置showInSubWindow为true, 弹窗将基于UIExtension的宿主窗口对齐。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
668| isModal<sup>11+</sup>         | boolean                                                      | 否   | 弹窗是否为模态窗口,模态窗口有蒙层,非模态窗口无蒙层。<br/>默认值:true,此时弹窗有蒙层。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
669
670## ActionMenuSuccessResponse
671
672操作菜单的响应结果。
673
674**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。
675
676**系统能力:** SystemCapability.ArkUI.ArkUI.Full
677
678| 名称  | 类型   | 必填 | 说明                                     |
679| ----- | ------ | ---- | ---------------------------------------- |
680| index | number | 是   | 选中按钮在buttons数组中的索引,从0开始。 |
681
682## CustomDialogOptions<sup>11+</sup>
683
684自定义弹窗的内容,继承自[BaseDialogOptions](#basedialogoptions11)。
685
686**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
687
688**系统能力:** SystemCapability.ArkUI.ArkUI.Full
689
690| 名称    | 类型                                                    | 必填 | 说明                                                         |
691| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
692| builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | 是  | 设置自定义弹窗的内容。<br/>**说明:** <br/>builder需要赋值为箭头函数,格式如下:() => { this.XXX() },其中XXX是内部builder名。<br/>如果是全局builder需要在组件内部创建一个builder,在内部builder中调用全局builder。<br/>builder根节点宽高百分比相对弹框容器大小。<br/>builder非根节点宽高百分比相对父节点大小。<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
693| backgroundColor <sup>12+</sup>| [ResourceColor](arkui-ts/ts-types.md#resourcecolor)  | 否 | 设置弹窗背板颜色。<br/>默认值:Color.Transparent<br/>**说明:** <br/>当设置了backgroundColor为非透明色时,backgroundBlurStyle需要设置为BlurStyle.NONE,否则颜色显示将不符合预期效果。 |
694| cornerRadius<sup>12+</sup>| [Dimension](arkui-ts/ts-types.md#dimension10)&nbsp;\|&nbsp;[BorderRadiuses](arkui-ts/ts-types.md#borderradiuses9) | 否 | 设置背板的圆角半径。<br />可分别设置4个圆角的半径。<br />默认值:{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }<br /> 圆角大小受组件尺寸限制,最大值为组件宽或高的一半,若值为负,则按照默认值处理。 <br /> 百分比参数方式:以父元素弹窗宽和高的百分比来设置弹窗的圆角。|
695| borderWidth<sup>12+</sup>| [Dimension](arkui-ts/ts-types.md#dimension10)&nbsp;\|&nbsp;[EdgeWidths](arkui-ts/ts-types.md#edgewidths9)  | 否 | 设置弹窗背板的边框宽度。<br />可分别设置4个边框宽度。<br />默认值:0<br /> 百分比参数方式:以父元素弹窗宽的百分比来设置弹窗的边框宽度。<br />当弹窗左边框和右边框大于弹窗宽度,弹窗上边框和下边框大于弹窗高度,显示可能不符合预期。 |
696| borderColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor)&nbsp;\|&nbsp;[EdgeColors](arkui-ts/ts-types.md#edgecolors9)  | 否 | 设置弹窗背板的边框颜色。<br/>默认值:Color.Black<br/> 如果使用borderColor属性,需要和borderWidth属性一起使用。 |
697| borderStyle<sup>12+</sup> | [BorderStyle](arkui-ts/ts-appendix-enums.md#borderstyle)&nbsp;\|&nbsp;[EdgeStyles](arkui-ts/ts-types.md#edgestyles9)  | 否 | 设置弹窗背板的边框样式。<br/>默认值:BorderStyle.Solid<br/> 如果使用borderStyle属性,需要和borderWidth属性一起使用。 |
698| width<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10) | 否   | 设置弹窗背板的宽度。<br />**说明:**<br>- 弹窗宽度默认最大值:400vp。<br />- 百分比参数方式:弹窗参考宽度为所在窗口的宽度,在此基础上调小或调大。|
699| height<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10)  | 否   | 设置弹窗背板的高度。<br />**说明:**<br />- 弹窗高度默认最大值:0.9 *(窗口高度 - 安全区域)。<br />- 百分比参数方式:弹窗参考高度为(窗口高度 - 安全区域),在此基础上调小或调大。|
700| shadow<sup>12+</sup>| [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions对象说明)&nbsp;\|&nbsp;[ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10枚举说明)   | 否 | 设置弹窗背板的阴影。<br />当设备为2in1时,默认场景下获焦阴影值为ShadowStyle.OUTER_FLOATING_MD,失焦为ShadowStyle.OUTER_FLOATING_SM |
701| backgroundBlurStyle<sup>12+</sup> | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9)                 | 否   | 弹窗背板模糊材质。<br/>默认值:BlurStyle.COMPONENT_ULTRA_THICK<br/>**说明:** <br/>设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时,则不要设置backgroundColor,否则颜色显示将不符合预期效果。 |
702
703## BaseDialogOptions<sup>11+</sup>
704
705弹窗的选项。
706
707**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
708
709**系统能力:** SystemCapability.ArkUI.ArkUI.Full
710
711| 名称            | 类型                                                         | 必填 | 说明                                                         |
712| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
713| maskRect        | [Rectangle](arkui-ts/ts-methods-alert-dialog-box.md#rectangle8类型说明) | 否   | 弹窗遮蔽层区域。<br/>默认值:{ x: 0, y: 0, width: '100%', height: '100%' }<br/>**说明:**<br/>showInSubWindow为true时,maskRect不生效。 |
714| alignment       | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否   | 弹窗在竖直方向上的对齐方式。<br>默认值:DialogAlignment.Default <br/>**说明**:<br/>若在UIExtension中设置showInSubWindow为true, 弹窗将基于UIExtension的宿主窗口对齐。|
715| offset          | [Offset](arkui-ts/ts-types.md#offset)                     | 否   | 弹窗相对alignment所在位置的偏移量。<br/>默认值:{&nbsp;dx:&nbsp;0&nbsp;,&nbsp;dy:&nbsp;0&nbsp;} |
716| isModal         | boolean                                                      | 否   | 弹窗是否为模态窗口,模态窗口有蒙层,非模态窗口无蒙层。<br/>默认值:true,此时弹窗有蒙层。 |
717| showInSubWindow | boolean                                                      | 否   | 某弹框需要显示在主窗口之外时,是否在子窗口显示此弹窗。<br/>默认值:false,弹窗显示在应用内,而非独立子窗口。 |
718| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | 否 | 交互式关闭回调函数。<br/>**说明:**<br/>1.当用户执行点击遮障层关闭、左滑/右滑、三键back、键盘ESC关闭交互操作时,如果注册该回调函数,则不会立刻关闭弹窗。在回调函数中可以通过reason得到阻拦关闭弹窗的操作类型,从而根据原因选择是否能关闭弹窗。当前组件返回的reason中,暂不支持CLOSE_BUTTON的枚举值。<br/>2.在onWillDismiss回调中,不能再做onWillDismiss拦截。 |
719|  autoCancel<sup>12+</sup> |       boolean                                   | 否   | 点击遮障层时,是否关闭弹窗,true表示关闭弹窗。false表示不关闭弹窗。<br/>默认值:true |
720|  maskColor<sup>12+</sup> |        [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否    | 自定义蒙层颜色。<br>默认值: 0x33000000              |
721| transition<sup>12+</sup>          | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10) | 否   | 设置弹窗显示和退出的过渡效果。<br/>**说明:**<br/> 1.如果不设置,则使用默认的显示/退出动效。<br/> 2.显示动效中按back键,打断显示动效,执行退出动效,动画效果为显示动效与退出动效的曲线叠加后的效果。<br/> 3.退出动效中按back键,不会打断退出动效,退出动效继续执行,继续按back键退出应用。                               |
722| onDidAppear<sup>12+</sup> | () => void | 否 | 弹窗弹出时的事件回调。<br />**说明:**<br />1.正常时序依次为:onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.在onDidAppear内设置改变弹窗显示效果的回调事件,二次弹出生效。<br />3.快速点击弹出,消失弹窗时,存在onWillDisappear在onDidAppear前生效。<br />4. 当弹窗入场动效未完成时关闭弹窗,该回调不会触发。 |
723| onDidDisappear<sup>12+</sup> | () => void | 否 | 弹窗消失时的事件回调。<br />**说明:**<br />正常时序依次为:onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。 |
724| onWillAppear<sup>12+</sup> | () => void | 否 | 弹窗显示动效前的事件回调。<br />**说明:**<br />1.正常时序依次为:onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.在onWillAppear内设置改变弹窗显示效果的回调事件,二次弹出生效。 |
725| onWillDisappear<sup>12+</sup> | () => void | 否 | 弹窗退出动效前的事件回调。<br />**说明:**<br />1.正常时序依次为:onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.快速点击弹出,消失弹窗时,存在onWillDisappear在onDidAppear前生效。 |
726| keyboardAvoidMode<sup>12+</sup> | [KeyboardAvoidMode](#keyboardavoidmode12枚举说明) | 否 | 用于设置弹窗是否在拉起软键盘时进行自动避让。<br/>默认值:KeyboardAvoidMode.DEFAULT<br/>**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |
727| enableHoverMode<sup>14+</sup>   | boolean | 否   | 是否响应悬停态。<br />默认值:false,默认不响应。<br/>**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。|
728| hoverModeArea<sup>14+</sup>     | [HoverModeAreaType](arkui-ts/ts-appendix-enums.md#hovermodeareatype14) | 否   | 悬停态下弹窗默认展示区域。<br />默认值:HoverModeAreaType.BOTTOM_SCREEN<br/>**原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。|
729
730## DismissDialogAction<sup>12+</sup>
731
732Dialog关闭的信息。
733
734**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
735
736**系统能力:** SystemCapability.ArkUI.ArkUI.Full
737
738### 属性
739
740| 名称    | 类型                                                         | 可读 | 可写 | 说明                                                         |
741| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
742| dismiss | Callback&lt;void&gt;                                         | 否   | 否   | Dialog关闭回调函数。开发者需要退出时调用,不需要退出时无需调用。 |
743| reason  | [DismissReason](#dismissreason12枚举说明) | 否   | 否   | Dialog无法关闭原因。根据开发者需要选择不同操作下,Dialog是否需要关闭。 |
744
745## DismissReason<sup>12+</sup>枚举说明
746
747**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
748
749**系统能力:** SystemCapability.ArkUI.ArkUI.Full
750
751| 名称          | 值   | 描述                                                         |
752| ------------- | ---- | ------------------------------------------------------------ |
753| PRESS_BACK    | 0    | 点击三键back、左滑/右滑、键盘ESC。                           |
754| TOUCH_OUTSIDE | 1    | 点击遮障层时。                                               |
755| CLOSE_BUTTON  | 2    | 点击关闭按钮。                                               |
756| SLIDE_DOWN    | 3    | 下拉关闭。<br/>**说明:** <br/>该接口仅支持在[半模态转场](./arkui-ts/ts-universal-attributes-sheet-transition.md)中使用。 |
757
758## KeyboardAvoidMode<sup>12+</sup>枚举说明
759
760**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
761
762**系统能力:** SystemCapability.ArkUI.ArkUI.Full
763
764| 名称    | 值   | 说明                                             |
765| ------- | ---- | ------------------------------------------------ |
766| DEFAULT | 0    | 默认避让软键盘并在到达极限高度之后进行高度压缩。 |
767| NONE    | 1    | 不避让软键盘。                                   |
768
769## Button
770
771菜单中的菜单项按钮。
772
773**系统能力:** SystemCapability.ArkUI.ArkUI.Full
774
775| 名称    | 类型                                       | 必填   | 说明      |
776| ----- | ---------------------------------------- | ---- | ------- |
777| text  | string&nbsp;\|&nbsp; [Resource](arkui-ts/ts-types.md#resource类型) | 是    | 按钮文本内容。<br />**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
778| color | string&nbsp;\| &nbsp;[Resource](arkui-ts/ts-types.md#resource类型) | 是    | 按钮文本颜色。<br />**原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 |
779| primary<sup>12+</sup> | boolean | 否    | 在弹窗获焦且未进行tab键走焦时,按钮是否默认响应Enter键。多个Button时,只允许一个Button的该字段配置为true,否则所有Button均不响应。多重弹窗可自动获焦连续响应。<br />**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 |