1# Class (PromptAction) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @houguobiao--> 5<!--Designer: @houguobiao--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9创建并显示即时反馈、对话框、操作菜单以及自定义弹窗。 10 11> **说明：** 12> 13> - 本模块首批接口从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> - 本Class首批接口从API version 10开始支持。 16> 17> - 以下API需先使用UIContext中的[getPromptAction()](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取到PromptAction对象，再通过该对象调用对应方法。 18 19## showToast 20 21showToast(options: promptAction.ShowToastOptions): void 22 23创建并显示即时反馈。 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力：** SystemCapability.ArkUI.ArkUI.Full 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------- | ---------------------------------------- | ---- | ------- | 33| options | [promptAction.ShowToastOptions](js-apis-promptAction.md#showtoastoptions) | 是 | Toast选项。 | 34 35**错误码：** 36 37以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 38 39| 错误码ID | 错误信息 | 40| ------ | ---------------------------------- | 41| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 42| 100001 | Internal error. | 43 44**示例：** 45 46该示例通过调用showToast接口，创建并显示即时反馈。 47 48```ts 49import { PromptAction } from '@kit.ArkUI'; 50import { BusinessError } from '@kit.BasicServicesKit'; 51 52@Entry 53@Component 54struct Index { 55 promptAction: PromptAction = this.getUIContext().getPromptAction(); 56 57 build() { 58 Column() { 59 Button('showToast') 60 .onClick(() => { 61 try { 62 this.promptAction.showToast({ 63 message: 'Message Info', 64 duration: 2000 65 }); 66 } catch (error) { 67 let message = (error as BusinessError).message; 68 let code = (error as BusinessError).code; 69 console.error(`showToast args error code is ${code}, message is ${message}`); 70 }; 71 }) 72 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 73 } 74} 75``` 76 77## openToast<sup>18+</sup> 78 79openToast(options: promptAction.ShowToastOptions): Promise<number> 80 81显示即时反馈。使用Promise异步回调返回即时反馈的id，可供closeToast使用。 82 83**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 84 85**系统能力：** SystemCapability.ArkUI.ArkUI.Full 86 87**参数：** 88 89| 参数名 | 类型 | 必填 | 说明 | 90| ------- | ------------------------------------------------------------ | ---- | -------------- | 91| options | [promptAction.ShowToastOptions](js-apis-promptAction.md#showtoastoptions) | 是 | Toast选项。 | 92 93**返回值** 94 95| 类型 | 说明 | 96| ---------------- | ------------------------------------ | 97| Promise<number> | Promise对象。返回即时反馈的id，可供closeToast使用。 | 98 99**错误码：** 100 101以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 102 103| 错误码ID | 错误信息 | 104| -------- | ------------------------------------------------------------ | 105| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 106| 100001 | Internal error. | 107 108**示例：** 109 110该示例通过调用openToast和closeToast接口，展示了弹出以及关闭Toast的功能。 111 112```ts 113import { PromptAction } from '@kit.ArkUI'; 114import { BusinessError } from '@kit.BasicServicesKit'; 115 116@Entry 117@Component 118struct Index { 119 @State toastId: number = 0; 120 promptAction: PromptAction = this.getUIContext().getPromptAction(); 121 122 build() { 123 Column() { 124 Button('OpenToast') 125 .height(100) 126 .onClick(() => { 127 this.promptAction.openToast({ 128 message: 'Toast Message', 129 duration: 10000, 130 }).then((toastId: number) => { 131 this.toastId = toastId; 132 }) 133 .catch((error: BusinessError) => { 134 console.error(`openToast error code is ${error.code}, message is ${error.message}`); 135 }) 136 }) 137 Blank().height(50) 138 Button('Close Toast') 139 .height(100) 140 .onClick(() => { 141 try { 142 this.promptAction.closeToast(this.toastId); 143 } catch (error) { 144 let message = (error as BusinessError).message; 145 let code = (error as BusinessError).code; 146 console.error(`CloseToast error code is ${code}, message is ${message}`); 147 }; 148 }) 149 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 150 } 151} 152``` 153 154## closeToast<sup>18+</sup> 155 156closeToast(toastId: number): void 157 158关闭即时反馈。 159 160**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164**参数** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ------- | ------ | ---- | ----------------------------- | 168| toastId | number | 是 | openToast返回的id。 | 169 170**错误码：** 171 172以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 173 174| 错误码ID | 错误信息 | 175| -------- | ------------------------------------------------------------ | 176| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 177| 100001 | Internal error. | 178| 103401 | Cannot find the toast. | 179 180**示例：** 181 182请参考[openToast18](#opentoast18)的示例。 183 184## showDialog 185 186showDialog(options: promptAction.ShowDialogOptions, callback: AsyncCallback<promptAction.ShowDialogSuccessResponse>): void 187 188创建并显示对话框，对话框响应结果使用callback异步回调返回。 189 190**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.ArkUI.ArkUI.Full 193 194**参数：** 195 196| 参数名 | 类型 | 必填 | 说明 | 197| -------- | ---------------------------------------- | ---- | ------------ | 198| options | [promptAction.ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | 是 | 页面显示对话框信息描述。 | 199| callback | AsyncCallback<[promptAction.ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | 是 | 回调函数。弹出对话框成功，err为undefined，data为获取到的对话框响应结果，否则为错误对象。 | 200 201**错误码：** 202 203以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 204 205| 错误码ID | 错误信息 | 206| ------ | ---------------------------------- | 207| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 208| 100001 | Internal error. | 209 210**示例：** 211 212该示例通过调用showDialog接口，展示了弹出对话框以及返回对话框响应结果的功能。 213 214```ts 215import { PromptAction } from '@kit.ArkUI'; 216import { BusinessError } from '@kit.BasicServicesKit'; 217 218@Entry 219@Component 220struct Index { 221 promptAction: PromptAction = this.getUIContext().getPromptAction(); 222 223 build() { 224 Column() { 225 Button('showDialog') 226 .onClick(() => { 227 try { 228 this.promptAction.showDialog({ 229 title: 'showDialog Title Info', 230 message: 'Message Info', 231 buttons: [ 232 { 233 text: 'button1', 234 color: '#000000' 235 }, 236 { 237 text: 'button2', 238 color: '#000000' 239 } 240 ] 241 }, (err, data) => { 242 if (err) { 243 console.error('showDialog err: ' + err); 244 return; 245 } 246 console.info('showDialog success callback, click button: ' + data.index); 247 }); 248 } catch (error) { 249 let message = (error as BusinessError).message; 250 let code = (error as BusinessError).code; 251 console.error(`showDialog args error code is ${code}, message is ${message}`); 252 }; 253 }) 254 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 255 } 256} 257``` 258 259## showDialog 260 261showDialog(options: promptAction.ShowDialogOptions): Promise<promptAction.ShowDialogSuccessResponse> 262 263创建并显示对话框，使用Promise异步回调获取对话框的响应结果。 264 265**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 266 267**系统能力：** SystemCapability.ArkUI.ArkUI.Full 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| ------- | ---------------------------------------- | ---- | ------ | 273| options | [promptAction.ShowDialogOptions](js-apis-promptAction.md#showdialogoptions) | 是 | 对话框选项。 | 274 275**返回值：** 276 277| 类型 | 说明 | 278| ---------------------------------------- | -------- | 279| Promise<[promptAction.ShowDialogSuccessResponse](js-apis-promptAction.md#showdialogsuccessresponse)> | Promise对象，返回对话框的响应结果。 | 280 281**错误码：** 282 283以下错误码的详细介绍请参见[ 通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 284 285| 错误码ID | 错误信息 | 286| ------ | ---------------------------------- | 287| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 288| 100001 | Internal error. | 289 290**示例：** 291 292该示例通过调用showDialog接口，展示了弹出对话框以及通过Promise获取对话框响应结果的功能。 293 294```ts 295import { PromptAction } from '@kit.ArkUI'; 296 297@Entry 298@Component 299struct Index { 300 promptAction: PromptAction = this.getUIContext().getPromptAction(); 301 302 build() { 303 Column() { 304 Button('showDialog') 305 .onClick(() => { 306 this.promptAction.showDialog({ 307 title: 'Title Info', 308 message: 'Message Info', 309 buttons: [ 310 { 311 text: 'button1', 312 color: '#000000' 313 }, 314 { 315 text: 'button2', 316 color: '#000000' 317 } 318 ], 319 }) 320 .then(data => { 321 console.info('showDialog success, click button: ' + data.index); 322 }) 323 .catch((err: Error) => { 324 console.error('showDialog error: ' + err); 325 }) 326 }) 327 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 328 } 329} 330``` 331 332## showActionMenu<sup>11+</sup> 333 334showActionMenu(options: promptAction.ActionMenuOptions, callback: AsyncCallback<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)>): void 335 336创建并显示操作菜单，菜单响应结果异步返回。 337 338**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 339 340**系统能力：** SystemCapability.ArkUI.ArkUI.Full 341 342**参数：** 343 344| 参数名 | 类型 | 必填 | 说明 | 345| -------- | ------------------------------------------------------------ | ---- | ------------------ | 346| options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | 是 | 操作菜单选项。 | 347| callback | AsyncCallback<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | 是 | 回调函数。弹出操作菜单成功，err为undefined，data为获取到的操作菜单响应结果，否则为错误对象。 | 348 349**错误码：** 350 351以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 352 353| 错误码ID | 错误信息 | 354| -------- | ---------------------------------- | 355| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 356| 100001 | Internal error. | 357 358**示例：** 359 360```ts 361import { PromptAction, promptAction } from '@kit.ArkUI'; 362import { BusinessError } from '@kit.BasicServicesKit'; 363 364@Entry 365@Component 366struct Index { 367 promptAction: PromptAction = this.getUIContext().getPromptAction(); 368 369 build() { 370 Column() { 371 Button('showActionMenu') 372 .onClick(() => { 373 try { 374 this.promptAction.showActionMenu({ 375 title: 'Title Info', 376 buttons: [ 377 { 378 text: 'item1', 379 color: '#666666' 380 }, 381 { 382 text: 'item2', 383 color: '#000000' 384 } 385 ] 386 }, (err: BusinessError, data: promptAction.ActionMenuSuccessResponse) => { 387 if (err) { 388 console.error('showActionMenu err: ' + err); 389 return; 390 } 391 console.info('showActionMenu success callback, click button: ' + data.index); 392 }); 393 } catch (error) { 394 let message = (error as BusinessError).message; 395 let code = (error as BusinessError).code; 396 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 397 }; 398 }) 399 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 400 } 401} 402``` 403 404## showActionMenu 405 406showActionMenu(options: promptAction.ActionMenuOptions): Promise<promptAction.ActionMenuSuccessResponse> 407 408创建并显示操作菜单，通过Promise异步回调获取菜单的响应结果。 409 410**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 411 412**系统能力：** SystemCapability.ArkUI.ArkUI.Full 413 414**参数：** 415 416| 参数名 | 类型 | 必填 | 说明 | 417| ------- | ---------------------------------------- | ---- | ------- | 418| options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | 是 | 操作菜单选项。 | 419 420**返回值：** 421 422| 类型 | 说明 | 423| ---------------------------------------- | ------- | 424| Promise<[promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)> | Promise对象，返回菜单的响应结果。 | 425 426**错误码：** 427 428以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 429 430| 错误码ID | 错误信息 | 431| ------ | ---------------------------------- | 432| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 433| 100001 | Internal error. | 434 435**示例：** 436 437该示例通过调用showActionMenu接口，展示了弹出操作菜单以及通过Promise获取操作菜单响应结果的功能。 438 439```ts 440import { PromptAction } from '@kit.ArkUI'; 441@Entry 442@Component 443struct Index { 444 promptAction: PromptAction = this.getUIContext().getPromptAction(); 445 446 build() { 447 Column() { 448 Button('showActionMenu') 449 .onClick(() => { 450 this.promptAction.showActionMenu({ 451 title: 'showActionMenu Title Info', 452 buttons: [ 453 { 454 text: 'item1', 455 color: '#666666' 456 }, 457 { 458 text: 'item2', 459 color: '#000000' 460 }, 461 ] 462 }) 463 .then(data => { 464 console.info('showActionMenu success, click button: ' + data.index); 465 }) 466 .catch((err: Error) => { 467 console.error('showActionMenu error: ' + err); 468 }) 469 }) 470 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 471 } 472} 473``` 474 475## openCustomDialog<sup>12+</sup> 476 477openCustomDialog\<T extends Object>(dialogContent: ComponentContent\<T>, options?: promptAction.BaseDialogOptions): Promise<void> 478 479创建并弹出dialogContent对应的自定义弹窗，使用Promise异步回调。通过该接口弹出的弹窗内容样式完全按照dialogContent中设置的样式显示，即相当于customDialog设置customStyle为true时的显示效果。暂不支持[isModal](js-apis-promptAction.md#basedialogoptions11) = true与[showInSubWindow](js-apis-promptAction.md#basedialogoptions11) = true同时使用。如果同时设置为true时，则只生效showInSubWindow = true。 480 481**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 482 483**系统能力：** SystemCapability.ArkUI.ArkUI.Full 484 485**参数：** 486 487| 参数名 | 类型 | 必填 | 说明 | 488| ------- | ---------------------------------------- | ---- | ------- | 489| dialogContent | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | 490| options | [promptAction.BaseDialogOptions](js-apis-promptAction.md#basedialogoptions11) | 否 | 弹窗样式。 | 491 492**返回值：** 493 494| 类型 | 说明 | 495| ---------------------------------------- | ------- | 496| Promise<void> | Promise对象，无返回结果。 | 497 498**错误码：** 499 500以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 501 502| 错误码ID | 错误信息 | 503| ------ | ---------------------------------- | 504| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 505| 103301 | Dialog content error. The ComponentContent is incorrect. | 506| 103302 | Dialog content already exist. The ComponentContent has already been opened. | 507 508**示例：** 509 510该示例通过监听[系统环境信息](../apis-ability-kit/js-apis-app-ability-configuration.md)（系统语言、深浅色等）的变化，调用[ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) 的[update](../apis-arkui/js-apis-arkui-builderNode.md#update)和[updateConfiguration](../apis-arkui/js-apis-arkui-builderNode.md#updateconfiguration12)实现自定义弹窗的数据更新及节点的全量刷新。 511```ts 512import { ComponentContent } from '@kit.ArkUI'; 513import { AbilityConstant, Configuration, EnvironmentCallback, ConfigurationConstant } from '@kit.AbilityKit'; 514import { BusinessError } from '@kit.BasicServicesKit'; 515import { resourceManager } from '@kit.LocalizationKit'; 516 517class Params { 518 text: string = ""; 519 colorMode: resourceManager.ColorMode = resourceManager.ColorMode.LIGHT 520 521 constructor(text: string, colorMode: resourceManager.ColorMode) { 522 this.text = text 523 this.colorMode = colorMode 524 } 525} 526 527@Builder 528function BuilderDialog(params: Params) { 529 Column() { 530 Text(params.text) 531 .fontSize(50) 532 .fontWeight(FontWeight.Bold) 533 .margin({ bottom: 36 }) 534 }.backgroundColor(params.colorMode == resourceManager.ColorMode.LIGHT ? "#D5D5D5" : "#004AAF") 535} 536 537@Entry 538@Component 539struct Index { 540 @State message: string = "hello"; 541 contentNode: ComponentContent<Params> | null = null; 542 callbackId: number | undefined = 0; 543 544 aboutToAppear(): void { 545 let environmentCallback: EnvironmentCallback = { 546 onMemoryLevel: (level: AbilityConstant.MemoryLevel): void => { 547 }, 548 onConfigurationUpdated: (config: Configuration): void => { 549 console.info(`onConfigurationUpdated ${config}`); 550 this.getUIContext().getHostContext()?.getApplicationContext().resourceManager.getConfiguration((err, 551 config) => { 552 // 调用ComponentContent的update更新colorMode信息 553 this.contentNode?.update(new Params(this.message, config.colorMode)) 554 setTimeout(() => { 555 // 调用ComponentContent的updateConfiguration，触发节点的全量更新 556 this.contentNode?.updateConfiguration() 557 }) 558 }) 559 } 560 } 561 // 注册监听系统环境变化监听器 562 this.callbackId = 563 this.getUIContext().getHostContext()?.getApplicationContext().on('environment', environmentCallback) 564 // 设置应用深浅色跟随系统 565 this.getUIContext() 566 .getHostContext()?.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET) 567 } 568 569 aboutToDisappear() { 570 // 解注册监听系统环境变化的回调 571 this.getUIContext().getHostContext()?.getApplicationContext().off('environment', this.callbackId) 572 this.contentNode?.dispose() 573 } 574 575 build() { 576 Row() { 577 Column() { 578 Button("click me") 579 .onClick(() => { 580 let uiContext = this.getUIContext(); 581 let promptAction = uiContext.getPromptAction(); 582 if (this.contentNode == null && uiContext.getHostContext() != undefined) { 583 this.contentNode = new ComponentContent(uiContext, wrapBuilder(BuilderDialog), new Params(this.message, 584 uiContext.getHostContext()!!.getApplicationContext().resourceManager.getConfigurationSync().colorMode)) 585 } 586 if (this.contentNode == null) { 587 return 588 } 589 promptAction.closeCustomDialog(this.contentNode) 590 promptAction.openCustomDialog(this.contentNode).then(() => { 591 console.info("succeeded") 592 }).catch((error: BusinessError) => { 593 console.error(`OpenCustomDialog args error code is ${error.code}, message is ${error.message}`); 594 }) 595 }) 596 } 597 .width('100%') 598 .height('100%') 599 } 600 .height('100%') 601 } 602} 603``` 604 605## openCustomDialogWithController<sup>18+</sup> 606 607openCustomDialogWithController\<T extends Object>(dialogContent: ComponentContent\<T>, controller: promptAction.DialogController, options?: promptAction.BaseDialogOptions): Promise<void> 608 609创建并弹出dialogContent对应的自定义弹窗，使用Promise异步回调。支持传入弹窗控制器与自定义弹窗绑定，后续可以通过控制器控制自定义弹窗。 610 611通过该接口弹出的弹窗内容样式完全按照dialogContent中设置的样式显示，即相当于customDialog设置customStyle为true时的显示效果。 612 613暂不支持[isModal](js-apis-promptAction.md#basedialogoptions11) = true与[showInSubWindow](js-apis-promptAction.md#basedialogoptions11) = true同时使用。如果同时设置为true时，则只生效showInSubWindow = true。 614 615**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 616 617**系统能力：** SystemCapability.ArkUI.ArkUI.Full 618 619**参数：** 620 621| 参数名 | 类型 | 必填 | 说明 | 622| ------- | ---------------------------------------- | ---- | ------- | 623| dialogContent | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | 624| controller | [promptAction.DialogController](js-apis-promptAction.md#dialogcontroller18) | 是 | 自定义弹窗的控制器。 | 625| options | [promptAction.BaseDialogOptions](js-apis-promptAction.md#basedialogoptions11) | 否 | 自定义弹窗的样式。 | 626 627**返回值：** 628 629| 类型 | 说明 | 630| ---------------------------------------- | ------- | 631| Promise<void> | Promise对象，无返回结果。 | 632 633**错误码：** 634 635以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 636 637| 错误码ID | 错误信息 | 638| ------ | ---------------------------------- | 639| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 640| 103301 | Dialog content error. The ComponentContent is incorrect. | 641| 103302 | Dialog content already exist. The ComponentContent has already been opened. | 642 643**示例：** 644 645该示例通过调用openCustomDialog接口，展示了支持传入弹窗控制器与自定义弹窗绑定的功能。 646 647```ts 648import { BusinessError } from '@kit.BasicServicesKit'; 649import { ComponentContent, promptAction } from '@kit.ArkUI'; 650 651class Params { 652 text: string = ""; 653 dialogController: promptAction.DialogController = new promptAction.DialogController(); 654 655 constructor(text: string, dialogController: promptAction.DialogController) { 656 this.text = text; 657 this.dialogController = dialogController; 658 } 659} 660 661@Builder 662function buildText(params: Params) { 663 Column() { 664 Text(params.text) 665 .fontSize(50) 666 .fontWeight(FontWeight.Bold) 667 .margin({ bottom: 36 }) 668 Button('点我关闭弹窗：通过外部传递的DialogController') 669 .onClick(() => { 670 if (params.dialogController != undefined) { 671 params.dialogController.close(); 672 } 673 }) 674 }.backgroundColor('#FFF0F0F0') 675} 676 677@Entry 678@ComponentV2 679struct Index { 680 @Local message: string = "hello"; 681 private dialogController: promptAction.DialogController = new promptAction.DialogController(); 682 683 build() { 684 Row() { 685 Column() { 686 Button("click me") 687 .onClick(() => { 688 let uiContext = this.getUIContext(); 689 let promptAction = uiContext.getPromptAction(); 690 let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), 691 new Params(this.message, this.dialogController)); 692 promptAction.openCustomDialogWithController(contentNode, this.dialogController) 693 .then(() => { 694 console.info('succeeded'); 695 }) 696 .catch((error: BusinessError) => { 697 console.error(`OpenCustomDialogWithController args error code is ${error.code}, message is ${error.message}`); 698 }) 699 }) 700 } 701 .width('100%') 702 .height('100%') 703 } 704 .height('100%') 705 } 706} 707``` 708 709## closeCustomDialog<sup>12+</sup> 710 711closeCustomDialog\<T extends Object>(dialogContent: ComponentContent\<T>): Promise<void> 712 713关闭已弹出的dialogContent对应的自定义弹窗，使用Promise异步回调。 714 715**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 716 717**系统能力：** SystemCapability.ArkUI.ArkUI.Full 718 719**参数：** 720 721| 参数名 | 类型 | 必填 | 说明 | 722| ------- | ---------------------------------------- | ---- | ------- | 723| dialogContent | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | 724 725**返回值：** 726 727| 类型 | 说明 | 728| ---------------------------------------- | ------- | 729| Promise<void> | Promise对象，无返回结果。 | 730 731**错误码：** 732 733以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 734 735| 错误码ID | 错误信息 | 736| ------ | ---------------------------------- | 737| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 738| 103301 | Dialog content error. The ComponentContent is incorrect. | 739| 103303 | Dialog content not found. The ComponentContent cannot be found. | 740 741**示例：** 742 743该示例通过调用closeCustomDialog接口，关闭已弹出的dialogContent对应的自定义弹窗。 744 745```ts 746import { BusinessError } from '@kit.BasicServicesKit'; 747import { ComponentContent } from '@kit.ArkUI'; 748 749class Params { 750 text: string = ""; 751 752 constructor(text: string) { 753 this.text = text; 754 } 755} 756 757@Builder 758function buildText(params: Params) { 759 Column() { 760 Text(params.text) 761 .fontSize(50) 762 .fontWeight(FontWeight.Bold) 763 .margin({ bottom: 36 }) 764 }.backgroundColor('#FFF0F0F0') 765} 766 767@Entry 768@Component 769struct Index { 770 @State message: string = "hello"; 771 772 build() { 773 Row() { 774 Column() { 775 Button("click me") 776 .onClick(() => { 777 let uiContext = this.getUIContext(); 778 let promptAction = uiContext.getPromptAction(); 779 let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), new Params(this.message)); 780 promptAction.openCustomDialog(contentNode) 781 .then(() => { 782 console.info('succeeded'); 783 }) 784 .catch((error: BusinessError) => { 785 console.error(`OpenCustomDialog args error code is ${error.code}, message is ${error.message}`); 786 }) 787 setTimeout(() => { 788 promptAction.closeCustomDialog(contentNode) 789 .then(() => { 790 console.info('succeeded'); 791 }) 792 .catch((error: BusinessError) => { 793 console.error(`OpenCustomDialog args error code is ${error.code}, message is ${error.message}`); 794 }) 795 }, 2000); //2秒后自动关闭 796 }) 797 } 798 .width('100%') 799 .height('100%') 800 } 801 .height('100%') 802 } 803} 804``` 805 806## updateCustomDialog<sup>12+</sup> 807 808updateCustomDialog\<T extends Object>(dialogContent: ComponentContent\<T>, options: promptAction.BaseDialogOptions): Promise<void> 809 810更新已弹出的dialogContent对应的自定义弹窗的样式，使用Promise异步回调。 811 812**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 813 814**系统能力：** SystemCapability.ArkUI.ArkUI.Full 815 816**参数：** 817 818| 参数名 | 类型 | 必填 | 说明 | 819| ------- | ---------------------------------------- | ---- | ------- | 820| dialogContent | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | 自定义弹窗中显示的组件内容。 | 821| options | [promptAction.BaseDialogOptions](js-apis-promptAction.md#basedialogoptions11) | 是 | 弹窗样式，目前仅支持更新alignment、offset、autoCancel、maskColor。 | 822 823**返回值：** 824 825| 类型 | 说明 | 826| ---------------------------------------- | ------- | 827| Promise<void> | Promise对象，无返回结果。 | 828 829**错误码：** 830 831以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 832 833| 错误码ID | 错误信息 | 834| ------ | ---------------------------------- | 835| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 836| 103301 | Dialog content error. The ComponentContent is incorrect. | 837| 103303 | Dialog content not found. The ComponentContent cannot be found. | 838 839**示例：** 840 841该示例通过调用updateCustomDialog接口，动态调整已弹出自定义弹窗的位置。 842 843```ts 844import { BusinessError } from '@kit.BasicServicesKit'; 845import { ComponentContent } from '@kit.ArkUI'; 846 847class Params { 848 text: string = ""; 849 850 constructor(text: string) { 851 this.text = text; 852 } 853} 854 855@Builder 856function buildText(params: Params) { 857 Column() { 858 Text(params.text) 859 .fontSize(50) 860 .fontWeight(FontWeight.Bold) 861 .margin({ bottom: 36 }) 862 }.backgroundColor('#FFF0F0F0') 863} 864 865@Entry 866@Component 867struct Index { 868 @State message: string = "hello"; 869 870 build() { 871 Row() { 872 Column() { 873 Button("click me") 874 .onClick(() => { 875 let uiContext = this.getUIContext(); 876 let promptAction = uiContext.getPromptAction(); 877 let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), new Params(this.message)); 878 promptAction.openCustomDialog(contentNode) 879 .then(() => { 880 console.info('succeeded'); 881 }) 882 .catch((error: BusinessError) => { 883 console.error(`updateCustomDialog args error code is ${error.code}, message is ${error.message}`); 884 }) 885 886 setTimeout(() => { 887 promptAction.updateCustomDialog(contentNode, { alignment: DialogAlignment.CenterEnd }) 888 .then(() => { 889 console.info('succeeded'); 890 }) 891 .catch((error: BusinessError) => { 892 console.error(`updateCustomDialog args error code is ${error.code}, message is ${error.message}`); 893 }) 894 }, 2000); //2秒后自动更新弹窗位置 895 }) 896 } 897 .width('100%') 898 .height('100%') 899 } 900 .height('100%') 901 } 902} 903``` 904 905## openCustomDialog<sup>12+</sup> 906 907openCustomDialog(options: promptAction.CustomDialogOptions): Promise\<number> 908 909创建并弹出自定义弹窗。使用Promise异步回调返回对话框的id，可供closeCustomDialog使用。暂不支持isModal = true与showInSubWindow = true同时使用。如果同时设置为true时，则只生效showInSubWindow = true。 910 911**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 912 913**系统能力：** SystemCapability.ArkUI.ArkUI.Full 914 915**参数：** 916 917| 参数名 | 类型 | 必填 | 说明 | 918| ------- | ------------------------------------------------------------ | ---- | ------------------ | 919| options | [promptAction.CustomDialogOptions](js-apis-promptAction.md#customdialogoptions11) | 是 | 自定义弹窗的内容。 | 920 921**返回值：** 922 923| 类型 | 说明 | 924| ------------------- | --------------------------------------- | 925| Promise<number> | Promise对象。返回对话框id，可供closeCustomDialog使用。 | 926 927**错误码：** 928 929以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 930 931| 错误码ID | 错误信息 | 932| -------- | ------------------------------------------------------------ | 933| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 934| 100001 | Internal error. | 935 936## presentCustomDialog<sup>18+</sup> 937 938presentCustomDialog(builder: CustomBuilder \| CustomBuilderWithId, controller?: promptAction.DialogController, options?: promptAction.DialogOptions): Promise\<number> 939 940创建并弹出自定义弹窗。使用Promise异步回调返回对话框的id，可供closeCustomDialog使用。 941 942支持在自定义弹窗内容中持有弹窗ID进行对应操作。支持传入弹窗控制器与自定义弹窗绑定，后续可以通过控制器控制自定义弹窗。 943 944暂不支持isModal = true与showInSubWindow = true同时使用。如果同时设置为true时，则只生效showInSubWindow = true。 945 946**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 947 948**系统能力：** SystemCapability.ArkUI.ArkUI.Full 949 950**参数：** 951 952| 参数名 | 类型 | 必填 | 说明 | 953| ------- | ------------------------------------------------------------ | ---- | ------------------ | 954| builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [CustomBuilderWithId](arkts-apis-uicontext-t.md#custombuilderwithid18) | 是 | 自定义弹窗的内容。 | 955| controller | [promptAction.DialogController](js-apis-promptAction.md#dialogcontroller18) | 否 | 自定义弹窗的控制器。 | 956| options | [promptAction.DialogOptions](js-apis-promptAction.md#dialogoptions18) | 否 | 自定义弹窗的样式。 | 957 958**返回值：** 959 960| 类型 | 说明 | 961| ------------------- | --------------------------------------- | 962| Promise<number> | Promise对象。返回自定义弹窗ID。 | 963 964**错误码：** 965 966以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 967 968| 错误码ID | 错误信息 | 969| -------- | ------------------------------------------------------------ | 970| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 971| 100001 | Internal error. | 972 973**示例：** 974 975```ts 976import { BusinessError } from '@kit.BasicServicesKit'; 977import { PromptAction, promptAction } from '@kit.ArkUI'; 978 979@Entry 980@ComponentV2 981struct Index { 982 @Local message: string = "hello"; 983 private ctx: UIContext = this.getUIContext(); 984 private promptAction: PromptAction = this.ctx.getPromptAction(); 985 private dialogController: promptAction.DialogController = new promptAction.DialogController(); 986 987 private customDialogComponentId: number = 0; 988 @Builder customDialogComponent() { 989 Column() { 990 Text(this.message).fontSize(30) 991 Row({ space: 10 }) { 992 Button("通过DialogId关闭").onClick(() => { 993 this.promptAction.closeCustomDialog(this.customDialogComponentId); 994 }) 995 Button("通过DialogController关闭").onClick(() => { 996 this.dialogController.close(); 997 }) 998 } 999 }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) 1000 } 1001 1002 @Builder customDialogComponentWithId(dialogId: number) { 1003 Column() { 1004 Text(this.message).fontSize(30) 1005 Row({ space: 10 }) { 1006 Button("通过DialogId关闭").onClick(() => { 1007 this.promptAction.closeCustomDialog(dialogId); 1008 }) 1009 Button("通过DialogController关闭").onClick(() => { 1010 this.dialogController.close(); 1011 }) 1012 } 1013 }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) 1014 } 1015 1016 build() { 1017 Row() { 1018 Column({ space: 10 }) { 1019 Button('presentCustomDialog') 1020 .fontSize(20) 1021 .onClick(() => { 1022 this.promptAction.presentCustomDialog(() => { 1023 this.customDialogComponent() 1024 }, this.dialogController) 1025 .then((dialogId: number) => { 1026 this.customDialogComponentId = dialogId; 1027 }) 1028 .catch((err: BusinessError) => { 1029 console.error("presentCustomDialog error: " + err.code + " " + err.message); 1030 }) 1031 }) 1032 Button('presentCustomDialog with id') 1033 .fontSize(20) 1034 .onClick(() => { 1035 this.promptAction.presentCustomDialog((dialogId: number) => { 1036 this.customDialogComponentWithId(dialogId) 1037 }, this.dialogController) 1038 .catch((err: BusinessError) => { 1039 console.error("presentCustomDialog with id error: " + err.code + " " + err.message); 1040 }) 1041 }) 1042 } 1043 .width('100%') 1044 .height('100%') 1045 } 1046 .height('100%') 1047 } 1048} 1049``` 1050 1051## closeCustomDialog<sup>12+</sup> 1052 1053closeCustomDialog(dialogId: number): void 1054 1055关闭自定义弹窗。 1056 1057**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1058 1059**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1060 1061**参数：** 1062 1063| 参数名 | 类型 | 必填 | 说明 | 1064| -------- | ------ | ---- | -------------------------------- | 1065| dialogId | number | 是 | openCustomDialog返回的对话框id。 | 1066 1067**错误码：** 1068 1069以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1070 1071| 错误码ID | 错误信息 | 1072| -------- | ------------------------------------------------------------ | 1073| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1074| 100001 | Internal error. | 1075 1076**示例：** 1077 1078```ts 1079import { PromptAction } from '@kit.ArkUI'; 1080 1081@Entry 1082@Component 1083struct Index { 1084 promptAction: PromptAction = this.getUIContext().getPromptAction(); 1085 private customDialogComponentId: number = 0; 1086 1087 @Builder 1088 customDialogComponent() { 1089 Column() { 1090 Text('弹窗').fontSize(30) 1091 Row({ space: 50 }) { 1092 Button("确认").onClick(() => { 1093 this.promptAction.closeCustomDialog(this.customDialogComponentId); 1094 }) 1095 Button("取消").onClick(() => { 1096 this.promptAction.closeCustomDialog(this.customDialogComponentId); 1097 }) 1098 } 1099 }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) 1100 } 1101 1102 build() { 1103 Row() { 1104 Column() { 1105 Button("click me") 1106 .onClick(() => { 1107 this.promptAction.openCustomDialog({ 1108 builder: () => { 1109 this.customDialogComponent() 1110 }, 1111 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 1112 console.info(`reason ${dismissDialogAction.reason}`); 1113 console.info('dialog onWillDismiss'); 1114 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 1115 dismissDialogAction.dismiss(); 1116 } 1117 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 1118 dismissDialogAction.dismiss(); 1119 } 1120 } 1121 }).then((dialogId: number) => { 1122 this.customDialogComponentId = dialogId; 1123 }) 1124 }) 1125 } 1126 .width('100%') 1127 .height('100%') 1128 } 1129 .height('100%') 1130 } 1131} 1132``` 1133 1134## getTopOrder<sup>18+</sup> 1135 1136getTopOrder(): LevelOrder 1137 1138返回最顶层显示的弹窗的顺序。 1139 1140获取最顶层显示的弹窗的顺序，可以在下一个弹窗时指定期望的顺序。 1141 1142**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1143 1144**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1145 1146**返回值：** 1147 1148| 类型 | 说明 | 1149| ------------------- | --------------------------------------- | 1150| [LevelOrder](js-apis-promptAction.md#levelorder18) | 返回弹窗层级信息。 | 1151 1152**示例：** 1153 1154该示例通过调用getTopOrder接口，展示了获取最顶层显示弹窗顺序的功能。 1155 1156```ts 1157import { ComponentContent, PromptAction, LevelOrder, promptAction, UIContext } from '@kit.ArkUI'; 1158import { BusinessError } from '@kit.BasicServicesKit'; 1159 1160class Params { 1161 text: string = ""; 1162 constructor(text: string) { 1163 this.text = text; 1164 } 1165} 1166 1167@Builder 1168function buildText(params: Params) { 1169 Column({ space: 20 }) { 1170 Text(params.text) 1171 .fontSize(50) 1172 .fontWeight(FontWeight.Bold) 1173 .margin({ bottom: 36 }) 1174 }.backgroundColor('#FFF0F0F0') 1175} 1176 1177@Entry 1178@Component 1179struct Index { 1180 @State message: string = '弹窗'; 1181 private ctx: UIContext = this.getUIContext(); 1182 private promptAction: PromptAction = this.ctx.getPromptAction(); 1183 private contentNode: ComponentContent<Object> = 1184 new ComponentContent(this.ctx, wrapBuilder(buildText), new Params(this.message)); 1185 1186 private baseDialogOptions: promptAction.BaseDialogOptions = { 1187 showInSubWindow: false, 1188 levelOrder: LevelOrder.clamp(30.1), 1189 }; 1190 1191 build() { 1192 Row() { 1193 Column({ space: 10 }) { 1194 Button('openCustomDialog弹窗') 1195 .fontSize(20) 1196 .onClick(() => { 1197 this.promptAction.openCustomDialog(this.contentNode, this.baseDialogOptions) 1198 .catch((err: BusinessError) => { 1199 console.error("openCustomDialog error: " + err.code + " " + err.message); 1200 }) 1201 .then(() => { 1202 let topOrder: LevelOrder = this.promptAction.getTopOrder(); 1203 if (topOrder !== undefined) { 1204 console.error('topOrder: ' + topOrder.getOrder()); 1205 } 1206 }) 1207 }) 1208 }.width('100%') 1209 }.height('100%') 1210 } 1211} 1212``` 1213 1214## getBottomOrder<sup>18+</sup> 1215 1216getBottomOrder(): LevelOrder 1217 1218获取最底层显示的弹窗的顺序，可以在下一个弹窗时指定期望的顺序。 1219 1220**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1221 1222**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1223 1224**返回值：** 1225 1226| 类型 | 说明 | 1227| ------------------- | --------------------------------------- | 1228| [LevelOrder](js-apis-promptAction.md#levelorder18) | 返回弹窗层级信息。 | 1229 1230**示例：** 1231 1232该示例通过调用getBottomOrder接口，展示了获取最底层显示弹窗顺序的功能。 1233 1234```ts 1235import { ComponentContent, PromptAction, LevelOrder, promptAction, UIContext } from '@kit.ArkUI'; 1236import { BusinessError } from '@kit.BasicServicesKit'; 1237 1238class Params { 1239 text: string = ""; 1240 constructor(text: string) { 1241 this.text = text; 1242 } 1243} 1244 1245@Builder 1246function buildText(params: Params) { 1247 Column({ space: 20 }) { 1248 Text(params.text) 1249 .fontSize(50) 1250 .fontWeight(FontWeight.Bold) 1251 .margin({ bottom: 36 }) 1252 }.backgroundColor('#FFF0F0F0') 1253} 1254 1255@Entry 1256@Component 1257struct Index { 1258 @State message: string = '弹窗'; 1259 private ctx: UIContext = this.getUIContext(); 1260 private promptAction: PromptAction = this.ctx.getPromptAction(); 1261 private contentNode: ComponentContent<Object> = 1262 new ComponentContent(this.ctx, wrapBuilder(buildText), new Params(this.message)); 1263 1264 private baseDialogOptions: promptAction.BaseDialogOptions = { 1265 showInSubWindow: false, 1266 levelOrder: LevelOrder.clamp(30.1), 1267 }; 1268 1269 build() { 1270 Row() { 1271 Column({ space: 10 }) { 1272 Button('openCustomDialog弹窗') 1273 .fontSize(20) 1274 .onClick(() => { 1275 this.promptAction.openCustomDialog(this.contentNode, this.baseDialogOptions) 1276 .catch((err: BusinessError) => { 1277 console.error("openCustomDialog error: " + err.code + " " + err.message); 1278 }) 1279 .then(() => { 1280 let bottomOrder: LevelOrder = this.promptAction.getBottomOrder(); 1281 if (bottomOrder !== undefined) { 1282 console.error('bottomOrder: ' + bottomOrder.getOrder()); 1283 } 1284 }) 1285 }) 1286 }.width('100%') 1287 }.height('100%') 1288 } 1289} 1290``` 1291 1292## openPopup<sup>18+</sup> 1293 1294openPopup\<T extends Object>(content: ComponentContent\<T>, target: TargetInfo, options?: PopupCommonOptions): Promise<void> 1295 1296创建并弹出以content作为内容的Popup弹窗，使用Promise异步回调。 1297 1298> **说明：** 1299> 1300> 1. 使用该接口时，若未传入有效的target，则无法弹出popup弹窗。 1301> 1302> 2. 由于[updatePopup](#updatepopup18)和[closePopup](#closepopup18)依赖content去更新或者关闭指定的popup弹窗，开发者需自行维护传入的content。 1303> 1304> 3. 如果在wrapBuilder中包含其他组件（例如：[Popup](arkui-ts/ohos-arkui-advanced-Popup.md)、[Chip](arkui-ts/ohos-arkui-advanced-Chip.md)组件），则[ComponentContent](./js-apis-arkui-ComponentContent.md#componentcontent-1)应采用带有四个参数的构造函数constructor，其中options参数应传递{ nestingBuilderSupported: true }。 1305 1306**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1307 1308**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1309 1310**参数：** 1311 1312| 参数名 | 类型 | 必填 | 说明 | 1313| ------- | ---------------------------------------- | ---- | ------- | 1314| content | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | popup弹窗中显示的组件内容。 | 1315| target | [TargetInfo](arkts-apis-uicontext-i.md#targetinfo18) | 是 | 需要绑定组件的信息。 | 1316| options | [PopupCommonOptions](arkui-ts/ts-universal-attributes-popup.md#popupcommonoptions18类型说明) | 否 | popup弹窗样式。 | 1317 1318**返回值：** 1319 1320| 类型 | 说明 | 1321| ---------------------------------------- | ------- | 1322| Promise<void> | Promise对象，无返回结果。 | 1323 1324**错误码：** 1325 1326以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1327 1328| 错误码ID | 错误信息 | 1329| ------ | ---------------------------------- | 1330| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1331| 103301 | The ComponentContent is incorrect. | 1332| 103302 | The ComponentContent already exists. | 1333| 103304 | The targetId does not exist. | 1334| 103305 | The node of targetId is not in the component tree. | 1335 1336**示例：** 1337 1338该示例通过调用openPopup、updatePopup和closePopup接口，展示了弹出、更新以及关闭Popup的功能。 1339 1340```ts 1341import { ComponentContent, FrameNode } from '@kit.ArkUI'; 1342import { BusinessError } from '@kit.BasicServicesKit'; 1343 1344interface PopupParam { 1345 updateFunc?: () => void; 1346 closeFunc?: () => void; 1347} 1348 1349export function showPopup(context: UIContext, uniqueId: number, contentNode: ComponentContent<PopupParam>, 1350 popupParam: PopupParam) { 1351 const promptAction = context.getPromptAction(); 1352 let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); 1353 let targetId = frameNode?.getFirstChild()?.getUniqueId(); 1354 promptAction.openPopup(contentNode, { id: targetId }, { 1355 radius: 16, 1356 mask: { color: Color.Pink }, 1357 enableArrow: true, 1358 }) 1359 .then(() => { 1360 console.info('openPopup success'); 1361 }) 1362 .catch((err: BusinessError) => { 1363 console.error('openPopup error: ' + err.code + ' ' + err.message); 1364 }) 1365 popupParam.updateFunc = () => { 1366 promptAction.updatePopup(contentNode, { 1367 enableArrow: false 1368 }, true) 1369 .then(() => { 1370 console.info('updatePopup success'); 1371 }) 1372 .catch((err: BusinessError) => { 1373 console.error('updatePopup error: ' + err.code + ' ' + err.message); 1374 }) 1375 } 1376 popupParam.closeFunc = () => { 1377 promptAction.closePopup(contentNode) 1378 .then(() => { 1379 console.info('closePopup success'); 1380 }) 1381 .catch((err: BusinessError) => { 1382 console.error('closePopup error: ' + err.code + ' ' + err.message); 1383 }) 1384 } 1385} 1386 1387@Builder 1388function buildText(param?: PopupParam) { 1389 Column() { 1390 Text('popup') 1391 Button('Update Popup') 1392 .fontSize(20) 1393 .onClick(() => { 1394 param?.updateFunc?.(); 1395 }) 1396 Button('Close Popup') 1397 .fontSize(20) 1398 .onClick(() => { 1399 param?.closeFunc?.(); 1400 }) 1401 } 1402} 1403 1404@Entry 1405@Component 1406struct Index { 1407 build() { 1408 Column() { 1409 Button('Open Popup') 1410 .fontSize(20) 1411 .onClick(() => { 1412 let context = this.getUIContext(); 1413 const popupParam: PopupParam = {}; 1414 const contentNode = new ComponentContent(context, wrapBuilder(buildText), popupParam); 1415 showPopup(context, this.getUniqueId(), contentNode, popupParam); 1416 }) 1417 } 1418 } 1419} 1420``` 1421 1422## updatePopup<sup>18+</sup> 1423 1424updatePopup\<T extends Object>(content: ComponentContent\<T>, options: PopupCommonOptions, partialUpdate?: boolean ): Promise<void> 1425 1426更新content对应的Popup弹窗的样式，使用Promise异步回调。 1427 1428> **说明：** 1429> 1430> 不支持更新showInSubWindow、focusable、onStateChange、onWillDismiss、transition。 1431> 1432 1433**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1434 1435**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1436 1437**参数：** 1438 1439| 参数名 | 类型 | 必填 | 说明 | 1440| ------- | ---------------------------------------- | ---- | ------- | 1441| content | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | popup弹窗中显示的组件内容。 | 1442| options | [PopupCommonOptions](arkui-ts/ts-universal-attributes-popup.md#popupcommonoptions18类型说明) | 是 | popup弹窗样式。<br/>**说明：** <br/>不支持更新showInSubWindow、focusable、onStateChange、onWillDismiss、transition。 | 1443| partialUpdate | boolean | 否 | popup弹窗更新方式, 默认值为false。<br/>**说明：** <br/>1. true为增量更新，保留当前值，更新options中的指定属性。 <br/>2. false为全量更新，除options中的指定属性，其他属性恢复默认值。 | 1444 1445**返回值：** 1446 1447| 类型 | 说明 | 1448| ---------------------------------------- | ------- | 1449| Promise<void> | Promise对象，无返回结果。 | 1450 1451**错误码：** 1452 1453以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1454 1455| 错误码ID | 错误信息 | 1456| ------ | ---------------------------------- | 1457| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1458| 103301 | The ComponentContent is incorrect. | 1459| 103303 | The ComponentContent cannot be found. | 1460 1461**示例：** 1462 1463请参考[openPopup](#openpopup18)示例。 1464 1465## closePopup<sup>18+</sup> 1466 1467closePopup\<T extends Object>(content: ComponentContent\<T>): Promise<void> 1468 1469关闭content对应的Popup弹窗，使用Promise异步回调。 1470 1471**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1472 1473**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1474 1475**参数：** 1476 1477| 参数名 | 类型 | 必填 | 说明 | 1478| ------- | ---------------------------------------- | ---- | ------- | 1479| content | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | popup弹窗中显示的组件内容。 | 1480 1481**返回值：** 1482 1483| 类型 | 说明 | 1484| ---------------------------------------- | ------- | 1485| Promise<void> | Promise对象，无返回结果。 | 1486 1487**错误码：** 1488 1489以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1490 1491| 错误码ID | 错误信息 | 1492| ------ | ---------------------------------- | 1493| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1494| 103301 | The ComponentContent is incorrect. | 1495| 103303 | The ComponentContent cannot be found. | 1496 1497**示例：** 1498 1499请参考[openPopup](#openpopup18)示例。 1500 1501## openMenu<sup>18+</sup> 1502 1503openMenu\<T extends Object>(content: ComponentContent\<T>, target: TargetInfo, options?: MenuOptions): Promise<void> 1504 1505创建并弹出以content作为内容的Menu弹窗。使用Promise异步回调。 1506 1507> **说明：** 1508> 1509> 1. 使用该接口时，若未传入有效的target，则无法弹出menu弹窗。 1510> 1511> 2. 由于[updateMenu](#updatemenu18)和[closeMenu](#closemenu18)依赖content去更新或者关闭指定的menu弹窗，开发者需自行维护传入的content。 1512> 1513> 3. 如果在wrapBuilder中包含其他组件（例如：[Popup](arkui-ts/ohos-arkui-advanced-Popup.md)、[Chip](arkui-ts/ohos-arkui-advanced-Chip.md)组件），则[ComponentContent](./js-apis-arkui-ComponentContent.md#componentcontent-1)应采用带有四个参数的构造函数constructor，其中options参数应传递{ nestingBuilderSupported: true }。 1514> 1515> 4. 子窗弹窗里不能再弹出子窗弹窗，例如[openMenu](#openmenu18)设置了showInSubWindow为true时，则不能再弹出另一个设置了showInSubWindow为true的弹窗。 1516 1517**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1518 1519**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1520 1521**参数：** 1522 1523| 参数名 | 类型 | 必填 | 说明 | 1524| ------- | ---------------------------------------- | ---- | ------- | 1525| content | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | menu弹窗中显示的组件内容。 | 1526| target | [TargetInfo](arkts-apis-uicontext-i.md#targetinfo18) | 是 | 需要绑定组件的信息。 | 1527| options | [MenuOptions](./arkui-ts/ts-universal-attributes-menu.md#menuoptions10) | 否 | menu弹窗样式。<br/>**说明：**<br/>title属性不生效。<br/>preview参数仅支持设置MenuPreviewMode类型。 | 1528 1529**返回值：** 1530 1531| 类型 | 说明 | 1532| ---------------------------------------- | ------- | 1533| Promise<void> | Promise对象，无返回结果。 | 1534 1535**错误码：** 1536 1537以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1538 1539| 错误码ID | 错误信息 | 1540| ------ | ---------------------------------- | 1541| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1542| 103301 | The ComponentContent is incorrect. | 1543| 103302 | The ComponentContent already exists. | 1544| 103304 | The targetId does not exist. | 1545| 103305 | The node of targetId is not in the component tree. | 1546 1547**示例：** 1548 1549该示例通过调用openMenu接口，展示了弹出Menu的功能。 1550 1551```ts 1552import { ComponentContent, FrameNode } from '@kit.ArkUI'; 1553 1554export function doSomething(context: UIContext, uniqueId: number, contentNode: ComponentContent<Object>) { 1555 showMenu(context, uniqueId, contentNode); 1556} 1557 1558@Builder 1559function MyMenu() { 1560 Column() { 1561 Menu() { 1562 MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项1" }) 1563 MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项2" }) 1564 } 1565 } 1566 .width('80%') 1567 .padding('20lpx') 1568} 1569 1570export function showMenu(context: UIContext, uniqueId: number, contentNode: ComponentContent<Object>) { 1571 const promptAction = context.getPromptAction(); 1572 let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); 1573 let frameNodeTarget = frameNode?.getFirstChild(); 1574 frameNodeTarget = frameNodeTarget?.getChild(0); 1575 let targetId = frameNodeTarget?.getUniqueId(); 1576 promptAction.openMenu(contentNode, { id: targetId }, { 1577 enableArrow: true, 1578 }); 1579} 1580 1581@Entry 1582@Component 1583struct Index { 1584 build() { 1585 Column() { 1586 Button('OpenMenu', { type: ButtonType.Normal, stateEffect: true }) 1587 .borderRadius('16lpx') 1588 .width('80%') 1589 .margin(10) 1590 .onClick(() => { 1591 let context = this.getUIContext(); 1592 const contentNode = new ComponentContent(context, wrapBuilder(MyMenu)); 1593 doSomething(context, this.getUniqueId(), contentNode); 1594 }) 1595 } 1596 } 1597} 1598``` 1599 1600## updateMenu<sup>18+</sup> 1601 1602updateMenu\<T extends Object>(content: ComponentContent\<T>, options: MenuOptions, partialUpdate?: boolean ): Promise<void> 1603 1604更新content对应的Menu弹窗的样式。使用Promise异步回调。 1605 1606> **说明：** 1607> 1608> 不支持更新showInSubWindow、preview、previewAnimationOptions、transition、onAppear、aboutToAppear、onDisappear、aboutToDisappear、onWillAppear、onDidAppear、onWillDisappear和onDidDisappear。 1609> 1610> 支持mask通过设置[MenuMaskType](./arkui-ts/ts-universal-attributes-menu.md#menumasktype20类型说明)实现更新蒙层样式，不支持mask通过设置boolean实现蒙层从无到有或者从有到无的更新。 1611> 1612 1613**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1614 1615**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1616 1617**参数：** 1618 1619| 参数名 | 类型 | 必填 | 说明 | 1620| ------- | ---------------------------------------- | ---- | ------- | 1621| content | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | menu弹窗中显示的组件内容。 | 1622| options | [MenuOptions](./arkui-ts/ts-universal-attributes-menu.md#menuoptions10) | 是 | menu弹窗样式。<br/>**说明：** <br/>1. 不支持更新showInSubWindow、preview、previewAnimationOptions、transition、onAppear、aboutToAppear、onDisappear、aboutToDisappear、onWillAppear、onDidAppear、onWillDisappear和onDidDisappear。<br/>2. 支持mask通过设置[MenuMaskType](./arkui-ts/ts-universal-attributes-menu.md#menumasktype20类型说明)实现更新蒙层样式，不支持mask通过设置boolean实现蒙层从无到有或者从有到无的更新。 | 1623| partialUpdate | boolean | 否 | menu弹窗更新方式，默认值为false。<br/>**说明：** <br/>1. true为增量更新，保留当前值，更新options中的指定属性。 <br/>2. false为全量更新，除options中的指定属性，其他属性恢复默认值。 | 1624 1625**返回值：** 1626 1627| 类型 | 说明 | 1628| ---------------------------------------- | ------- | 1629| Promise<void> | Promise对象，无返回结果。 | 1630 1631**错误码：** 1632 1633以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1634 1635| 错误码ID | 错误信息 | 1636| ------ | ---------------------------------- | 1637| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1638| 103301 | The ComponentContent is incorrect. | 1639| 103303 | The ComponentContent cannot be found. | 1640 1641**示例：** 1642 1643该示例通过调用updateMenu接口，展示了更新Menu箭头样式的功能。 1644 1645```ts 1646import { ComponentContent, FrameNode } from '@kit.ArkUI'; 1647 1648export function doSomething(context: UIContext, uniqueId: number, contentNode: ComponentContent<Object>) { 1649 showMenu(context, uniqueId, contentNode); 1650} 1651 1652@Builder 1653function MyMenu() { 1654 Column() { 1655 Menu() { 1656 MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项1" }) 1657 MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项2" }) 1658 } 1659 } 1660 .width('80%') 1661 .padding('20lpx') 1662} 1663 1664export function showMenu(context: UIContext, uniqueId: number, contentNode: ComponentContent<Object>) { 1665 const promptAction = context.getPromptAction(); 1666 let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); 1667 let frameNodeTarget = frameNode?.getFirstChild(); 1668 frameNodeTarget = frameNodeTarget?.getChild(0); 1669 let targetId = frameNodeTarget?.getUniqueId(); 1670 promptAction.openMenu(contentNode, { id: targetId }, { 1671 enableArrow: true, 1672 }); 1673 setTimeout(() => { 1674 promptAction.updateMenu(contentNode, { 1675 enableArrow: false, 1676 }); 1677 }, 2000); 1678} 1679 1680@Entry 1681@Component 1682struct Index { 1683 build() { 1684 Column() { 1685 Button('OpenMenu', { type: ButtonType.Normal, stateEffect: true }) 1686 .borderRadius('16lpx') 1687 .width('80%') 1688 .margin(10) 1689 .onClick(() => { 1690 let context = this.getUIContext(); 1691 const contentNode = new ComponentContent(context, wrapBuilder(MyMenu)); 1692 doSomething(context, this.getUniqueId(), contentNode); 1693 }) 1694 } 1695 } 1696} 1697``` 1698 1699## closeMenu<sup>18+</sup> 1700 1701closeMenu\<T extends Object>(content: ComponentContent\<T>): Promise<void> 1702 1703关闭content对应的Menu弹窗。使用Promise异步回调。 1704 1705**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1706 1707**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1708 1709**参数：** 1710 1711| 参数名 | 类型 | 必填 | 说明 | 1712| ------- | ---------------------------------------- | ---- | ------- | 1713| content | [ComponentContent\<T>](./js-apis-arkui-ComponentContent.md) | 是 | menu弹窗中显示的组件内容。 | 1714 1715**返回值：** 1716 1717| 类型 | 说明 | 1718| ---------------------------------------- | ------- | 1719| Promise<void> | Promise对象，无返回结果。 | 1720 1721**错误码：** 1722 1723以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1724 1725| 错误码ID | 错误信息 | 1726| ------ | ---------------------------------- | 1727| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1728| 103301 | The ComponentContent is incorrect. | 1729| 103303 | The ComponentContent cannot be found. | 1730 1731**示例：** 1732 1733该示例通过调用closeMenu接口，展示了关闭Menu的功能。 1734 1735```ts 1736import { ComponentContent, FrameNode } from '@kit.ArkUI'; 1737 1738export function doSomething(context: UIContext, uniqueId: number, contentNode: ComponentContent<Object>) { 1739 showMenu(context, uniqueId, contentNode); 1740} 1741 1742@Builder 1743function MyMenu() { 1744 Column() { 1745 Menu() { 1746 MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项1" }) 1747 MenuItem({ startIcon: $r("app.media.startIcon"), content: "菜单选项2" }) 1748 } 1749 } 1750 .width('80%') 1751 .padding('20lpx') 1752} 1753 1754export function showMenu(context: UIContext, uniqueId: number, contentNode: ComponentContent<Object>) { 1755 const promptAction = context.getPromptAction(); 1756 let frameNode: FrameNode | null = context.getFrameNodeByUniqueId(uniqueId); 1757 let frameNodeTarget = frameNode?.getFirstChild(); 1758 frameNodeTarget = frameNodeTarget?.getChild(0); 1759 let targetId = frameNodeTarget?.getUniqueId(); 1760 promptAction.openMenu(contentNode, { id: targetId }, { 1761 enableArrow: true, 1762 }); 1763 setTimeout(() => { 1764 promptAction.closeMenu(contentNode); 1765 }, 2000); 1766} 1767 1768@Entry 1769@Component 1770struct Index { 1771 build() { 1772 Column() { 1773 Button('OpenMenu', { type: ButtonType.Normal, stateEffect: true }) 1774 .borderRadius('16lpx') 1775 .width('80%') 1776 .margin(10) 1777 .onClick(() => { 1778 let context = this.getUIContext(); 1779 const contentNode = new ComponentContent(context, wrapBuilder(MyMenu)); 1780 doSomething(context, this.getUniqueId(), contentNode); 1781 }) 1782 } 1783 } 1784} 1785``` 1786## showActionMenu<sup>(deprecated)</sup> 1787 1788showActionMenu(options: promptAction.ActionMenuOptions, callback: [promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse)): void 1789 1790创建并显示操作菜单，菜单响应结果异步返回。 1791 1792从API version11开始不再维护，建议使用[showActionMenu](#showactionmenu11)。 1793 1794**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 1795 1796**参数：** 1797 1798| 参数名 | 类型 | 必填 | 说明 | 1799| -------- | ------------------------------------------------------------ | ---- | ------------------ | 1800| options | [promptAction.ActionMenuOptions](js-apis-promptAction.md#actionmenuoptions) | 是 | 操作菜单选项。 | 1801| callback | [promptAction.ActionMenuSuccessResponse](js-apis-promptAction.md#actionmenusuccessresponse) | 是 | 菜单响应结果回调。 | 1802 1803**错误码：** 1804 1805以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[弹窗错误码](errorcode-promptAction.md)。 1806 1807| 错误码ID | 错误信息 | 1808| ------ | ---------------------------------- | 1809| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1810| 100001 | Internal error. | 1811 1812**示例：** 1813 1814该示例通过调用showActionMenu接口，展示了弹出操作菜单以及返回菜单响应结果的功能。 1815 1816```ts 1817import { PromptAction } from '@kit.ArkUI'; 1818import { BusinessError } from '@kit.BasicServicesKit'; 1819 1820@Entry 1821@Component 1822struct Index { 1823 promptAction: PromptAction = this.getUIContext().getPromptAction(); 1824 1825 build() { 1826 Column() { 1827 Button('showActionMenu') 1828 .onClick(() => { 1829 try { 1830 this.promptAction.showActionMenu({ 1831 title: 'Title Info', 1832 buttons: [ 1833 { 1834 text: 'item1', 1835 color: '#666666' 1836 }, 1837 { 1838 text: 'item2', 1839 color: '#000000' 1840 } 1841 ] 1842 }, { index: 0 }); 1843 } catch (error) { 1844 let message = (error as BusinessError).message; 1845 let code = (error as BusinessError).code; 1846 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 1847 } 1848 ; 1849 }) 1850 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 1851 } 1852} 1853```