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 77 78API version 12及之后Toast样式。 79 80 81 82## promptAction.showDialog 83 84showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse> 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<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 对话框响应结果。 | 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 148 149## promptAction.showDialog 150 151showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse>):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<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 是 | 对话框响应结果回调。 | 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 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 248 249 250 251## promptAction.showActionMenu 252 253showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void 254 255创建并显示操作菜单，菜单响应结果异步返回。 256 257**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 258 259**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 260 261**参数：** 262 263| 参数名 | 类型 | 必填 | 说明 | 264| -------- | ---------------------------------------- | ---- | --------- | 265| options | [ActionMenuOptions](#actionmenuoptions) | 是 | 操作菜单选项。 | 266| callback | AsyncCallback<[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 311 312## promptAction.showActionMenu 313 314showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse> 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<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 菜单响应结果。 | 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 377 378## promptAction.openCustomDialog<sup>11+</sup> 379 380openCustomDialog(options: CustomDialogOptions): Promise<number> 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<number> | 返回供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 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 \| [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 \| 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对象说明) \| [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 \| [Resource](arkui-ts/ts-types.md#resource类型) | 否 | 标题文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 632| message | string \| [Resource](arkui-ts/ts-types.md#resource类型) | 否 | 内容文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 633| buttons | Array<[Button](#button)> | 否 | 对话框中按钮的数组，结构为：{text:'button', color: '\#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/>默认值：{ dx: 0 , dy: 0 }<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对象说明) \| [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 \| [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', color: '\#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) \| [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) \| [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) \| [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) \| [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对象说明) \| [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/>默认值：{ dx: 0 , dy: 0 } | 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<void> | 否 | 否 | 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 \| [Resource](arkui-ts/ts-types.md#resource类型) | 是 | 按钮文本内容。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 778| color | string \| [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开始，该接口支持在原子化服务中使用。 |
