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' 419 420@Entry 421@Component 422struct Index { 423 private customDialogComponentId: number = 0 424 425 @Builder customDialogComponent() { 426 Column() { 427 Text('弹窗').fontSize(30) 428 Row({ space: 50 }) { 429 Button("确认").onClick(() => { 430 promptAction.closeCustomDialog(this.customDialogComponentId) 431 }) 432 Button("取消").onClick(() => { 433 promptAction.closeCustomDialog(this.customDialogComponentId) 434 }) 435 } 436 }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) 437 } 438 439 build() { 440 Row() { 441 Column({ space: 20 }) { 442 Text('组件内弹窗') 443 .fontSize(30) 444 .onClick(() => { 445 promptAction.openCustomDialog({ 446 builder: () => { 447 this.customDialogComponent() 448 }, 449 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 450 console.info("reason" + JSON.stringify(dismissDialogAction.reason)) 451 console.log("dialog onWillDismiss") 452 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 453 dismissDialogAction.dismiss() 454 } 455 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 456 dismissDialogAction.dismiss() 457 } 458 } 459 }).then((dialogId: number) => { 460 this.customDialogComponentId = dialogId 461 }) 462 }) 463 } 464 .width('100%') 465 } 466 .height('100%') 467 } 468} 469 470``` 471该示例定义了弹窗样式，如宽度、高度、背景色、阴影等等。 472```ts 473import { promptAction } from '@kit.ArkUI' 474 475let customDialogId: number = 0 476 477@Builder 478function customDialogBuilder() { 479 Column() { 480 Text('Custom dialog Message').fontSize(10) 481 Row() { 482 Button("确认").onClick(() => { 483 promptAction.closeCustomDialog(customDialogId) 484 }) 485 Blank().width(50) 486 Button("取消").onClick(() => { 487 promptAction.closeCustomDialog(customDialogId) 488 }) 489 } 490 } 491} 492 493@Entry 494@Component 495struct Index { 496 @State message: string = 'Hello World' 497 498 @Builder 499 customDialogComponent() { 500 customDialogBuilder() 501 } 502 503 build() { 504 Row() { 505 Column() { 506 Text(this.message) 507 .fontSize(50) 508 .fontWeight(FontWeight.Bold) 509 .onClick(() => { 510 promptAction.openCustomDialog({ 511 builder: () => { 512 this.customDialogComponent() 513 }, 514 keyboardAvoidMode: KeyboardAvoidMode.NONE, 515 showInSubWindow: false, 516 offset: { dx: 5, dy: 5 }, 517 backgroundColor: 0xd9ffffff, 518 cornerRadius: 20, 519 width: '80%', 520 height: 200, 521 borderWidth: 1, 522 borderStyle: BorderStyle.Dashed, //使用borderStyle属性，需要和borderWidth属性一起使用 523 borderColor: Color.Blue, //使用borderColor属性，需要和borderWidth属性一起使用 524 shadow: ({ 525 radius: 20, 526 color: Color.Grey, 527 offsetX: 50, 528 offsetY: 0 529 }), 530 }).then((dialogId: number) => { 531 customDialogId = dialogId 532 }) 533 }) 534 } 535 .width('100%') 536 } 537 .height('100%') 538 } 539} 540``` 541 542 543## promptAction.closeCustomDialog<sup>11+</sup> 544 545closeCustomDialog(dialogId: number): void 546 547关闭自定义弹窗。 548 549**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 550 551**系统能力：** SystemCapability.ArkUI.ArkUI.Full 552 553**参数：** 554 555| 参数名 | 类型 | 必填 | 说明 | 556| -------- | ------ | ---- | -------------------------------- | 557| dialogId | number | 是 | openCustomDialog返回的对话框id。 | 558 559**错误码：** 560 561以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 562 563| 错误码ID | 错误信息 | 564| -------- | ---------------------------------- | 565| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 566| 100001 | Internal error. | 567 568**示例：** 569 570示例请看[promptAction.openCustomDialog](#promptactionopencustomdialog11)的示例。 571 572## ShowToastOptions 573 574文本提示框的选项。 575 576**系统能力：** SystemCapability.ArkUI.ArkUI.Full 577 578| 名称 | 类型 | 必填 | 说明 | 579| ----------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 580| message | string \| [Resource](arkui-ts/ts-types.md#resource类型) | 是 | 显示的文本信息。<br>**说明：** <br/>默认字体为'Harmony Sans'，不支持设置其他字体。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 581| duration | number | 否 | 默认值1500ms，取值区间：1500ms-10000ms。若小于1500ms则取默认值，若大于10000ms则取上限值10000ms。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 582| bottom | string \| number | 否 | 设置弹窗底部边框距离导航条的高度，ToastShowMode.TOP_MOST模式下，软键盘拉起时，如果bottom值过小，toast要被软键盘遮挡时，会自动避让至距离软键盘80vp处。ToastShowMode.DEFAULT模式下，软键盘拉起时，会上移软键盘的高度。<br/>默认值：80vp<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br/>**说明：** <br/>当底部没有导航条时，bottom为设置弹窗底部边框距离窗口底部的高度。 | 583| showMode<sup>11+</sup> | [ToastShowMode](#toastshowmode11) | 否 | 设置弹窗是否显示在应用之上。<br>默认值：ToastShowMode.DEFAULT，默认显示在应用内。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 584| alignment<sup>12+</sup> | [Alignment](arkui-ts/ts-appendix-enums.md#alignment) | 否 | 对齐方式。<br/>默认值：undefined，默认底部偏上位置。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 585| offset<sup>12+</sup> | [Offset](arkui-ts/ts-types.md#offset) | 否 | 在对齐方式上的偏移。<br/>默认值：{dx:0, dy:0}，默认没有偏移。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 586| 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开始，该接口支持在原子化服务中使用。 | 587| textColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 文本提示框文本颜色<br/>默认值：Color.Black<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 588| 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开始，该接口支持在原子化服务中使用。 | 589| 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.OuterDefaultMD<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 590 591## ToastShowMode<sup>11+</sup> 592 593设置弹窗显示模式，默认显示在应用内，支持显示在应用之上。 594 595**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 596 597**系统能力：** SystemCapability.ArkUI.ArkUI.Full 598 599| 名称 | 值 | 说明 | 600| -------- | ---- | ---------------------- | 601| DEFAULT | 0 | Toast 显示在应用内。 | 602| TOP_MOST | 1 | Toast 显示在应用之上。 | 603 604## ShowDialogOptions 605 606对话框的选项。 607 608**系统能力：** SystemCapability.ArkUI.ArkUI.Full 609 610| 名称 | 类型 | 必填 | 说明 | 611| --------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 612| title | string \| [Resource](arkui-ts/ts-types.md#resource类型) | 否 | 标题文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 613| message | string \| [Resource](arkui-ts/ts-types.md#resource类型) | 否 | 内容文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 614| buttons | Array<[Button](#button)> | 否 | 对话框中按钮的数组，结构为：{text:'button', color: '\#666666'}，支持大于1个按钮。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 615| 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开始，该接口支持在原子化服务中使用。 | 616| offset<sup>10+</sup> | [Offset](arkui-ts/ts-types.md#offset) | 否 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 }<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 617| 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开始，该接口支持在原子化服务中使用。 | 618| showInSubWindow<sup>11+</sup> | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。<br/>**说明**：showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 619| isModal<sup>11+</sup> | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 620| 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开始，该接口支持在原子化服务中使用。 | 621| 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开始，该接口支持在原子化服务中使用。 | 622| 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开始，该接口支持在原子化服务中使用。 | 623 624## ShowDialogSuccessResponse 625 626对话框的响应结果。 627 628**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 629 630**系统能力：** SystemCapability.ArkUI.ArkUI.Full 631 632| 名称 | 类型 | 必填 | 说明 | 633| ----- | ------ | ---- | ------------------------------- | 634| index | number | 是 | 选中按钮在buttons数组中的索引。 | 635 636## ActionMenuOptions 637 638操作菜单的选项。 639 640**系统能力：** SystemCapability.ArkUI.ArkUI.Full 641 642| 名称 | 类型 | 必填 | 说明 | 643| ----------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 644| title | string \| [Resource](arkui-ts/ts-types.md#resource类型) | 否 | 标题文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 645| 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开始，该接口支持在原子化服务中使用。 | 646| showInSubWindow<sup>11+</sup> | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，在子窗口不显示弹窗。<br/>**说明**：<br/> - showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。 <br/> - 若在UIExtension中设置showInSubWindow为true, 弹窗将基于UIExtension的宿主窗口对齐。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 647| isModal<sup>11+</sup> | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 648 649## ActionMenuSuccessResponse 650 651操作菜单的响应结果。 652 653**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 654 655**系统能力：** SystemCapability.ArkUI.ArkUI.Full 656 657| 名称 | 类型 | 必填 | 说明 | 658| ----- | ------ | ---- | ---------------------------------------- | 659| index | number | 是 | 选中按钮在buttons数组中的索引，从0开始。 | 660 661## CustomDialogOptions<sup>11+</sup> 662 663自定义弹窗的内容，继承自[BaseDialogOptions](#basedialogoptions11)。 664 665**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 666 667**系统能力：** SystemCapability.ArkUI.ArkUI.Full 668 669| 名称 | 类型 | 必填 | 说明 | 670| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 671| 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开始，该接口支持在原子化服务中使用。 | 672| backgroundColor <sup>12+</sup>| [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 设置弹窗背板颜色。<br/>默认值：Color.Transparent<br/>**说明：** <br/>当设置了backgroundColor为非透明色时，backgroundBlurStyle需要设置为BlurStyle.NONE，否则颜色显示将不符合预期效果。 | 673| 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 /> 百分比参数方式：以父元素弹窗宽和高的百分比来设置弹窗的圆角。| 674| borderWidth<sup>12+</sup>| [Dimension](arkui-ts/ts-types.md#dimension10) \| [EdgeWidths](arkui-ts/ts-types.md#edgewidths9) | 否 | 设置弹窗背板的边框宽度。<br />可分别设置4个边框宽度。<br />默认值：0。<br /> 百分比参数方式：以父元素弹窗宽的百分比来设置弹窗的边框宽度。<br />当弹窗左边框和右边框大于弹窗宽度，弹窗上边框和下边框大于弹窗高度，显示可能不符合预期。| 675| borderColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) \| [EdgeColors](arkui-ts/ts-types.md#edgecolors9) | 否 | 设置弹窗背板的边框颜色。<br/>默认值：Color.Black。<br/> 如果使用borderColor属性，需要和borderWidth属性一起使用。 | 676| 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属性一起使用。 | 677| width<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10) | 否 | 设置弹窗背板的宽度。<br />**说明：**<br>- 弹窗宽度默认最大值：400vp。<br />- 百分比参数方式：弹窗参考宽度为所在窗口的宽度，在此基础上调小或调大。| 678| height<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10) | 否 | 设置弹窗背板的高度。<br />**说明：**<br />- 弹窗高度默认最大值：0.9 *（窗口高度 - 安全区域）。<br />- 百分比参数方式：弹窗参考高度为（窗口高度 - 安全区域），在此基础上调小或调大。| 679| 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 | 680| 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，否则颜色显示将不符合预期效果。 | 681 682## BaseDialogOptions<sup>11+</sup> 683 684弹窗的选项。 685 686**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 687 688**系统能力：** SystemCapability.ArkUI.ArkUI.Full 689 690| 名称 | 类型 | 必填 | 说明 | 691| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 692| 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不生效。 | 693| alignment | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否 | 弹窗在竖直方向上的对齐方式。<br>默认值：DialogAlignment.Default <br/>**说明**：<br/>若在UIExtension中设置showInSubWindow为true, 弹窗将基于UIExtension的宿主窗口对齐。| 694| offset | [Offset](arkui-ts/ts-types.md#offset) | 否 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 } | 695| isModal | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。 | 696| showInSubWindow | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。 | 697| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | 否 | 交互式关闭回调函数。<br/>**说明：**<br/>1.当用户执行点击遮障层关闭、左滑/右滑、三键back、键盘ESC关闭交互操作时，如果注册该回调函数，则不会立刻关闭弹窗。在回调函数中可以通过reason得到阻拦关闭弹窗的操作类型，从而根据原因选择是否能关闭弹窗。当前组件返回的reason中，暂不支持CLOSE_BUTTON的枚举值。<br/>2.在onWillDismiss回调中，不能再做onWillDismiss拦截。 | 698| autoCancel<sup>12+</sup> | boolean | 否 | 点击遮障层时，是否关闭弹窗，true表示关闭弹窗。false表示不关闭弹窗。<br/>默认值：true | 699| maskColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 自定义蒙层颜色。<br>默认值: 0x33000000 | 700| transition<sup>12+</sup> | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10) | 否 | 设置弹窗显示和退出的过渡效果。<br/>**说明：**<br/> 1.如果不设置，则使用默认的显示/退出动效。<br/> 2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。<br/> 3.退出动效中按back键，不会打断退出动效，退出动效继续执行，继续按back键退出应用。 | 701| onDidAppear<sup>12+</sup> | () => void | 否 | 弹窗弹出时的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.在onDidAppear内设置改变弹窗显示效果的回调事件，二次弹出生效。<br />3.快速点击弹出，消失弹窗时，存在onWillDisappear在onDidAppear前生效。<br />4. 当弹窗入场动效未完成时关闭弹窗，该回调不会触发。 | 702| onDidDisappear<sup>12+</sup> | () => void | 否 | 弹窗消失时的事件回调。<br />**说明：**<br />正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。 | 703| onWillAppear<sup>12+</sup> | () => void | 否 | 弹窗显示动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.在onWillAppear内设置改变弹窗显示效果的回调事件，二次弹出生效。 | 704| onWillDisappear<sup>12+</sup> | () => void | 否 | 弹窗退出动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.快速点击弹出，消失弹窗时，存在onWillDisappear在onDidAppear前生效。 | 705| keyboardAvoidMode<sup>12+</sup> | [KeyboardAvoidMode](#keyboardavoidmode12枚举说明) | 否 | 用于设置弹窗是否在拉起软键盘时进行自动避让。<br/>默认值：KeyboardAvoidMode.DEFAULT<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 706 707## DismissDialogAction<sup>12+</sup> 708 709Dialog关闭的信息。 710 711**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 712 713**系统能力：** SystemCapability.ArkUI.ArkUI.Full 714 715### 属性 716 717| 名称 | 类型 | 可读 | 可写 | 说明 | 718| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 719| dismiss | Callback<void> | 否 | 否 | Dialog关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 720| reason | [DismissReason](#dismissreason12枚举说明) | 否 | 否 | Dialog无法关闭原因。根据开发者需要选择不同操作下，Dialog是否需要关闭。 | 721 722## DismissReason<sup>12+</sup>枚举说明 723 724**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 725 726**系统能力：** SystemCapability.ArkUI.ArkUI.Full 727 728| 名称 | 值 | 描述 | 729| ------------- | ---- | ------------------------------------------------------------ | 730| PRESS_BACK | 0 | 点击三键back、左滑/右滑、键盘ESC。 | 731| TOUCH_OUTSIDE | 1 | 点击遮障层时。 | 732| CLOSE_BUTTON | 2 | 点击关闭按钮。 | 733| SLIDE_DOWN | 3 | 下拉关闭。<br/>**说明：** <br/>该接口仅支持在[半模态转场](./arkui-ts/ts-universal-attributes-sheet-transition.md)中使用。 | 734 735## KeyboardAvoidMode<sup>12+</sup>枚举说明 736 737**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 738 739**系统能力：** SystemCapability.ArkUI.ArkUI.Full 740 741| 名称 | 值 | 说明 | 742| ------- | ---- | ------------------------------------------------ | 743| DEFAULT | 0 | 默认避让软键盘并在到达极限高度之后进行高度压缩。 | 744| NONE | 1 | 不避让软键盘。 | 745 746## Button 747 748菜单中的菜单项按钮。 749 750**系统能力：** SystemCapability.ArkUI.ArkUI.Full 751 752| 名称 | 类型 | 必填 | 说明 | 753| ----- | ---------------------------------------- | ---- | ------- | 754| text | string \| [Resource](arkui-ts/ts-types.md#resource类型) | 是 | 按钮文本内容。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 755| color | string \| [Resource](arkui-ts/ts-types.md#resource类型) | 是 | 按钮文本颜色。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 756| primary<sup>12+</sup> | boolean | 否 | 在弹窗获焦且未进行tab键走焦时，按钮是否默认响应Enter键。多个Button时，只允许一个Button的该字段配置为true，否则所有Button均不响应。多重弹窗可自动获焦连续响应。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 |
