1# @ohos.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 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> 该模块不支持在[UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md)的文件声明处使用，即不能在UIAbility的生命周期中调用，需要在创建组件实例后使用。 16> 17> 本模块功能依赖UI的执行上下文，不可在[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的地方使用，参见[UIContext](arkts-apis-uicontext-uicontext.md)说明。建议<!--Del-->在除[ServiceExtensionAbility](../../application-models/serviceextensionability.md)等无UI界面的场景外，均<!--DelEnd-->使用UIContext中的弹窗方法。 18 19## 导入模块 20 21```ts 22import { promptAction } from '@kit.ArkUI'; 23``` 24 25## promptAction.openToast<sup>18+</sup> 26 27openToast(options: ShowToastOptions): Promise<number> 28 29显示即时反馈并通过Promise返回其id。 30 31> **说明：** 32> 33> 不支持在输入法类型窗口中使用子窗（showMode设置为TOP_MOST或者SYSTEM_TOP_MOST）的openToast，详情见输入法框架的约束与限制说明[createPanel](../apis-ime-kit/js-apis-inputmethodengine.md#createpanel10-1)。 34 35**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39**参数** 40 41| 参数名 | 类型 | 必填 | 说明 | 42| ------- | ------------------------------------------------------------ | ---- | -------------- | 43| options | [ShowToastOptions](#showtoastoptions) | 是 | Toast选项。 | 44 45**返回值** 46 47| 类型 | 说明 | 48| ---------------- | ------------------------------------ | 49| Promise<number> | 返回即时反馈的id，可供closeToast使用。 | 50 51**错误码：** 52 53以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 54 55| 错误码ID | 错误信息 | 56| -------- | ------------------------------------------------------------ | 57| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 58| 100001 | Internal error. | 59 60**示例：** 61 62> **说明：** 63> 64> 直接使用openToast可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用UIContext中的getPromptAction方法获取到PromptAction对象，再通过该对象调用[openToast](arkts-apis-uicontext-promptaction.md#opentoast18)实现。 65 66```ts 67import { BusinessError } from '@kit.BasicServicesKit'; 68import { PromptAction, UIContext } from '@kit.ArkUI'; 69 70@Entry 71@Component 72struct toastExample { 73 @State toastId: number = 0; 74 uiContext: UIContext = this.getUIContext(); 75 promptAction: PromptAction = this.uiContext.getPromptAction(); 76 77 build() { 78 Column() { 79 Button('Open Toast') 80 .height(100) 81 .type(ButtonType.Capsule) 82 .onClick(() => { 83 this.promptAction.openToast({ 84 message: 'Toast Message', 85 duration: 10000, 86 }).then((toastId: number) => { 87 this.toastId = toastId; 88 }) 89 .catch((error: BusinessError) => { 90 console.error(`openToast error code is ${error.code}, message is ${error.message}`); 91 }) 92 }) 93 Blank().height(50) 94 Button('Close Toast') 95 .height(100) 96 .type(ButtonType.Capsule) 97 .onClick(() => { 98 try { 99 this.promptAction.closeToast(this.toastId); 100 } catch (error) { 101 let message = (error as BusinessError).message; 102 let code = (error as BusinessError).code; 103 console.error(`CloseToast error code is ${code}, message is ${message}`); 104 } 105 }) 106 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 107 } 108} 109``` 110 111 112 113## promptAction.closeToast<sup>18+</sup> 114 115closeToast(toastId: number): void 116 117关闭即时反馈。 118 119**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 120 121**系统能力：** SystemCapability.ArkUI.ArkUI.Full 122 123**参数** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ------- | ------ | ---- | ----------------------------- | 127| toastId | number | 是 | openToast返回的id。 | 128 129**错误码：** 130 131以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 132 133| 错误码ID | 错误信息 | 134| -------- | ------------------------------------------------------------ | 135| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 136| 100001 | Internal error. | 137| 103401 | Cannot find the toast. | 138 139**示例：** 140 141> **说明：** 142> 143> 直接使用closeToast可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用UIContext中的getPromptAction方法获取到PromptAction对象，再通过该对象调用[openToast](arkts-apis-uicontext-promptaction.md#closetoast18)实现。 144 145示例请看[promptAction.openToast18](#promptactionopentoast18)的示例。 146 147## ShowToastOptions 148 149Toast的选项。 150 151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 152 153| 名称 | 类型 | 只读 | 可选 | 说明 | 154| ----------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 155| message | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 否 | 显示的文本信息。<br>**说明：** <br/>默认字体为'Harmony Sans'，不支持设置其他字体。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 156| duration | number | 否 | 是 | 设置Toast弹出的持续时间。<br/>默认值：1500ms<br/>取值范围：[1500, 10000]<br/>若小于1500ms则取默认值，若大于10000ms则取上限值10000ms。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 157| bottom | string \| number | 否 | 是 | 设置Toast底部边框距离导航条的高度，软键盘拉起时，如果bottom值过小，toast要被软键盘遮挡时，会自动避让至距离软键盘80vp处。<br/>默认值：80vp<br/>**说明：** <br/>当底部没有导航条时，bottom为设置弹窗底部边框距离窗口底部的高度。<br/>设置对齐方式alignment后，bottom不生效。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 158| showMode<sup>11+</sup> | [ToastShowMode](#toastshowmode11) | 否 | 是 | 设置Toast层级。<br>默认值：ToastShowMode.DEFAULT，默认显示在应用内。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 159| alignment<sup>12+</sup> | [Alignment](arkui-ts/ts-appendix-enums.md#alignment) | 否 | 是 | 对齐方式。<br>**说明：** <br/>不同alignment下，Toast位置对齐效果，如下图所示。<br/><br/>Toast的文本显示默认自左向右，不支持其他对齐方式。<br/>默认值：undefined，默认底部偏上位置。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 160| offset<sup>12+</sup> | [Offset](arkui-ts/ts-types.md#offset) | 否 | 是 | 在对齐方式上的偏移。<br/>默认值：{ dx: 0, dy: 0 }，默认没有偏移。<br/>**说明：** <br/>仅支持设置px类型的数值。如需设置其他类型的数值，应将其他类型转换为px类型后传入。例如，若需设置vp，应将其转换为px后传入。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 161| backgroundColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 是 | Toast的背板颜色。<br/>默认值：Color.Transparent<br/>**说明：** <br/>backgroundColor会与模糊属性backgroundBlurStyle叠加产生效果，如果不符合预期，可将backgroundBlurStyle设置为BlurStyle.NONE，即可取消模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 162| textColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 是 | Toast的文本颜色。<br/>默认值：Color.Black<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 163| backgroundBlurStyle<sup>12+</sup> | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | 否 | 是 | Toast的背板模糊材质。<br/>默认值：BlurStyle.COMPONENT_ULTRA_THICK<br/>**说明：** <br/>设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时，则不要设置backgroundColor，否则颜色显示将不符合预期效果。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 164| shadow<sup>12+</sup> | [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| [ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 否 | 是 | Toast的背板阴影。<br/>默认值：ShadowStyle.OUTER_DEFAULT_MD<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 165| enableHoverMode<sup>14+</sup> | boolean | 否 | 是 | 是否响应悬停态，值为true时，响应悬停态。<br/>默认值：false，默认不响应。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 166| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](arkui-ts/ts-universal-attributes-sheet-transition.md#hovermodeareatype14) | 否 | 是 | 响应悬停态时，弹窗的显示区域。<br/>默认值：HoverModeAreaType.BOTTOM_SCREEN，默认显示在下半屏。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 167 168## ToastShowMode<sup>11+</sup> 169 170设置Toast的显示模式，默认显示在应用内，支持显示在子窗。 171 172**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176| 名称 | 值 | 说明 | 177| -------- | ---- | ---------------------- | 178| DEFAULT | 0 | Toast显示在应用内。 | 179| TOP_MOST | 1 | Toast显示在子窗。 | 180 181## ShowDialogOptions 182 183对话框的选项。 184 185**系统能力：** SystemCapability.ArkUI.ArkUI.Full 186 187| 名称 | 类型 | 只读 | 可选 | 说明 | 188| --------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 189| title | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 是 | 标题文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 190| message | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 是 | 内容文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 191| buttons | Array<[Button](#button)> | 否 | 是 | 对话框中按钮的数组，结构为：{text:'button', color: '\#666666'}，支持大于1个按钮。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 192| 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开始，该接口支持在原子化服务中使用。 | 193| offset<sup>10+</sup> | [Offset](arkui-ts/ts-types.md#offset) | 否 | 是 | 对话框相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 }<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 194| 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/>maskRect在设置[Rectangle](arkui-ts/ts-methods-alert-dialog-box.md#rectangle8类型说明)中的部分属性后，若未设置其余的属性，则其余属性的默认值为0。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 195| showInSubWindow<sup>11+</sup> | boolean | 否 | 是 | 某对话框需要显示在主窗口之外时，是否在子窗口显示此对话框。值为true表示在子窗口显示对话框。<br/>默认值：false，对话框显示在应用内，而非独立子窗口。<br/>**说明：** showInSubWindow为true的对话框无法触发显示另一个showInSubWindow为true的对话框。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 196| isModal<sup>11+</sup> | boolean | 否 | 是 | 对话框是否为模态窗口。值为true表示为模态窗口且有蒙层，不可与对话框周围其他控件进行交互，即蒙层区域无法事件透传。值为false表示为非模态窗口且无蒙层，可以与对话框周围其他控件进行交互。<br/>默认值：true<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 197| backgroundColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 是 | 对话框背板颜色。<br/>默认值：Color.Transparent<br/>**说明：** <br/>backgroundColor会与模糊属性backgroundBlurStyle叠加产生效果，如果不符合预期，可将backgroundBlurStyle设置为BlurStyle.NONE，即可取消模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 198| 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开始，该接口支持在原子化服务中使用。 | 199| backgroundBlurStyleOptions<sup>19+</sup> | [BackgroundBlurStyleOptions](arkui-ts/ts-universal-attributes-background.md#backgroundblurstyleoptions10对象说明) | 否 | 是 | 背景模糊效果。默认值请参考BackgroundBlurStyleOptions类型说明。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 200| backgroundEffect<sup>19+</sup> | [BackgroundEffectOptions](arkui-ts/ts-universal-attributes-background.md#backgroundeffectoptions11) | 否 | 是 | 背景效果参数。默认值请参考BackgroundEffectOptions类型说明。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 201| 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开始，该接口支持在原子化服务中使用。 | 202| enableHoverMode<sup>14+</sup> | boolean | 否 | 是 | 是否响应悬停态，值为true时，响应悬停态。<br />默认值：false，默认不响应。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 203| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](arkui-ts/ts-universal-attributes-sheet-transition.md#hovermodeareatype14) | 否 | 是 | 设置悬停态下对话框的默认展示区域。<br />默认值：HoverModeAreaType.BOTTOM_SCREEN<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 204| onWillAppear<sup>19+</sup> | Callback<void> | 否 | 是 | 对话框显示动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。<br />2.在onWillAppear内设置改变对话框显示效果的回调事件，二次弹出生效。 <br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。| 205| onDidAppear<sup>19+</sup> | Callback<void> | 否 | 是 | 对话框弹出时的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。<br />2.在onDidAppear内设置改变弹窗显示效果的回调事件，二次弹出生效。<br />3.快速点击弹出，关闭对话框时，onWillDisappear在onDidAppear前生效。<br/>4.对话框入场动效未完成时彻底关闭对话框，动效打断，onDidAppear不会触发。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 206| onWillDisappear<sup>19+</sup> | Callback<void> | 否 | 是 | 对话框退出动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。<br /> **原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。| 207| onDidDisappear<sup>19+</sup> | Callback<void> | 否 | 是 | 对话框消失时的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 208| levelMode<sup>15+</sup> | [LevelMode](#levelmode15枚举说明) | 否 | 是 | 设置对话框显示层级。<br />**说明：**<br />- 默认值：LevelMode.OVERLAY<br />- 当且仅当showInSubWindow属性设置为false时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 209| levelUniqueId<sup>15+</sup> | number | 否 | 是 | 设置页面级对话框需要显示的层级下的[节点 uniqueId](js-apis-arkui-frameNode.md#getuniqueid12)。<br/>取值范围：大于等于0的数字。<br />**说明：** <br />- 当且仅当levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 210| immersiveMode<sup>15+</sup> | [ImmersiveMode](#immersivemode15枚举说明) | 否 | 是 | 设置页面内对话框蒙层效果。<br />**说明：**<br />- 默认值：ImmersiveMode.DEFAULT <br />- 当且仅当levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 211| levelOrder<sup>18+</sup> | [LevelOrder](#levelorder18) | 否 | 是 | 设置对话框显示的顺序。<br />**说明：**<br />- 默认值：LevelOrder.clamp(0) <br />- 不支持动态刷新顺序。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 212 213## ShowDialogSuccessResponse 214 215对话框的响应结果。 216 217**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 218 219**系统能力：** SystemCapability.ArkUI.ArkUI.Full 220 221| 名称 | 类型 | 只读 | 可选 | 说明 | 222| ----- | ------ | ---- | ---- | ------------------------------- | 223| index | number | 否 | 否 | 选中按钮在buttons数组中的索引，从0开始。 | 224 225## ActionMenuOptions 226 227操作菜单的选项。 228 229**系统能力：** SystemCapability.ArkUI.ArkUI.Full 230 231| 名称 | 类型 | 只读 | 可选 | 说明 | 232| ----------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 233| title | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 是 | 标题文本。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 234| 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开始，该接口支持在原子化服务中使用。 | 235| showInSubWindow<sup>11+</sup> | boolean | 否 | 是 | 某操作菜单需要显示在主窗口之外时，是否在子窗口显示此菜单。值为true表示在子窗口显示菜单。<br/>默认值：false，在子窗口不显示菜单。<br/>**说明：** <br/> - showInSubWindow为true的菜单无法触发显示另一个showInSubWindow为true的菜单。 <br/> - 若在UIExtension中设置showInSubWindow为true, 菜单将基于UIExtension的宿主窗口对齐。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 236| isModal<sup>11+</sup> | boolean | 否 | 是 | 菜单是否为模态窗口。值为true表示为模态窗口且有蒙层，不可与菜单周围其他控件进行交互，即蒙层区域无法事件透传。值为false表示为非模态窗口且无蒙层，可以与菜单周围其他控件进行交互。<br/>默认值：true<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 237| levelMode<sup>15+</sup> | [LevelMode](#levelmode15枚举说明) | 否 | 是 | 设置菜单显示层级。<br />**说明：**<br />- 默认值：LevelMode.OVERLAY <br />- 当且仅当showInSubWindow属性设置为false时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 238| levelUniqueId<sup>15+</sup> | number | 否 | 是 | 设置页面级菜单需要显示的层级下的[节点 uniqueId](js-apis-arkui-frameNode.md#getuniqueid12)。<br/>取值范围：大于等于0的数字。<br />**说明：**<br />- 当且仅当levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 239| immersiveMode<sup>15+</sup> | [ImmersiveMode](#immersivemode15枚举说明) | 否 | 是 | 设置页面内菜单蒙层效果。<br />**说明：**<br />- 默认值：ImmersiveMode.DEFAULT <br />- 当且仅当levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 240| onWillAppear<sup>20+</sup> | Callback<void> | 否 | 是 | 菜单显示动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。 <br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 241| onDidAppear<sup>20+</sup> | Callback<void> | 否 | 是 | 菜单弹出时的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。<br />2.快速点击弹出，关闭菜单时，onWillDisappear在onDidAppear前生效。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 242| onWillDisappear<sup>20+</sup> | Callback<void> | 否 | 是 | 菜单退出动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。<br /> **原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 243| onDidDisappear<sup>20+</sup> | Callback<void> | 否 | 是 | 菜单消失时的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>onWillDisappear>>onDidDisappear。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 244 245## ActionMenuSuccessResponse 246 247操作菜单的响应结果。 248 249**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 250 251**系统能力：** SystemCapability.ArkUI.ArkUI.Full 252 253| 名称 | 类型 | 只读 | 可选 | 说明 | 254| ----- | ------ | ---- | ---- | ---------------------------------------- | 255| index | number | 否 | 否 | 选中按钮在buttons数组中的索引，从0开始。 | 256 257## CommonState<sup>20+</sup>枚举说明 258 259自定义弹窗的状态。 260 261**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 262 263**系统能力：** SystemCapability.ArkUI.ArkUI.Full 264 265| 名称 | 值 | 说明 | 266| ------------- | ---- | ------------------------------------------ | 267| UNINITIALIZED | 0 | 未初始化，控制器未与dialog绑定时。 | 268| INITIALIZED | 1 | 已初始化，控制器与dialog绑定后。 | 269| APPEARING | 2 | 显示中，dialog显示动画过程中。 | 270| APPEARED | 3 | 已显示，dialog显示动画结束。 | 271| DISAPPEARING | 4 | 消失中，dialog消失动画过程中。 | 272| DISAPPEARED | 5 | 已消失，dialog消失动画结束后。 | 273 274## DialogController<sup>18+</sup> 275 276自定义弹窗控制器，继承自[CommonController](#commoncontroller18)。 277 278DialogController可作为UIContext弹出自定义弹窗的成员变量，具体用法可看[openCustomDialogWithController](arkts-apis-uicontext-promptaction.md#opencustomdialogwithcontroller18)和[presentCustomDialog](arkts-apis-uicontext-promptaction.md#presentcustomdialog18)示例。 279 280**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 281 282**系统能力：** SystemCapability.ArkUI.ArkUI.Full 283 284## CommonController<sup>18+</sup> 285 286公共控制器，可以控制promptAction相关组件。 287 288**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 289 290**系统能力：** SystemCapability.ArkUI.ArkUI.Full 291 292### constructor<sup>18+</sup> 293constructor() 294 295控制器的构造函数。 296 297**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 298 299**系统能力：** SystemCapability.ArkUI.ArkUI.Full 300 301### close<sup>18+</sup> 302close(): void 303 304关闭显示的自定义弹窗，若已关闭，则不生效。 305 306**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 307 308**系统能力：** SystemCapability.ArkUI.ArkUI.Full 309 310### getState<sup>20+</sup> 311 312getState(): CommonState 313 314获取自定义弹窗的状态。 315 316**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 317 318**系统能力：** SystemCapability.ArkUI.ArkUI.Full 319 320**返回值：** 321 322| 类型 | 说明 | 323| ------------------------------------------------- | ------------------ | 324| [CommonState](#commonstate20枚举说明) | 返回对应的弹窗状态。 | 325 326## LevelOrder<sup>18+</sup> 327 328弹窗层级，可以控制弹窗显示的顺序。 329 330**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 331 332**系统能力：** SystemCapability.ArkUI.ArkUI.Full 333 334### clamp<sup>18+</sup> 335static clamp(order: number): LevelOrder 336 337创建指定顺序的弹窗层级。 338 339**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 340 341**系统能力：** SystemCapability.ArkUI.ArkUI.Full 342 343**参数：** 344 345| 参数名 | 类型 | 必填 | 说明 | 346| ------ | ------- | ---- | ------------------------------------------------------------ | 347| order | number | 是 | 弹窗显示顺序。取值范围为[-100000.0, 100000.0]，如果值小于-100000.0则设置为-100000.0，如果值大于100000.0则设置为100000.0。 | 348 349**返回值：** 350 351| 类型 | 说明 | 352| ------ | ------ | 353| [LevelOrder](#levelorder18) | 返回当前对象实例。 | 354 355### getOrder<sup>18+</sup> 356getOrder(): number 357 358获取弹窗显示顺序。 359 360**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 361 362**系统能力：** SystemCapability.ArkUI.ArkUI.Full 363 364**返回值：** 365 366| 类型 | 说明 | 367| ------ | ------ | 368| number | 返回显示顺序数值。 | 369 370## DialogOptions<sup>18+</sup> 371 372自定义弹窗的内容，继承自[BaseDialogOptions](#basedialogoptions11)。 373 374**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 375 376**系统能力：** SystemCapability.ArkUI.ArkUI.Full 377 378| 名称 | 类型 | 只读 | 可选 | 说明 | 379| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 380| backgroundColor | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 是 | 设置弹窗背板颜色。<br/>默认值：Color.Transparent<br/>**说明：** <br/>backgroundColor会与模糊属性backgroundBlurStyle叠加产生效果，如果不符合预期，可将backgroundBlurStyle设置为BlurStyle.NONE，即可取消模糊。 | 381| cornerRadius | [DialogOptionsCornerRadius](#dialogoptionscornerradius18) | 否 | 是 | 设置弹窗背板的圆角半径。<br />可分别设置4个圆角的半径。<br />默认值：{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }<br /> 圆角大小受组件尺寸限制，最大值为组件宽或高的一半，若值为负，则按照默认值处理。 <br /> 百分比参数方式：以父元素弹窗宽和高的百分比来设置弹窗的圆角。| 382| borderWidth | [DialogOptionsBorderWidth](#dialogoptionsborderwidth18) | 否 | 是 | 设置弹窗背板的边框宽度。<br />可分别设置4个边框宽度。<br />默认值：0 <br />单位：vp <br /> 百分比参数方式：以父元素弹窗宽的百分比来设置弹窗的边框宽度。<br />当弹窗左边框和右边框大于弹窗宽度，弹窗上边框和下边框大于弹窗高度，显示可能不符合预期。| 383| borderColor | [DialogOptionsBorderColor](#dialogoptionsbordercolor18) | 否 | 是 | 设置弹窗背板的边框颜色。<br/>默认值：Color.Black <br/> 如果使用borderColor属性，需要和borderWidth属性一起使用。 | 384| borderStyle | [DialogOptionsBorderStyle](#dialogoptionsborderstyle18) | 否 | 是 | 设置弹窗背板的边框样式。<br/>默认值：BorderStyle.Solid。<br/> 如果使用borderStyle属性，需要和borderWidth属性一起使用。 | 385| width | [Dimension](arkui-ts/ts-types.md#dimension10) | 否 | 是 | 设置弹窗背板的宽度。<br />**说明：**<br>- 默认最大值：400vp <br />- 百分比参数方式：弹窗参考宽度基于所在窗口宽度调整。| 386| height | [Dimension](arkui-ts/ts-types.md#dimension10) | 否 | 是 | 设置弹窗背板的高度。<br />**说明：**<br />- 默认最大值：0.9 *（窗口高度 - 安全区域）。<br />- 百分比参数方式：弹窗参考高度为（窗口高度 - 安全区域），在此基础上调小或调大。| 387| shadow | [DialogOptionsShadow](#dialogoptionsshadow18) | 否 | 是 | 设置弹窗背板的阴影。<br />当设备为2in1时，默认场景下获焦阴影值为ShadowStyle.OUTER_FLOATING_MD，失焦为ShadowStyle.OUTER_FLOATING_SM。其他设备默认无阴影。 | 388| backgroundBlurStyle | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | 否 | 是 | 弹窗背板模糊材质。<br/>默认值：BlurStyle.COMPONENT_ULTRA_THICK<br/>**说明：** <br/>设置为BlurStyle.NONE即可关闭背景虚化。当设置了backgroundBlurStyle为非NONE值时，则不要设置backgroundColor，否则颜色显示将不符合预期效果。 | 389 390## DialogOptionsCornerRadius<sup>18+</sup> 391 392type DialogOptionsCornerRadius = Dimension \| BorderRadiuses 393 394表示弹窗背板的圆角半径允许的数据字段类型。 395 396**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 397 398**系统能力：** SystemCapability.ArkUI.ArkUI.Full 399 400| 类型 | 说明 | 401| ------------------------------------------------------------ | ---------------------------- | 402| [Dimension](arkui-ts/ts-types.md#dimension10) | 表示值类型为长度类型，用于描述尺寸单位。 | 403| [BorderRadiuses](arkui-ts/ts-types.md#borderradiuses9) | 表示值类型为圆角类型，用于描述组件边框圆角半径。 | 404 405## DialogOptionsBorderWidth<sup>18+</sup> 406 407type DialogOptionsBorderWidth = Dimension \| EdgeWidths 408 409表示弹窗背板的边框宽度允许的数据字段类型。 410 411**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 412 413**系统能力：** SystemCapability.ArkUI.ArkUI.Full 414 415| 类型 | 说明 | 416| ------------------------------------------------------------ | ---------------------------- | 417| [Dimension](arkui-ts/ts-types.md#dimension10) | 表示值类型为长度类型，用于描述尺寸单位。 | 418| [EdgeWidths](arkui-ts/ts-types.md#edgewidths9) | 表示值类型为边框宽度类型，用于描述组件边框不同方向的宽度。 | 419 420## DialogOptionsBorderColor<sup>18+</sup> 421 422type DialogOptionsBorderColor = ResourceColor \| EdgeColors 423 424表示弹窗背板的边框颜色允许的数据字段类型。 425 426**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 427 428**系统能力：** SystemCapability.ArkUI.ArkUI.Full 429 430| 类型 | 说明 | 431| ------------------------------------------------------------ | ---------------------------- | 432| [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 表示值类型为颜色类型，用于描述资源颜色类型。 | 433| [EdgeColors](arkui-ts/ts-types.md#edgecolors9) | 表示值类型为边框颜色，用于描述组件边框四条边的颜色。 | 434 435## DialogOptionsBorderStyle<sup>18+</sup> 436 437type DialogOptionsBorderStyle = BorderStyle \| EdgeStyles 438 439表示弹窗背板的边框样式允许的数据字段类型。 440 441**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 442 443**系统能力：** SystemCapability.ArkUI.ArkUI.Full 444 445| 类型 | 说明 | 446| ------------------------------------------------------------ | ---------------------------- | 447| [BorderStyle](arkui-ts/ts-appendix-enums.md#borderstyle) | 表示值类型为边框类型，用于描述组件边框的类型。 | 448| [EdgeStyles](arkui-ts/ts-types.md#edgestyles9) | 表示值类型为边框样式，用于描述组件边框四条边的样式。 | 449 450## DialogOptionsShadow<sup>18+</sup> 451 452type DialogOptionsShadow = ShadowOptions \| ShadowStyle 453 454表示弹窗背板的阴影允许的数据字段类型。 455 456**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 457 458**系统能力：** SystemCapability.ArkUI.ArkUI.Full 459 460| 类型 | 说明 | 461| ------------------------------------------------------------ | ---------------------------- | 462| [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions对象说明) | 表示值类型为阴影属性集合，用于设置阴影的模糊半径、阴影的颜色、X轴和Y轴的偏移量。 | 463| [ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10枚举说明) | 表示值类型为阴影类型，用于描述阴影的类型。 | 464 465## CustomDialogOptions<sup>11+</sup> 466 467自定义弹窗的内容，继承自[BaseDialogOptions](#basedialogoptions11)。 468 469**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 470 471**系统能力：** SystemCapability.ArkUI.ArkUI.Full 472 473| 名称 | 类型 | 只读 | 可选 | 说明 | 474| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 475| builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | 否 | 否 | 设置自定义弹窗的内容。<br/>**说明：** <br/>builder需要赋值为箭头函数，格式如下：() => { this.XXX() }，其中XXX是内部builder名。<br/>全局builder需要在组件内部创建，并在内部builder中调用。<br/>builder根节点宽高百分比相对弹窗容器大小。<br/>builder非根节点宽高百分比相对父节点大小。 | 476| backgroundColor <sup>12+</sup>| [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 是 | 设置弹窗背板颜色。<br/>默认值：Color.Transparent<br/>**说明：** <br/>当设置了backgroundColor为非透明色时，backgroundBlurStyle需要设置为BlurStyle.NONE，否则颜色显示将不符合预期效果。 | 477| 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 /> 百分比参数方式：以父元素弹窗宽和高的百分比来设置弹窗的圆角。| 478| borderWidth<sup>12+</sup>| [Dimension](arkui-ts/ts-types.md#dimension10) \| [EdgeWidths](arkui-ts/ts-types.md#edgewidths9) | 否 | 是 | 设置弹窗背板的边框宽度。<br />可分别设置4个边框宽度。<br />默认值：0 <br />单位：vp <br /> 百分比参数方式：以父元素弹窗宽的百分比来设置弹窗的边框宽度。<br />当弹窗左边框和右边框大于弹窗宽度，弹窗上边框和下边框大于弹窗高度，显示可能不符合预期。 | 479| borderColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) \| [EdgeColors](arkui-ts/ts-types.md#edgecolors9) | 否 | 是 | 设置弹窗背板的边框颜色。<br/>默认值：Color.Black<br/> 如果使用borderColor属性，需要和borderWidth属性一起使用。 | 480| 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属性一起使用。 | 481| width<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10) | 否 | 是 | 设置弹窗背板的宽度。<br />**说明：**<br>- 弹窗宽度默认最大值：400vp <br />- 百分比参数方式：弹窗参考宽度基于所在窗口的宽度的基础上调整。| 482| height<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10) | 否 | 是 | 设置弹窗背板的高度。<br />**说明：**<br />- 弹窗高度默认最大值：0.9 *（窗口高度 - 安全区域）。<br />- 百分比参数方式：弹窗参考高度为（窗口高度 - 安全区域），在此基础上调小或调大。| 483| 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。其他设备默认无阴影。 | 484| 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，否则颜色显示将不符合预期效果。 | 485 486## BaseDialogOptions<sup>11+</sup> 487 488弹窗的选项。 489 490**系统能力：** SystemCapability.ArkUI.ArkUI.Full 491 492| 名称 | 类型 | 只读 | 可选 | 说明 | 493| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 494| 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不生效。<br/>maskRect在设置[Rectangle](arkui-ts/ts-methods-alert-dialog-box.md#rectangle8类型说明)中的部分属性后，若未设置其余的属性，则其余属性的默认值为0。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 495| alignment | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment枚举说明) | 否 | 是 | 弹窗在竖直方向上的对齐方式。<br>默认值：DialogAlignment.Default <br/>**说明：**<br/>若在UIExtension中设置showInSubWindow为true, 弹窗将基于UIExtension的宿主窗口对齐。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 496| offset | [Offset](arkui-ts/ts-types.md#offset) | 否 | 是 | 弹窗相对alignment所在位置的偏移量。<br/>默认值：{ dx: 0 , dy: 0 } <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 497| isModal | boolean | 否 | 是 | 弹窗是否为模态窗口。值为true表示为模态窗口且有蒙层，不可与弹窗周围其他控件进行交互，即蒙层区域无法事件透传。值为false表示为非模态窗口且无蒙层，可以与弹窗周围其他控件进行交互。<br/>默认值：true<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 498| showInSubWindow | boolean | 否 | 是 | 某弹窗需要显示在主窗口之外时，是否在子窗口显示此弹窗。值为true表示在子窗口显示弹窗。<br/>默认值：false，弹窗显示在应用内，而非独立子窗口。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 499| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | 否 | 是 | 交互式关闭回调函数。<br/>**说明：** <br/>1.当用户执行点击遮障层关闭、侧滑（左滑/右滑）、三键back、键盘ESC关闭交互操作时，如果注册该回调函数，则不会立刻关闭弹窗。在回调函数中可以通过reason得到阻拦关闭弹窗的操作类型，从而根据原因选择是否能关闭弹窗。当前组件返回的reason中，暂不支持CLOSE_BUTTON的枚举值。<br/>2.在onWillDismiss回调中，不能再做onWillDismiss拦截。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 500| autoCancel<sup>12+</sup> | boolean | 否 | 是 | 点击遮障层时，是否关闭弹窗，true表示关闭弹窗。false表示不关闭弹窗。<br/>默认值：true <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 501| maskColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 否 | 是 | 自定义蒙层颜色。<br>默认值: 0x33000000 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 502| transition<sup>12+</sup> | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 是 | 设置弹窗显示和退出的过渡效果。<br/>**说明：**<br/> 1.如果不设置，则使用默认的显示/退出动效。<br/> 2.显示动效中按back键，打断显示动效，执行退出动效，动画效果为显示动效与退出动效的曲线叠加后的效果。<br/> 3.退出动效中按back键，不会打断退出动效，退出动效继续执行，继续按back键退出应用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 503| dialogTransition<sup>19+</sup> | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 是 | 设置弹窗内容显示的过渡效果。默认无动效。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 504| maskTransition<sup>19+</sup> | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10对象说明) | 否 | 是 | 设置蒙层显示的过渡效果。默认无动效。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 505| onDidAppear<sup>12+</sup> | () => void | 否 | 是 | 弹窗弹出时的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.在onDidAppear内设置改变弹窗显示效果的回调事件，二次弹出生效。<br />3.快速点击弹出，消失弹窗时，存在onWillDisappear在onDidAppear前生效。<br />4. 当弹窗入场动效未完成时关闭弹窗，该回调不会触发。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 506| onDidDisappear<sup>12+</sup> | () => void | 否 | 是 | 弹窗消失时的事件回调。<br />**说明：**<br />正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。 <br/>当弹窗退场动画未完成时（例如：同时触发弹窗关闭和页面切换），该回调不会触发。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 507| onWillAppear<sup>12+</sup> | () => void | 否 | 是 | 弹窗显示动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.在onWillAppear内设置改变弹窗显示效果的回调事件，二次弹出生效。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 508| onWillDisappear<sup>12+</sup> | () => void | 否 | 是 | 弹窗退出动效前的事件回调。<br />**说明：**<br />1.正常时序依次为：onWillAppear>>onDidAppear>>(onDateAccept/onCancel/onDateChange)>>onWillDisappear>>onDidDisappear。<br />2.快速点击弹出，消失弹窗时，存在onWillDisappear在onDidAppear前生效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 509| keyboardAvoidMode<sup>12+</sup> | [KeyboardAvoidMode](./arkui-ts/ts-universal-attributes-popup.md#keyboardavoidmode12枚举说明) | 否 | 是 | 用于设置弹窗是否在拉起软键盘时进行自动避让。<br/>默认值：KeyboardAvoidMode.DEFAULT<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 510| enableHoverMode<sup>14+</sup> | boolean | 否 | 是 | 是否响应悬停态，值为true时，响应悬停态。<br />默认值：false，默认不响应。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| 511| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](arkui-ts/ts-universal-attributes-sheet-transition.md#hovermodeareatype14) | 否 | 是 | 悬停态下弹窗默认展示区域。<br />默认值：HoverModeAreaType.BOTTOM_SCREEN<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 512| backgroundBlurStyleOptions<sup>19+</sup> | [BackgroundBlurStyleOptions](arkui-ts/ts-universal-attributes-background.md#backgroundblurstyleoptions10对象说明) | 否 | 是 | 背景模糊效果。默认值请参考BackgroundBlurStyleOptions类型说明。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 513| backgroundEffect<sup>19+</sup> | [BackgroundEffectOptions](arkui-ts/ts-universal-attributes-background.md#backgroundeffectoptions11) | 否 | 是 | 背景效果参数。默认值请参考BackgroundEffectOptions类型说明。<br />**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 | 514| keyboardAvoidDistance<sup>15+</sup> | [LengthMetrics](js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 是 | 弹窗避让键盘后，和键盘之间距离。<br />**说明：**<br/>- 默认值：16vp<br />- 默认单位：vp<br />- 当且仅当keyboardAvoidMode属性设置为DEFAULT时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 | 515| levelMode<sup>15+</sup> | [LevelMode](#levelmode15枚举说明) | 否 | 是 | 设置弹窗显示层级。<br />**说明：**<br />- 默认值：LevelMode.OVERLAY <br />- 当且仅当showInSubWindow属性设置为false时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 516| levelUniqueId<sup>15+</sup> | number | 否 | 是 | 设置页面级弹窗需要显示的层级下的[节点 uniqueId](js-apis-arkui-frameNode.md#getuniqueid12)。<br/>取值范围：大于等于0的数字。<br />**说明：** <br />- 当且仅当levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 517| immersiveMode<sup>15+</sup> | [ImmersiveMode](#immersivemode15枚举说明) | 否 | 是 | 设置页面内弹窗蒙层效果。<br />**说明：**<br />- 默认值：ImmersiveMode.DEFAULT <br />- 当且仅当levelMode属性设置为LevelMode.EMBEDDED时生效。<br/>**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。| 518| levelOrder<sup>18+</sup> | [LevelOrder](#levelorder18) | 否 | 是 | 设置弹窗显示的顺序。<br />**说明：**<br />- 默认值：LevelOrder.clamp(0) <br />- 不支持动态刷新顺序。<br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 519| focusable<sup>19+</sup> | boolean | 否 | 是 | 设置弹窗是否获取焦点。值为true表示获取焦点，值为false表示不获取焦点。<br />默认值：true <br />**说明：**<br />只有弹出覆盖在当前窗口之上的弹窗才可以获取焦点。<br/>**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。| 520 521## DismissDialogAction<sup>12+</sup> 522 523Dialog关闭的信息。 524 525**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 526 527**系统能力：** SystemCapability.ArkUI.ArkUI.Full 528 529### 属性 530 531| 名称 | 类型 | 只读 | 可选 | 说明 | 532| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 533| dismiss | Callback<void> | 否 | 否 | Dialog关闭回调函数。开发者需要退出时调用，不需要退出时无需调用。 | 534| reason | [DismissReason](./arkui-ts/ts-universal-attributes-popup.md#dismissreason12枚举说明) | 否 | 否 | Dialog无法关闭原因。根据开发者需求选择不同操作下，Dialog是否关闭。 | 535 536## LevelMode<sup>15+</sup>枚举说明 537 538弹窗显示层级模式。 539 540**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 541 542**系统能力：** SystemCapability.ArkUI.ArkUI.Full 543 544| 名称 | 值 | 说明 | 545| ------- | ---- | ------------------------------------------------ | 546| OVERLAY | 0 | 弹窗层级为应用窗口根节点，应用内路由导航切换弹窗不隐藏。 | 547| EMBEDDED | 1 | 弹窗节点为页面内路由/导航下的节点，随路由导航切换，弹窗随页面隐藏。| 548 549## ImmersiveMode<sup>15+</sup>枚举说明 550 551页面内弹窗蒙层显示区域模式。 552 553**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 554 555**系统能力：** SystemCapability.ArkUI.ArkUI.Full 556 557| 名称 | 值 | 说明 | 558| ------- | ---- | ------------------------------------------------ | 559| DEFAULT | 0 | 弹窗蒙层遵循父节点布局约束进行显示。 | 560| EXTEND | 1 | 弹窗蒙层可扩展至覆盖状态栏和导航条。 561 562## Button 563 564菜单中的菜单项按钮。 565 566**系统能力：** SystemCapability.ArkUI.ArkUI.Full 567 568| 名称 | 类型 | 只读 | 可选 | 说明 | 569| ----- | ---------------------------------------- | ---- | ------- | ------- | 570| text | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 否 | 按钮文本内容。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 571| color | string \| [Resource](arkui-ts/ts-types.md#resource) | 否 | 否 | 按钮文本颜色。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 572| primary<sup>12+</sup> | boolean | 否 | 是 | 在弹窗获焦且未进行tab键走焦时，按钮是否默认响应Enter键。多个Button时，只允许一个Button的该字段配置为true，否则所有Button均不响应。多重弹窗可自动获焦连续响应。值为true表示按钮默认响应Enter键，值为false时，按钮不默认响应Enter键。<br/>默认值：false<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 573 574## 示例 575 576该示例实现了在promptAction.DialogController中调用getState获取弹窗当前状态。 577 578```ts 579// xxx.ets 580import { BusinessError } from '@kit.BasicServicesKit'; 581import { ComponentContent, promptAction } from '@kit.ArkUI'; 582 583@Component 584struct CustomDialogExample { 585 build() { 586 Column() { 587 Text('Hello') 588 .fontSize(50) 589 .fontWeight(FontWeight.Bold) 590 .margin({ bottom: 36 }) 591 Button('点我关闭弹窗') 592 .onClick(() => { 593 if (this.getDialogController()) { 594 this.getDialogController().close(); 595 } 596 }) 597 Button('点我获取状态') 598 .onClick(() => { 599 if (this.getDialogController()) { 600 let state: promptAction.CommonState = this.getDialogController().getState(); 601 console.info('state:' + state); // 打印弹窗状态 602 } 603 }) 604 605 }.backgroundColor('#FFF0F0F0') 606 } 607} 608 609@Builder 610function buildText() { 611 CustomDialogExample() 612} 613 614@Entry 615@Component 616struct Index { 617 618 private dialogController: promptAction.DialogController = new promptAction.DialogController() 619 620 build() { 621 Row() { 622 Column() { 623 Button("click me") 624 .onClick(() => { 625 let uiContext = this.getUIContext(); 626 let promptAction = uiContext.getPromptAction(); 627 let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), 628 ); 629 630 promptAction.openCustomDialogWithController(contentNode, this.dialogController, { 631 632 transition: TransitionEffect.OPACITY.animation({ 633 duration: 3000 634 }) 635 }).then(() => { 636 console.info('succeeded') 637 }).catch((error: BusinessError) => { 638 console.error(`OpenCustomDialogWithController args error code is ${error.code}, message is ${error.message}`); 639 }) 640 }) 641 } 642 .width('100%') 643 .height('100%') 644 } 645 .height('100%') 646 } 647} 648``` 649 650## promptAction.showToast<sup>(deprecated)</sup> 651 652showToast(options: ShowToastOptions): void 653 654创建并显示即时反馈。 655 656> **说明：** 657> 658> 从API version 18开始废弃，且直接使用showToast可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[showToast](arkts-apis-uicontext-promptaction.md#showtoast)。 659> 660> 从API version 10开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](arkts-apis-uicontext-promptaction.md)对象。 661> 662> Toast样式单一，不支持内容的自定义，具体支持能力请参考[ShowToastOptions](#showtoastoptions)提供的接口。 663 664**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 665 666**系统能力：** SystemCapability.ArkUI.ArkUI.Full 667 668**参数：** 669 670| 参数名 | 类型 | 必填 | 说明 | 671| ------- | ------------------------------------- | ---- | -------------- | 672| options | [ShowToastOptions](#showtoastoptions) | 是 | Toast选项。 | 673 674**错误码：** 675 676以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 677 678| 错误码ID | 错误信息 | 679| -------- | ------------------------------------------------------------ | 680| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 681| 100001 | Internal error. | 682 683**示例：** 684 685```ts 686import { promptAction } from '@kit.ArkUI'; 687import { BusinessError } from '@kit.BasicServicesKit'; 688 689@Entry 690@Component 691struct toastExample { 692 build() { 693 Column() { 694 Button('Show toast').fontSize(20) 695 .onClick(() => { 696 try { 697 promptAction.showToast({ 698 message: 'Hello World', 699 duration: 2000 700 }); 701 } catch (error) { 702 let message = (error as BusinessError).message; 703 let code = (error as BusinessError).code; 704 console.error(`showToast args error code is ${code}, message is ${message}`); 705 }; 706 }) 707 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 708 } 709} 710``` 711 712API version 11及之前Toast样式。 713 714 715 716API version 12及之后Toast样式。 717 718 719 720## promptAction.showDialog<sup>(deprecated)</sup> 721 722showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse> 723 724创建并显示对话框，对话框通过Promise返回结果。 725 726> **说明：** 727> 728> 从API version 18开始废弃，且直接使用showDialog可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[showDialog](arkts-apis-uicontext-promptaction.md#showdialog-1)。 729> 730> 从API version 10开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](arkts-apis-uicontext-promptaction.md)对象。 731 732**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 733 734**系统能力：** SystemCapability.ArkUI.ArkUI.Full 735 736**参数：** 737 738| 参数名 | 类型 | 必填 | 说明 | 739| ------- | --------------------------------------- | ---- | ------------ | 740| options | [ShowDialogOptions](#showdialogoptions) | 是 | 对话框选项。 | 741 742**返回值：** 743 744| 类型 | 说明 | 745| ------------------------------------------------------------ | ---------------- | 746| Promise<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 对话框响应结果。 | 747 748**错误码：** 749 750以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 751 752| 错误码ID | 错误信息 | 753| -------- | ------------------------------------------------------------ | 754| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 755| 100001 | Internal error. | 756 757**示例：** 758 759```ts 760import { promptAction } from '@kit.ArkUI'; 761 762promptAction.showDialog({ 763 title: 'Title Info', 764 message: 'Message Info', 765 buttons: [ 766 { 767 text: 'button1', 768 color: '#000000' 769 }, 770 { 771 text: 'button2', 772 color: '#000000' 773 } 774 ], 775}) 776 .then(data => { 777 console.info('showDialog success, click button: ' + data.index); 778 }) 779 .catch((err: Error) => { 780 console.info('showDialog error: ' + err); 781 }) 782``` 783 784 785 786## promptAction.showDialog<sup>(deprecated)</sup> 787 788showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse>):void 789 790创建并显示对话框，对话框响应结果异步返回。 791 792> **说明：** 793> 794> 从API version 18开始废弃，且直接使用showDialog可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[showDialog](arkts-apis-uicontext-promptaction.md#showdialog)。 795> 796> 从API version 10开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](arkts-apis-uicontext-promptaction.md)对象。 797 798**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 799 800**系统能力：** SystemCapability.ArkUI.ArkUI.Full 801 802**参数：** 803 804| 参数名 | 类型 | 必填 | 说明 | 805| -------- | ------------------------------------------------------------ | ---- | ------------------------ | 806| options | [ShowDialogOptions](#showdialogoptions) | 是 | 页面显示对话框信息描述。 | 807| callback | AsyncCallback<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | 是 | 对话框响应结果回调。 | 808 809**错误码：** 810 811以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 812 813| 错误码ID | 错误信息 | 814| -------- | ------------------------------------------------------------ | 815| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 816| 100001 | Internal error. | 817 818**示例：** 819 820```ts 821import { promptAction } from '@kit.ArkUI'; 822import { BusinessError } from '@kit.BasicServicesKit'; 823 824try { 825 promptAction.showDialog({ 826 title: 'showDialog Title Info', 827 message: 'Message Info', 828 buttons: [ 829 { 830 text: 'button1', 831 color: '#000000' 832 }, 833 { 834 text: 'button2', 835 color: '#000000' 836 } 837 ] 838 }, (err, data) => { 839 if (err) { 840 console.info('showDialog err: ' + err); 841 return; 842 } 843 console.info('showDialog success callback, click button: ' + data.index); 844 }); 845} catch (error) { 846 let message = (error as BusinessError).message; 847 let code = (error as BusinessError).code; 848 console.error(`showDialog args error code is ${code}, message is ${message}`); 849}; 850``` 851 852 853 854当弹窗的showInSubWindow属性为true时，弹窗可显示在窗口外。 855 856```ts 857import { promptAction } from '@kit.ArkUI'; 858import { BusinessError } from '@kit.BasicServicesKit'; 859 860try { 861 promptAction.showDialog({ 862 title: 'showDialog Title Info', 863 message: 'Message Info', 864 isModal: true, 865 showInSubWindow: true, 866 buttons: [ 867 { 868 text: 'button1', 869 color: '#000000' 870 }, 871 { 872 text: 'button2', 873 color: '#000000' 874 } 875 ] 876 }, (err, data) => { 877 if (err) { 878 console.info('showDialog err: ' + err); 879 return; 880 } 881 console.info('showDialog success callback, click button: ' + data.index); 882 }); 883} catch (error) { 884 let message = (error as BusinessError).message; 885 let code = (error as BusinessError).code; 886 console.error(`showDialog args error code is ${code}, message is ${message}`); 887}; 888``` 889 890 891 892以下示例展示了弹窗生命周期的相关接口的使用方法。 893 894```ts 895// xxx.ets 896import { BusinessError } from '@kit.BasicServicesKit'; 897 898@Entry 899@Component 900struct DialogExample { 901 @State log: string = 'Log information:'; 902 build() { 903 Column() { 904 Button('showDialog') 905 .onClick(() => { 906 this.showCustomDialog(); 907 }) 908 Text(this.log).fontSize(30).margin({ top: 200 }) 909 }.width('100%').margin({ top: 5 }) 910 } 911 912 showCustomDialog() { 913 try { 914 this.getUIContext().getPromptAction().showDialog({ 915 title: '操作确认', 916 message: '您确定要执行此操作吗？', 917 alignment: DialogAlignment.Bottom, 918 buttons: [ 919 { 920 text: '取消', 921 color: '#999999' 922 }, 923 { 924 text: '确定', 925 color: '#007DFF' 926 } 927 ], 928 onDidAppear: () => { 929 this.log += '# onDidAppear'; 930 console.info("showDialog,is onDidAppear!"); 931 }, 932 onDidDisappear: () => { 933 this.log += '# onDidDisappear'; 934 console.info("showDialog,is onDidDisappear!"); 935 }, 936 onWillAppear: () => { 937 this.log = 'Log information:#onWillAppear'; 938 console.info("showDialog,is onWillAppear!"); 939 }, 940 onWillDisappear: () => { 941 this.log += '# onWillDisappear'; 942 console.info("showDialog,is onWillDisappear!"); 943 }, 944 }) 945 } catch (error) { 946 let err: BusinessError = error as BusinessError; 947 console.error(`捕获到异常: ${err.code}, ${err.message}`); 948 } 949 } 950} 951``` 952 953 954 955 956 957## promptAction.showActionMenu<sup>(deprecated)</sup> 958 959showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void 960 961创建并显示操作菜单，菜单响应结果异步返回。 962 963> **说明：** 964> 965> 从API version 18开始废弃，且直接使用showActionMenu可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[showActionMenu](arkts-apis-uicontext-promptaction.md#showactionmenu11)。 966> 967> 从API version 11开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](arkts-apis-uicontext-promptaction.md)对象。 968 969**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 970 971**系统能力：** SystemCapability.ArkUI.ArkUI.Full。 972 973**参数：** 974 975| 参数名 | 类型 | 必填 | 说明 | 976| -------- | ------------------------------------------------------------ | ---- | ------------------ | 977| options | [ActionMenuOptions](#actionmenuoptions) | 是 | 操作菜单选项。 | 978| callback | AsyncCallback<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 是 | 菜单响应结果回调。 | 979 980**错误码：** 981 982以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 983 984| 错误码ID | 错误信息 | 985| -------- | ------------------------------------------------------------ | 986| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 987| 100001 | Internal error. | 988 989**示例：1** 990 991```ts 992import { promptAction } from '@kit.ArkUI'; 993import { BusinessError } from '@kit.BasicServicesKit'; 994 995try { 996 promptAction.showActionMenu({ 997 title: 'Title Info', 998 buttons: [ 999 { 1000 text: 'item1', 1001 color: '#666666' 1002 }, 1003 { 1004 text: 'item2', 1005 color: '#000000' 1006 }, 1007 ] 1008 }, (err, data) => { 1009 if (err) { 1010 console.info('showActionMenu err: ' + err); 1011 return; 1012 } 1013 console.info('showActionMenu success callback, click button: ' + data.index); 1014 }) 1015} catch (error) { 1016 let message = (error as BusinessError).message 1017 let code = (error as BusinessError).code 1018 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 1019}; 1020``` 1021 1022 1023 1024**示例：2** 1025 1026该示例为showActionMenu配置生命周期回调。 1027 1028```ts 1029import { promptAction } from '@kit.ArkUI'; 1030 1031@Entry 1032@Component 1033struct Index { 1034 @State isShown: boolean = false 1035 @State textColor: Color = Color.Black 1036 @State blueColor: Color = Color.Blue 1037 1038 @State onWillAppear: boolean = false 1039 @State onDidAppear: boolean = false 1040 @State onWillDisappear: boolean = false 1041 @State onDidDisappear: boolean = false 1042 build() { 1043 Column({ space: 50 }) { 1044 Text('onWillAppear').fontColor(this.onWillAppear ? this.blueColor : this.textColor) 1045 Text('onDidAppear').fontColor(this.onDidAppear ? this.blueColor : this.textColor) 1046 Text('onWillDisappear').fontColor(this.onWillDisappear ? this.blueColor : this.textColor) 1047 Text('onDidDisappear').fontColor(this.onDidDisappear ? this.blueColor : this.textColor) 1048 Button('click') 1049 .width(200) 1050 .height(100) 1051 .margin(100) 1052 .fontColor(this.textColor) 1053 .onClick(() => { 1054 promptAction.showActionMenu({ 1055 title: 'showActionMenu Title Info', 1056 buttons: [ 1057 { 1058 text: 'item1', 1059 color: '#666666' 1060 }, 1061 { 1062 text: 'item2', 1063 color: '#000000' 1064 }, 1065 ], 1066 onWillAppear:() => { 1067 console.info("promptAction menu cycle life onWillAppear"); 1068 this.onWillAppear = true; 1069 }, 1070 onDidAppear:() => { 1071 console.info("promptAction menu cycle life onDidAppear"); 1072 this.onDidAppear = true; 1073 }, 1074 onWillDisappear:() => { 1075 this.isShown = false; 1076 console.info("promptAction menu cycle life onWillDisappear"); 1077 this.onWillDisappear = true; 1078 }, 1079 onDidDisappear:() => { 1080 console.info("promptAction menu cycle life onDidDisappear"); 1081 this.onDidDisappear = true; 1082 } 1083 }) 1084 .then(data => { 1085 console.info('showActionMenu success, click button: ' + data.index); 1086 }) 1087 .catch((err: Error) => { 1088 console.info('showActionMenu error: ' + err); 1089 }) 1090 }) 1091 } 1092 .width('100%') 1093 } 1094} 1095``` 1096 1097 1098 1099## promptAction.showActionMenu<sup>(deprecated)</sup> 1100 1101showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse> 1102 1103创建并显示操作菜单，菜单响应后通过Promise返回结果。 1104 1105> **说明：** 1106> 1107> 从API version 18开始废弃，且直接使用showActionMenu可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[showActionMenu](arkts-apis-uicontext-promptaction.md#showactionmenu)。 1108> 1109> 从API version 10开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](arkts-apis-uicontext-promptaction.md)对象。 1110 1111**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1112 1113**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1114 1115**参数：** 1116 1117| 参数名 | 类型 | 必填 | 说明 | 1118| ------- | --------------------------------------- | ---- | -------------- | 1119| options | [ActionMenuOptions](#actionmenuoptions) | 是 | 操作菜单选项。 | 1120 1121**返回值：** 1122 1123| 类型 | 说明 | 1124| ------------------------------------------------------------ | -------------- | 1125| Promise<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | 菜单响应结果。 | 1126 1127**错误码：** 1128 1129以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 1130 1131| 错误码ID | 错误信息 | 1132| -------- | ------------------------------------------------------------ | 1133| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1134| 100001 | Internal error. | 1135 1136**示例：** 1137 1138```ts 1139import { promptAction } from '@kit.ArkUI'; 1140 1141promptAction.showActionMenu({ 1142 title: 'showActionMenu Title Info', 1143 buttons: [ 1144 { 1145 text: 'item1', 1146 color: '#666666' 1147 }, 1148 { 1149 text: 'item2', 1150 color: '#000000' 1151 }, 1152 ] 1153}) 1154 .then(data => { 1155 console.info('showActionMenu success, click button: ' + data.index); 1156 }) 1157 .catch((err: Error) => { 1158 console.info('showActionMenu error: ' + err); 1159 }) 1160``` 1161 1162 1163 1164## promptAction.openCustomDialog<sup>(deprecated)</sup> 1165 1166openCustomDialog(options: CustomDialogOptions): Promise<number> 1167 1168打开自定义弹窗。通过Promise返回结果。 1169 1170<!--Del-->不支持在ServiceExtension中使用。<!--DelEnd--> 1171 1172暂不支持isModal = true与showInSubWindow = true同时使用。如果同时设置为true时，则只生效showInSubWindow = true。 1173 1174弹窗宽度在设备竖屏时默认为 所在窗口宽度 - 左右margin（16vp，设备为2in1时为40vp），最大默认宽度为400vp。 1175 1176> **说明：** 1177> 1178> 从API version 11开始支持，从API version 18开始废弃，且直接使用openCustomDialog可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[openCustomDialog](arkts-apis-uicontext-promptaction.md#opencustomdialog12-1)。 1179> 1180> 从API version 12开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](arkts-apis-uicontext-promptaction.md)对象。 1181 1182**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1183 1184**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1185 1186**参数：** 1187 1188| 参数名 | 类型 | 必填 | 说明 | 1189| ------- | --------------------------------------------- | ---- | ------------------ | 1190| options | [CustomDialogOptions](#customdialogoptions11) | 是 | 自定义弹窗的内容。 | 1191 1192**返回值：** 1193 1194| 类型 | 说明 | 1195| --------------------- | --------------------------------------- | 1196| Promise<number> | 返回供closeCustomDialog使用的对话框id。 | 1197 1198**错误码：** 1199 1200以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 1201 1202| 错误码ID | 错误信息 | 1203| -------- | ------------------------------------------------------------ | 1204| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1205| 100001 | Internal error. | 1206 1207**示例：** 1208 1209```ts 1210import { promptAction } from '@kit.ArkUI'; 1211import { BusinessError } from '@kit.BasicServicesKit'; 1212 1213@Entry 1214@Component 1215struct Index { 1216 private customDialogComponentId: number = 0; 1217 1218 @Builder 1219 customDialogComponent() { 1220 Column() { 1221 Text('弹窗').fontSize(30) 1222 Row({ space: 50 }) { 1223 Button("确认").onClick(() => { 1224 try { 1225 promptAction.closeCustomDialog(this.customDialogComponentId) 1226 } catch (error) { 1227 let message = (error as BusinessError).message; 1228 let code = (error as BusinessError).code; 1229 console.error(`closeCustomDialog error code is ${code}, message is ${message}`); 1230 } 1231 }) 1232 Button("取消").onClick(() => { 1233 try { 1234 promptAction.closeCustomDialog(this.customDialogComponentId) 1235 } catch (error) { 1236 let message = (error as BusinessError).message; 1237 let code = (error as BusinessError).code; 1238 console.error(`closeCustomDialog error code is ${code}, message is ${message}`); 1239 } 1240 }) 1241 } 1242 }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) 1243 } 1244 1245 build() { 1246 Row() { 1247 Column({ space: 20 }) { 1248 Text('组件内弹窗') 1249 .fontSize(30) 1250 .onClick(() => { 1251 promptAction.openCustomDialog({ 1252 builder: () => { 1253 this.customDialogComponent() 1254 }, 1255 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 1256 console.info('reason' + JSON.stringify(dismissDialogAction.reason)); 1257 console.info('dialog onWillDismiss'); 1258 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 1259 dismissDialogAction.dismiss(); 1260 } 1261 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 1262 dismissDialogAction.dismiss(); 1263 } 1264 } 1265 }).then((dialogId: number) => { 1266 this.customDialogComponentId = dialogId; 1267 }) 1268 .catch((error: BusinessError) => { 1269 console.error(`openCustomDialog error code is ${error.code}, message is ${error.message}`); 1270 }) 1271 }) 1272 } 1273 .width('100%') 1274 } 1275 .height('100%') 1276 } 1277} 1278 1279``` 1280 1281该示例定义了弹窗样式，如宽度、高度、背景色、阴影等。 1282 1283> **说明：** 1284> 1285> 直接使用openCustomDialog可能导致实例不明确的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[openCustomDialog](arkts-apis-uicontext-promptaction.md#opencustomdialog12-1)。 1286 1287```ts 1288import { LevelMode, ImmersiveMode } from '@kit.ArkUI'; 1289 1290let customDialogId: number = 0; 1291 1292@Builder 1293function customDialogBuilder(uiContext: UIContext) { 1294 Column() { 1295 Text('Custom dialog Message').fontSize(10) 1296 Row() { 1297 Button("确认").onClick(() => { 1298 uiContext.getPromptAction().closeCustomDialog(customDialogId); 1299 }) 1300 Blank().width(50) 1301 Button("取消").onClick(() => { 1302 uiContext.getPromptAction().closeCustomDialog(customDialogId); 1303 }) 1304 } 1305 } 1306} 1307 1308@Entry 1309@Component 1310struct Index { 1311 @State message: string = 'Hello World'; 1312 private uiContext: UIContext = this.getUIContext(); 1313 1314 @Builder 1315 customDialogComponent() { 1316 customDialogBuilder(this.uiContext) 1317 } 1318 1319 build() { 1320 Row() { 1321 Column() { 1322 Text(this.message).id("test_text") 1323 .fontSize(50) 1324 .fontWeight(FontWeight.Bold) 1325 .onClick(() => { 1326 const node: FrameNode | null = this.uiContext.getFrameNodeById("test_text") || null; 1327 this.uiContext.getPromptAction().openCustomDialog({ 1328 builder: () => { 1329 this.customDialogComponent() 1330 }, 1331 keyboardAvoidMode: KeyboardAvoidMode.NONE, 1332 showInSubWindow: false, 1333 offset: { dx: 5, dy: 5 }, 1334 backgroundColor: 0xd9ffffff, 1335 cornerRadius: 20, 1336 width: '80%', 1337 height: 200, 1338 borderWidth: 1, 1339 borderStyle: BorderStyle.Dashed, // 使用borderStyle属性，需要和borderWidth属性一起使用 1340 borderColor: Color.Blue, // 使用borderColor属性，需要和borderWidth属性一起使用 1341 shadow: ({ 1342 radius: 20, 1343 color: Color.Grey, 1344 offsetX: 50, 1345 offsetY: 0 1346 }), 1347 levelMode: LevelMode.EMBEDDED, 1348 levelUniqueId: node?.getUniqueId(), 1349 immersiveMode: ImmersiveMode.DEFAULT, 1350 }).then((dialogId: number) => { 1351 customDialogId = dialogId; 1352 }) 1353 }) 1354 } 1355 .width('100%') 1356 } 1357 .height('100%') 1358 } 1359} 1360``` 1361 1362 1363 1364该示例实现了一个页面内的弹窗。 1365 1366> **说明：** 1367> 1368> 直接使用openCustomDialog可能导致实例不明确的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[openCustomDialog](arkts-apis-uicontext-promptaction.md#opencustomdialog12-1)。 1369 1370```ts 1371// Index.ets 1372import { LevelMode, ImmersiveMode } from '@kit.ArkUI'; 1373 1374let customDialogId: number = 0; 1375 1376@Builder 1377function customDialogBuilder(uiContext: UIContext) { 1378 Column() { 1379 Text('Custom dialog Message').fontSize(10).height(100) 1380 Row() { 1381 Button("Next").onClick(() => { 1382 uiContext.getRouter().pushUrl({ url: 'pages/Next' }); 1383 }) 1384 Blank().width(50) 1385 Button("Close").onClick(() => { 1386 uiContext.getPromptAction().closeCustomDialog(customDialogId); 1387 }) 1388 } 1389 }.padding(20) 1390} 1391 1392@Entry 1393@Component 1394struct Index { 1395 @State message: string = 'Hello World'; 1396 private uiContext: UIContext = this.getUIContext(); 1397 1398 @Builder 1399 customDialogComponent() { 1400 customDialogBuilder(this.uiContext) 1401 } 1402 1403 build() { 1404 Row() { 1405 Column() { 1406 Text(this.message).id("test_text") 1407 .fontSize(50) 1408 .fontWeight(FontWeight.Bold) 1409 .onClick(() => { 1410 const node: FrameNode | null = this.uiContext.getFrameNodeById("test_text") || null; 1411 this.uiContext.getPromptAction().openCustomDialog({ 1412 builder: () => { 1413 this.customDialogComponent() 1414 }, 1415 levelMode: LevelMode.EMBEDDED, 1416 levelUniqueId: node?.getUniqueId(), 1417 immersiveMode: ImmersiveMode.DEFAULT, 1418 }).then((dialogId: number) => { 1419 customDialogId = dialogId; 1420 }) 1421 }) 1422 } 1423 .width('100%') 1424 } 1425 .height('100%') 1426 } 1427} 1428``` 1429 1430```ts 1431// Next.ets 1432@Entry 1433@Component 1434struct Next { 1435 @State message: string = 'Back'; 1436 1437 build() { 1438 Row() { 1439 Column() { 1440 Button(this.message) 1441 .onClick(() => { 1442 this.getUIContext().getRouter().back(); 1443 }) 1444 } 1445 .width('100%') 1446 } 1447 .height('100%') 1448 } 1449} 1450``` 1451 1452 1453 1454## promptAction.closeCustomDialog<sup>(deprecated)</sup> 1455 1456closeCustomDialog(dialogId: number): void 1457 1458关闭自定义弹窗。 1459 1460> **说明：** 1461> 1462> 从API version 11开始支持，从API version 18开始废弃，且直接使用closeCustomDialog可能导致[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的问题，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)获取[PromptAction](arkts-apis-uicontext-promptaction.md)对象，再通过此对象调用替代方法[closeCustomDialog](arkts-apis-uicontext-promptaction.md#closecustomdialog12-1)。 1463> 1464> 从API version 12开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getPromptAction](arkts-apis-uicontext-uicontext.md#getpromptaction)方法获取当前UI上下文关联的[PromptAction](arkts-apis-uicontext-promptaction.md)对象。 1465 1466**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1467 1468**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1469 1470**参数：** 1471 1472| 参数名 | 类型 | 必填 | 说明 | 1473| -------- | ------ | ---- | -------------------------------- | 1474| dialogId | number | 是 | openCustomDialog返回的对话框id。 | 1475 1476**错误码：** 1477 1478以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.promptAction(弹窗)](errorcode-promptAction.md)错误码。 1479 1480| 错误码ID | 错误信息 | 1481| -------- | ------------------------------------------------------------ | 1482| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1483| 100001 | Internal error. | 1484 1485**示例：** 1486 1487示例请看[promptAction.openCustomDialog](#promptactionopencustomdialogdeprecated)的示例。
