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)说明。 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 '@ohos.promptAction'; 19``` 20 21## promptAction.showToast 22 23showToast(options: ShowToastOptions): void 24 25创建并显示文本提示框。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------- | ------------------------------------- | ---- | ------- | 33| options | [ShowToastOptions](#showtoastoptions) | 是 | 文本弹窗选项。 | 34 35**错误码：** 36 37以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 38 39| 错误码ID | 错误信息 | 40| --------- | ------- | 41| 100001 | if UI execution context not found. | 42 43**示例：** 44 45```ts 46import promptAction from '@ohos.promptAction' 47import { BusinessError } from '@ohos.base'; 48try { 49 promptAction.showToast({ 50 message: 'Message Info', 51 duration: 2000 52 }); 53} catch (error) { 54 let message = (error as BusinessError).message 55 let code = (error as BusinessError).code 56 console.error(`showToast args error code is ${code}, message is ${message}`); 57}; 58 59``` 60 61 62 63## ShowToastOptions 64 65文本提示框的选项。 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 68 69| 名称 | 类型 | 必填 | 说明 | 70| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 71| message | string\| [Resource](arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 是 | 显示的文本信息。<br>**说明：** <br/>默认字体为'Harmony Sans'，不支持设置其他字体。 | 72| duration | number | 否 | 默认值1500ms，取值区间：1500ms-10000ms。若小于1500ms则取默认值，若大于10000ms则取上限值10000ms。 | 73| bottom | string\| number | 否 | 设置弹窗边框距离屏幕底部的位置。<br>默认值：80vp | 74| showMode<sup>11+</sup> | [ToastShowMode](#toastshowmode11) | 否 | 设置弹窗是否显示在应用之上。<br>默认值：ToastShowMode.DEFAULT，默认显示在应用内。 | 75 76### ToastShowMode<sup>11+</sup> 77 78设置弹窗显示模式，默认显示在应用内，支持显示在应用之上。 79 80**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 81 82| 名称 | 值 | 说明 | 83| -------- | ---- | ------------------------------------------------------------ | 84| DEFAULT | 0 | Toast 显示在应用内。 | 85| TOP_MOST | 1 | Toast 显示在应用之上。 | 86 87 88## promptAction.showDialog 89 90showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse> 91 92创建并显示对话框，对话框响应后异步返回结果。 93 94**系统能力：** SystemCapability.ArkUI.ArkUI.Full 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| ------- | --------------------------------------- | ---- | ------ | 100| options | [ShowDialogOptions](#showdialogoptions) | 是 | 对话框选项。 | 101 102**返回值：** 103 104| 类型 | 说明 | 105| ---------------------------------------- | -------- | 106| Promise<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 对话框响应结果。 | 107 108**错误码：** 109 110以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 111 112| 错误码ID | 错误信息 | 113| --------- | ------- | 114| 100001 | if UI execution context not found. | 115 116**示例：** 117 118```ts 119import promptAction from '@ohos.promptAction' 120import { BusinessError } from '@ohos.base'; 121try { 122 promptAction.showDialog({ 123 title: 'Title Info', 124 message: 'Message Info', 125 buttons: [ 126 { 127 text: 'button1', 128 color: '#000000' 129 }, 130 { 131 text: 'button2', 132 color: '#000000' 133 } 134 ], 135 }) 136 .then(data => { 137 console.info('showDialog success, click button: ' + data.index); 138 }) 139 .catch((err:Error) => { 140 console.info('showDialog error: ' + err); 141 }) 142} catch (error) { 143 let message = (error as BusinessError).message 144 let code = (error as BusinessError).code 145 console.error(`showDialog args error code is ${code}, message is ${message}`); 146}; 147``` 148 149 150 151## promptAction.showDialog 152 153showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse>):void 154 155创建并显示对话框，对话框响应结果异步返回。 156 157**系统能力：** SystemCapability.ArkUI.ArkUI.Full 158 159**参数：** 160 161| 参数名 | 类型 | 必填 | 说明 | 162| -------- | ---------------------------------------- | ---- | ------------ | 163| options | [ShowDialogOptions](#showdialogoptions) | 是 | 页面显示对话框信息描述。 | 164| callback | AsyncCallback<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 是 | 对话框响应结果回调。 | 165 166**错误码：** 167 168以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 169 170| 错误码ID | 错误信息 | 171| --------- | ------- | 172| 100001 | if UI execution context not found. | 173 174**示例：** 175 176```ts 177import promptAction from '@ohos.promptAction'; 178import { BusinessError } from '@ohos.base'; 179try { 180 promptAction.showDialog({ 181 title: 'showDialog Title Info', 182 message: 'Message Info', 183 buttons: [ 184 { 185 text: 'button1', 186 color: '#000000' 187 }, 188 { 189 text: 'button2', 190 color: '#000000' 191 } 192 ] 193 }, (err, data) => { 194 if (err) { 195 console.info('showDialog err: ' + err); 196 return; 197 } 198 console.info('showDialog success callback, click button: ' + data.index); 199 }); 200} catch (error) { 201 let message = (error as BusinessError).message 202 let code = (error as BusinessError).code 203 console.error(`showDialog args error code is ${code}, message is ${message}`); 204}; 205``` 206 207 208 209当弹窗的showInSubWindow属性为true时，弹窗可显示在窗口外 210 211```ts 212import promptAction from '@ohos.promptAction'; 213import { BusinessError } from '@ohos.base'; 214try { 215 promptAction.showDialog({ 216 title: 'showDialog Title Info', 217 message: 'Message Info', 218 isModal: true, 219 showInSubWindow: true, 220 buttons: [ 221 { 222 text: 'button1', 223 color: '#000000' 224 }, 225 { 226 text: 'button2', 227 color: '#000000' 228 } 229 ] 230 }, (err, data) => { 231 if (err) { 232 console.info('showDialog err: ' + err); 233 return; 234 } 235 console.info('showDialog success callback, click button: ' + data.index); 236 }); 237} catch (error) { 238 let message = (error as BusinessError).message 239 let code = (error as BusinessError).code 240 console.error(`showDialog args error code is ${code}, message is ${message}`); 241}; 242``` 243 244 245 246 247 248## ShowDialogOptions 249 250对话框的选项。 251 252**系统能力：** SystemCapability.ArkUI.ArkUI.Full 253 254| 名称 | 类型 | 必填 | 说明 | 255| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 256| title | string\| [Resource](arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 否 | 标题文本。 | 257| message | string\| [Resource](arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 否 | 内容文本。 | 258| buttons | Array<[Button](#button)> | 否 | 对话框中按钮的数组，结构为：{text:'button', color: '\#666666'}，支持大于1个按钮。 259| alignment<sup>10+</sup> | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否 | 弹窗在竖直方向上的对齐方式。<br>默认值：DialogAlignment.Default | 260| offset<sup>10+</sup> | [Offset](arkui-ts/ts-types.md#offset) | 否 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 } | 261| 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不生效。| 262| showInSubWindow<sup>11+</sup> | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。<br/>**说明**：showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。 | 263| isModal<sup>11+</sup> | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。 | 264 265## ShowDialogSuccessResponse 266 267对话框的响应结果。 268 269**系统能力：** SystemCapability.ArkUI.ArkUI.Full 270 271| 名称 | 类型 | 必填 | 说明 | 272| ----- | ------ | ---- | ------------------------------- | 273| index | number | 否 | 选中按钮在buttons数组中的索引。 | 274 275## promptAction.showActionMenu 276 277showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void 278 279创建并显示操作菜单，菜单响应结果异步返回。 280 281**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 282 283**参数：** 284 285| 参数名 | 类型 | 必填 | 说明 | 286| -------- | ---------------------------------------- | ---- | --------- | 287| options | [ActionMenuOptions](#actionmenuoptions) | 是 | 操作菜单选项。 | 288| callback | AsyncCallback<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 是 | 菜单响应结果回调。 | 289 290**错误码：** 291 292以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 293 294| 错误码ID | 错误信息 | 295| --------- | ------- | 296| 100001 | if UI execution context not found. | 297 298**示例：** 299 300```ts 301import promptAction from '@ohos.promptAction'; 302import { BusinessError } from '@ohos.base'; 303try { 304 promptAction.showActionMenu({ 305 title: 'Title Info', 306 buttons: [ 307 { 308 text: 'item1', 309 color: '#666666' 310 }, 311 { 312 text: 'item2', 313 color: '#000000' 314 }, 315 ] 316 }, (err, data) => { 317 if (err) { 318 console.info('showActionMenu err: ' + err); 319 return; 320 } 321 console.info('showActionMenu success callback, click button: ' + data.index); 322 }) 323} catch (error) { 324 let message = (error as BusinessError).message 325 let code = (error as BusinessError).code 326 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 327}; 328``` 329 330 331 332## promptAction.showActionMenu 333 334showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse> 335 336创建并显示操作菜单，菜单响应后异步返回结果。 337 338**系统能力：** SystemCapability.ArkUI.ArkUI.Full 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| ------- | --------------------------------------- | ---- | ------- | 344| options | [ActionMenuOptions](#actionmenuoptions) | 是 | 操作菜单选项。 | 345 346**返回值：** 347 348| 类型 | 说明 | 349| ---------------------------------------- | ------- | 350| Promise<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 菜单响应结果。 | 351 352**错误码：** 353 354以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 355 356| 错误码ID | 错误信息 | 357| --------- | ------- | 358| 100001 | if UI execution context not found. | 359 360**示例：** 361 362```ts 363import promptAction from '@ohos.promptAction'; 364import { BusinessError } from '@ohos.base'; 365try { 366 promptAction.showActionMenu({ 367 title: 'showActionMenu Title Info', 368 buttons: [ 369 { 370 text: 'item1', 371 color: '#666666' 372 }, 373 { 374 text: 'item2', 375 color: '#000000' 376 }, 377 ] 378 }) 379 .then(data => { 380 console.info('showActionMenu success, click button: ' + data.index); 381 }) 382 .catch((err:Error) => { 383 console.info('showActionMenu error: ' + err); 384 }) 385} catch (error) { 386 let message = (error as BusinessError).message 387 let code = (error as BusinessError).code 388 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 389}; 390``` 391 392 393 394## promptAction.openCustomDialog<sup>11+</sup> 395 396openCustomDialog(options: CustomDialogOptions): Promise<number> 397 398打开自定义弹窗。 399 400不支持在[ServiceExtension](../../application-models/serviceextensionability.md)中使用。 401 402暂不支持isModal = true与showInSubWindow = true同时使用。 403 404弹窗宽度在设备竖屏时默认为4个栅格，横屏时为5个栅格。 405 406**系统能力：** SystemCapability.ArkUI.ArkUI.Full 407 408**参数：** 409 410| 参数名 | 类型 | 必填 | 说明 | 411| ------- | --------------------------------------------- | ---- | ------------------ | 412| options | [CustomDialogOptions](#customdialogoptions11) | 是 | 自定义弹窗的内容。 | 413 414**返回值：** 415 416| 类型 | 说明 | 417| --------------------- | ------------------------------------- | 418| Promise<number> | 返回供closeCustomDialog使用的对话框id。 | 419 420**错误码：** 421 422以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 423 424| 错误码ID | 错误信息 | 425| -------- | ---------------------------------- | 426| 100001 | if UI execution context not found. | 427 428**示例：** 429 430```ts 431import promptAction from '@ohos.promptAction' 432let customDialogId: number = 0 433@Builder 434function customDialogBuilder() { 435 Column() { 436 Text('Custom dialog Message').fontSize(10) 437 Row() { 438 Button("确认").onClick(() => { 439 promptAction.closeCustomDialog(customDialogId) 440 }) 441 Blank().width(50) 442 Button("取消").onClick(() => { 443 promptAction.closeCustomDialog(customDialogId) 444 }) 445 } 446 }.height(200).padding(5) 447} 448 449@Entry 450@Component 451struct Index { 452 @State message: string = 'Hello World' 453 454 build() { 455 Row() { 456 Column() { 457 Text(this.message) 458 .fontSize(50) 459 .fontWeight(FontWeight.Bold) 460 .onClick(() => { 461 promptAction.openCustomDialog({ 462 builder: customDialogBuilder.bind(this) 463 }).then((dialogId: number) => { 464 customDialogId = dialogId 465 }) 466 }) 467 } 468 .width('100%') 469 } 470 .height('100%') 471 } 472} 473``` 474 475## promptAction.closeCustomDialog<sup>11+</sup> 476 477closeCustomDialog(dialogId: number): void 478 479关闭自定义弹窗。 480 481**系统能力：** SystemCapability.ArkUI.ArkUI.Full 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| -------- | ------ | ---- | -------------------------------- | 487| dialogId | number | 是 | openCustomDialog返回的对话框id。 | 488 489**错误码：** 490 491以下错误码的详细介绍请参见[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 492 493| 错误码ID | 错误信息 | 494| -------- | ---------------------------------- | 495| 100001 | if UI execution context not found. | 496 497**示例：** 498 499示例请看[promptAction.openCustomDialog](#promptactionopencustomdialog11)的示例。 500 501## ActionMenuOptions 502 503操作菜单的选项。 504 505**系统能力：** SystemCapability.ArkUI.ArkUI.Full 506 507| 名称 | 类型 | 必填 | 说明 | 508| ----------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 509| title | string\| [Resource](arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 否 | 标题文本。 | 510| buttons | [[Button](#button),[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?] | 是 | 菜单中菜单项按钮的数组，结构为：{text:'button', color: '\#666666'}，支持1-6个按钮。按钮数量大于6个时，仅显示前6个按钮，之后的按钮不显示。 | 511| showInSubWindow<sup>11+</sup> | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，在子窗口不显示弹窗。<br/>**说明**：showInSubWindow为true的弹窗无法触发显示另一个showInSubWindow为true的弹窗。 | 512| isModal<sup>11+</sup> | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。 | 513 514## CustomDialogOptions<sup>11+</sup> 515 516自定义弹窗的内容，继承自[BaseDialogOptions](#basedialogoptions11)。 517 518**系统能力：** SystemCapability.ArkUI.ArkUI.Full 519 520| 名称 | 类型 | 必填 | 说明 | 521| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 522| builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | 否 | 设置自定义弹窗的内容。<br/>**说明：** <br/>builder需要使用bind(this)。<br/>builder根节点宽高百分比相对弹框容器大小。<br/>builder非根节点宽高百分比相对父节点大小。 | 523 524## BaseDialogOptions<sup>11+</sup> 525 526弹窗的选项。 527 528**系统能力：** SystemCapability.ArkUI.ArkUI.Full 529 530| 名称 | 类型 | 必填 | 说明 | 531| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 532| maskRect | [Rectangle](arkui-ts/ts-methods-alert-dialog-box.md#rectangle8类型说明) | 否 | 弹窗遮蔽层区域。<br/>**说明：**<br/>showInSubWindow为true时，maskRect不生效。 | 533| alignment | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否 | 弹窗在竖直方向上的对齐方式。 | 534| offset | [Offset](arkui-ts/ts-types.md#offset) | 否 | 弹窗相对alignment所在位置的偏移量。 | 535| isModal | boolean | 否 | 弹窗是否为模态窗口，模态窗口有蒙层，非模态窗口无蒙层。<br/>默认值：true，此时弹窗有蒙层。 | 536| showInSubWindow | boolean | 否 | 某弹框需要显示在主窗口之外时，是否在子窗口显示此弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。 | 537 538## ActionMenuSuccessResponse 539 540操作菜单的响应结果。 541 542**系统能力：** SystemCapability.ArkUI.ArkUI.Full 543 544| 名称 | 类型 | 必填 | 说明 | 545| ----- | ------ | ---- | ------------------------ | 546| index | number | 否 | 选中按钮在buttons数组中的索引，从0开始。 | 547 548## Button 549 550菜单中的菜单项按钮。 551 552**系统能力：** SystemCapability.ArkUI.ArkUI.Full 553 554| 名称 | 类型 | 必填 | 说明 | 555| ----- | ---------------------------------------- | ---- | ------- | 556| text | string\| [Resource](arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 是 | 按钮文本内容。 | 557| color | string\| [Resource](arkui-ts/ts-types.md#resource类型)<sup>9+</sup> | 是 | 按钮文本颜色。 | 558
