1# @ohos.promptAction (Prompt) 2 3The **PromptAction** module provides APIs for creating and showing toasts, dialog boxes, and action menus. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> This module cannot be used in the file declaration of the [UIAbility](../apis-ability-kit/js-apis-app-ability-uiAbility.md). In other words, the APIs of this module can be used only after a component instance is created; they cannot be called in the lifecycle of the UIAbility. 10> 11> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where [the UI context is ambiguous](../../ui/arkts-global-interface.md#ambiguous-ui-context). For details, see [UIContext](js-apis-arkui-UIContext.md#uicontext). It is recommended that you use the dialog box APIs provided by **UIContext**<!--Del-->, except for UI-less scenarios such as [ServiceExtension](../../application-models/serviceextensionability.md)<!--DelEnd-->. 12 13## Modules to Import 14 15```ts 16import { promptAction } from '@kit.ArkUI'; 17``` 18 19## promptAction.openToast<sup>18+</sup> 20 21openToast(options: ShowToastOptions): Promise<number> 22 23Shows a toast. This API uses a promise to return the toast ID. 24 25**Atomic service API**: This API can be used in atomic services since API version 18. 26 27**System capability**: SystemCapability.ArkUI.ArkUI.Full 28 29**Parameters** 30 31| Name | Type | Mandatory| Description | 32| ------- | ------------------------------------------------------------ | ---- | -------------- | 33| options | [ShowToastOptions](#showtoastoptions) | Yes | Toast options.| 34 35**Return value** 36 37| Type | Description | 38| ---------------- | ------------------------------------ | 39| Promise<number> | ID of the toast, which is required in **closeToast**.| 40 41**Error codes** 42 43For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 44 45| ID| Error Message | 46| -------- | ------------------------------------------------------------ | 47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 48| 100001 | Internal error. | 49 50**Example** 51 52> **NOTE** 53> 54> Directly using **openToast** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the **PromptAction** object using the **getPromptAction** API in **UIContext** and then call the [openToast](js-apis-arkui-UIContext.md#opentoast18) API through this object. 55 56```ts 57import { BusinessError } from '@kit.BasicServicesKit'; 58import { PromptAction, UIContext } from "@ohos.arkui.UIContext"; 59 60@Entry 61@Component 62struct toastExample { 63 @State toastId: number = 0; 64 uiContext: UIContext = this.getUIContext(); 65 promptAction: PromptAction = this.uiContext.getPromptAction(); 66 67 build() { 68 Column() { 69 Button('Open Toast') 70 .height(100) 71 .type(ButtonType.Capsule) 72 .onClick(() => { 73 this.promptAction.openToast({ 74 message: 'Toast Message', 75 duration: 10000, 76 }).then((toastId: number) => { 77 this.toastId = toastId; 78 }) 79 .catch((error: BusinessError) => { 80 console.error(`openToast error code is ${error.code}, message is ${error.message}`); 81 }) 82 }) 83 Blank().height(50) 84 Button('Close Toast') 85 .height(100) 86 .type(ButtonType.Capsule) 87 .onClick(() => { 88 try { 89 this.promptAction.closeToast(this.toastId); 90 } catch (error) { 91 let message = (error as BusinessError).message; 92 let code = (error as BusinessError).code; 93 console.error(`CloseToast error code is ${code}, message is ${message}`); 94 } 95 }) 96 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 97 } 98} 99``` 100 101 102 103## promptAction.closeToast<sup>18+</sup> 104 105closeToast(toastId: number): void 106 107Closes a toast. 108 109**Atomic service API**: This API can be used in atomic services since API version 18. 110 111**System capability**: SystemCapability.ArkUI.ArkUI.Full 112 113**Parameters** 114 115| Name | Type | Mandatory| Description | 116| ------- | ------ | ---- | ----------------------------- | 117| toastId | number | Yes | ID of the toast to close, which is returned by **openToast**.| 118 119**Error codes** 120 121For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 122 123| ID| Error Message | 124| -------- | ------------------------------------------------------------ | 125| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 126| 100001 | Internal error. | 127| 103401 | Cannot find the toast. | 128 129**Example** 130 131> **NOTE** 132> 133> Directly using **closeToast** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the **PromptAction** object using the **getPromptAction** API in **UIContext** and then call the [openToast](js-apis-arkui-UIContext.md#closetoast18) API through this object. 134 135See the example for [promptAction.openToaset18](#promptactionopentoast18). 136 137## ShowToastOptions 138 139Describes the options for showing the toast. 140 141**System capability**: SystemCapability.ArkUI.ArkUI.Full 142 143| Name | Type | Mandatory| Description | 144| ----------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 145| message | string \| [Resource](arkui-ts/ts-types.md#resource) | Yes | Text to display.<br>**NOTE**<br>The default font is **'Harmony Sans'**. Other fonts are not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 146| duration | number | No | Duration that the toast will remain on the screen.<br>The default value is 1500 ms. The value range is 1500 ms to 10000 ms. If a value less than 1500 ms is set, the default value is used. If the value greater than 10000 ms is set, the upper limit 10000 ms is used.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 147| bottom | string \| number | No | Distance from the bottom of the toast to the navigation bar. In **ToastShowMode.TOP_MOST** mode, if the soft keyboard is raised and the **bottom** value is too small, the toast will automatically avoid being blocked by the soft keyboard by moving up 80 vp above it. In **ToastShowMode.DEFAULT** mode, the toast will move up by the height of the soft keyboard.<br>Default value: **80vp**<br>**NOTE**<br>When there is no navigation bar at the bottom, **bottom** sets the distance from the bottom of the toast to the bottom of the window.<br>If the **alignment** property is set, **bottom** will not take effect.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 148| showMode<sup>11+</sup> | [ToastShowMode](#toastshowmode11) | No | Display mode of the toast.<br>Default value: **ToastShowMode.DEFAULT**, which means to show the toast in the application.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 149| alignment<sup>12+</sup> | [Alignment](arkui-ts/ts-appendix-enums.md#alignment) | No | Alignment mode.<br>**NOTE**<br>The figure below shows the position of the toast in different alignment modes.<br><br>The text display of the toast is always left-aligned; other alignment modes are not supported.<br>Default value: **undefined**, indicating bottom start<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 150| offset<sup>12+</sup> | [Offset](arkui-ts/ts-types.md#offset) | No | Offset in the specified alignment mode.<br>Default value: **{ dx: 0, dy: 0 }**, indicating no offset<br>**NOTE**<br>Only values in units of px are supported. Values in other units (for example, vp) must be converted to units of px before being passed in.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 151| backgroundColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No | Background color of the toast.<br>Default value: **Color.Transparent**<br>**NOTE**<br>The background color will be visually combined with the blur effect when both properties are set. If the resulting effect does not match your design requirements, you can disable the blur effect entirely by explicitly setting the **backgroundBlurStyle** property to **BlurStyle.NONE**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 152| textColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No | Font color of the toast.<br>Default value: **Color.Black**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 153| backgroundBlurStyle<sup>12+</sup> | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | No | Background blur style of the toast.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**NOTE**<br>Setting this parameter to **BlurStyle.NONE** disables the background blur. When **backgroundBlurStyle** is set to a value other than **NONE**, do not set **backgroundColor**. If you do, the color display may not produce the expected visual effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 154| shadow<sup>12+</sup> | [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10) | No | Background shadow of the toast.<br>Default value: **ShadowStyle.OUTER_DEFAULT_MD**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 155| enableHoverMode<sup>14+</sup> | boolean | No | Whether to respond when the device is in semi-folded mode. The value **true** means to respond when the device is in semi-folded mode.<br>Default value: **false**, meaning not to respond when the device is in semi-folded mode.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 156| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](arkui-ts/ts-appendix-enums.md#hovermodeareatype14) | No | Display area of the toast in the hover state.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**, indicating that the toast is displayed in the lower half screen<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 157 158## ToastShowMode<sup>11+</sup> 159 160Enumerates display modes for toasts. By default, the toast is displayed within the application and supports display in sub-windows. 161 162**Atomic service API**: This API can be used in atomic services since API version 12. 163 164**System capability**: SystemCapability.ArkUI.ArkUI.Full 165 166| Name | Value | Description | 167| -------- | ---- | ---------------------- | 168| DEFAULT | 0 | The toast is displayed within the application. | 169| TOP_MOST | 1 | The toast is displayed in a subwindow.| 170 171## ShowDialogOptions 172 173Describes the options for showing the dialog box. 174 175**System capability**: SystemCapability.ArkUI.ArkUI.Full 176 177| Name | Type | Mandatory| Description | 178| --------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 179| title | string \| [Resource](arkui-ts/ts-types.md#resource) | No | Title of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 180| message | string \| [Resource](arkui-ts/ts-types.md#resource) | No | Text body.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 181| buttons | Array<[Button](#button)> | No | Array of buttons in the dialog box. The array structure is {text:'button', color: '\#666666'}. More than one button is supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 182| alignment<sup>10+</sup> | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**<br>**NOTE**<br>If **showInSubWindow** is set to **true** in **UIExtension**, the dialog box is aligned with the host window based on **UIExtension**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 183| offset<sup>10+</sup> | [Offset](arkui-ts/ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.<br>Default value: **{ dx: 0 , dy: 0 }**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 184| maskRect<sup>10+</sup> | [Rectangle](arkui-ts/ts-methods-alert-dialog-box.md#rectangle8) | No | Mask area of the dialog box. Events within the mask area are blocked, while events outside the mask area are transmitted.<br>Default value: **{ x: 0, y: 0, width: '100%', height: '100%' }**<br>**NOTE**<br>**maskRect** does not take effect when **showInSubWindow** is set to **true**.<br>If only partial properties are set, the unspecified properties default to **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 185| showInSubWindow<sup>11+</sup> | boolean | No | Whether to show the dialog box in a subwindow when the dialog box needs to be displayed outside the main window. <br>**true**: The dialog box is shown in a subwindow.<br>**false** (default): The dialog box is displayed within the application, not in a separate subwindow.<br>**NOTE**<br>A dialog box whose **showInSubWindow** attribute is **true** cannot trigger the display of another dialog box whose **showInSubWindow** attribute is also **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 186| isModal<sup>11+</sup> | boolean | No | Whether the dialog box is a modal, which has a mask applied and does not allow for interaction with other components around the dialog box. <br>**true**: The dialog box is a modal. <br>**false**: The dialog box is not a modal.<br>Default value: **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 187| backgroundColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No | Background color of the dialog box.<br>Default value: **Color.Transparent**.<br>**NOTE**<br>The background color will be visually combined with the blur effect when both properties are set. If the resulting effect does not match your design requirements, you can disable the blur effect entirely by explicitly setting the **backgroundBlurStyle** property to **BlurStyle.NONE**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 188| backgroundBlurStyle<sup>12+</sup> | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | No | Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**NOTE**<br>Setting this parameter to **BlurStyle.NONE** disables the background blur. When **backgroundBlurStyle** is set to a value other than **NONE**, do not set **backgroundColor**. If you do, the color display may not produce the expected visual effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 189| backgroundBlurStyleOptions<sup>19+</sup> | [BackgroundBlurStyleOptions](arkui-ts/ts-universal-attributes-background.md#backgroundblurstyleoptions10) | No| Options for customizing the background blur style. For details about the default value, see **BackgroundBlurStyleOptions**.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 190| backgroundEffect<sup>19+</sup> | [BackgroundEffectOptions](arkui-ts/ts-universal-attributes-background.md#backgroundeffectoptions11) | No| Options for customizing the background effect. For details about the default value, see **BackgroundEffectOptions**.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 191| shadow<sup>12+</sup> | [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10) | No | Shadow of the dialog box.<br> Default value on 2-in-1 devices: **ShadowStyle.OUTER_FLOATING_MD** when the dialog box is focused and **ShadowStyle.OUTER_FLOATING_SM** otherwise On other devices, the dialog box has no shadow by default.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 192| enableHoverMode<sup>14+</sup> | boolean | No | Whether to respond when the device is in semi-folded mode. The value **true** means to respond when the device is in semi-folded mode.<br>Default value: **false**, meaning not to respond when the device is in semi-folded mode.<br>**Atomic service API**: This API can be used in atomic services since API version 14. | 193| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](arkui-ts/ts-appendix-enums.md#hovermodeareatype14) | No | Default display area of the dialog box in semi-folded mode.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 194| onWillAppear<sup>19+</sup> | Callback<void> | No| Callback invoked before the dialog box appearance animation.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onWillAppear**. The settings take effect next time the dialog box appears.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 195| onDidAppear<sup>19+</sup> | Callback<void> | No| Callback invoked when the dialog box appears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onDidAppear**. The settings take effect next time the dialog box appears.<br>3. When a dialog box is dismissed immediately after being shown, **onWillDisappear** may be triggered before **onDidAppear**.<br>4. If the dialog box is dismissed before its appearance animation is finished, the animation will be interrupted, and **onDidAppear** will not be invoked.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 196| onWillDisappear<sup>19+</sup> | Callback<void> | No| Callback invoked before the dialog box disappearance animation.<br>**NOTE**<br>The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br> **Atomic service API**: This API can be used in atomic services since API version 19.| 197| onDidDisappear<sup>19+</sup> | Callback<void> | No| Callback invoked when the dialog box disappears.<br>**NOTE**<br>The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 198| levelMode<sup>15+</sup> | [LevelMode](#levelmode15) | No | Display level of the dialog box.<br>**NOTE**<br>- Default value: **LevelMode.OVERLAY**<br>- This parameter takes effect only when **showInSubWindow** is set to **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 199| levelUniqueId<sup>15+</sup> | number | No | [Unique ID](js-apis-arkui-frameNode.md#getuniqueid12) of the node under the display level for the page-level dialog box.<br>Value range: a number no less than 0<br>**NOTE**<br>- This parameter takes effect only when **levelMode** is set to **LevelMode.EMBEDDED**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 200| immersiveMode<sup>15+</sup> | [ImmersiveMode](#immersivemode15) | No | Mask effect for the page-level dialog box.<br>**NOTE**<br>- Default value: **ImmersiveMode.DEFAULT**<br>- This parameter takes effect only when **levelMode** is set to **LevelMode.EMBEDDED**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 201| levelOrder<sup>18+</sup> | [LevelOrder](#levelorder18) | No | Display order of the dialog box.<br>**NOTE**<br>- Default value: **LevelOrder.clamp(0)**<br>- Dynamic updating is not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 202 203## ShowDialogSuccessResponse 204 205Describes the dialog box response result. 206 207**Atomic service API**: This API can be used in atomic services since API version 11. 208 209**System capability**: SystemCapability.ArkUI.ArkUI.Full 210 211| Name | Type | Mandatory| Description | 212| ----- | ------ | ---- | ------------------------------- | 213| index | number | Yes | Index of the selected button in the **buttons** array.| 214 215## ActionMenuOptions 216 217Describes the options for showing the action menu. 218 219**System capability**: SystemCapability.ArkUI.ArkUI.Full 220 221| Name | Type | Mandatory| Description | 222| ----------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 223| title | string \| [Resource](arkui-ts/ts-types.md#resource) | No | Title of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 224| buttons | [[Button](#button),[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?,[Button](#button)?] | Yes | Array of menu item buttons. The array structure is **{text:'button', color: '\#666666'}**. Up to six buttons are supported. If there are more than six buttons, only the first six buttons will be displayed.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 225| showInSubWindow<sup>11+</sup> | boolean | No | Whether to show the menu in a subwindow when the menu needs to be displayed outside the main window. <br>**true**: The menu is shown in a subwindow.<br>Default value: **false**, indicating that the dialog box is not displayed in a subwindow.<br>**NOTE**<br> - A menu whose **showInSubWindow** attribute is **true** cannot trigger the display of another menu whose **showInSubWindow** attribute is also **true**.<br> - If **showInSubWindow** is set to **true** in **UIExtension**, the menu is aligned with the host window based on **UIExtension**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 226| isModal<sup>11+</sup> | boolean | No | Whether the menu is a modal, which has a mask applied and does not allow for interaction with other components around the menu. <br>**true**: The menu is a modal. <br>**false**: The menu is not a modal.<br>Default value: **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 227| levelMode<sup>15+</sup> | [LevelMode](#levelmode15) | No | Display level modes of the menu.<br>**NOTE**<br>- Default value: **LevelMode.OVERLAY**<br>- This parameter takes effect only when **showInSubWindow** is set to **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 228| levelUniqueId<sup>15+</sup> | number | No | [Unique ID](js-apis-arkui-frameNode.md#getuniqueid12) of the node under the display level for the page-level menu.<br>Value range: a number no less than 0<br>**NOTE**<br>- This parameter takes effect only when **levelMode** is set to **LevelMode.EMBEDDED**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 229| immersiveMode<sup>15+</sup> | [ImmersiveMode](#immersivemode15) | No | Mask effect for the page-level menu.<br>**NOTE**<br>- Default value: **ImmersiveMode.DEFAULT**<br>- This parameter takes effect only when **levelMode** is set to **LevelMode.EMBEDDED**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 230| onWillAppear<sup>20+</sup> | Callback<void> | No| Callback invoked before the menu appearance animation.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 231| onDidAppear<sup>20+</sup> | Callback<void> | No| Callback invoked when the menu appears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br>2. When a menu is dismissed immediately after being shown, **onWillDisappear** may be triggered before **onDidAppear**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 232| onWillDisappear<sup>20+</sup> | Callback<void> | No| Callback invoked before the menu disappearance animation.<br>**NOTE**<br>The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br> **Atomic service API**: This API can be used in atomic services since API version 20.| 233| onDidDisappear<sup>20+</sup> | Callback<void> | No| Callback invoked when the menu disappears.<br>**NOTE**<br>The normal timing sequence is as follows: onWillAppear > onDidAppear > onWillDisappear > onDidDisappear.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 234 235## ActionMenuSuccessResponse 236 237Describes the action menu response result. 238 239**Atomic service API**: This API can be used in atomic services since API version 11. 240 241**System capability**: SystemCapability.ArkUI.ArkUI.Full 242 243| Name | Type | Mandatory| Description | 244| ----- | ------ | ---- | ---------------------------------------- | 245| index | number | Yes | Index of the selected button in the **buttons** array, starting from **0**.| 246 247## CommonState<sup>20+</sup> 248 249Enumerates states of the custom dialog box. 250 251**Atomic service API**: This API can be used in atomic services since API version 20. 252 253**System capability**: SystemCapability.ArkUI.ArkUI.Full 254 255| Name | Value | Description | 256| ------------- | ---- | ------------------------------------------ | 257| UNINITIALIZED | 0 | State before the controller is bound to the dialog box. | 258| INITIALIZED | 1 | State after the controller is bound to the dialog box. | 259| APPEARING | 2 | State during the dialog box appearance animation. | 260| APPEARED | 3 | State after the dialog display appearance ends. | 261| DISAPPEARING | 4 | State during the dialog box disappearance animation. | 262| DISAPPEARED | 5 | State after the dialog box disappearance animation ends. | 263 264## DialogController<sup>18+</sup> 265 266Implements a custom dialog controller that inherits from [CommonController](#commoncontroller18). 267 268It can be used as a member variable of **UIContext** to display custom dialog boxes. For specific usage, see the examples for [openCustomDialogWithController](js-apis-arkui-UIContext.md#opencustomdialogwithcontroller18) and [presentCustomDialog](js-apis-arkui-UIContext.md#presentcustomdialog18). 269 270**Atomic service API**: This API can be used in atomic services since API version 18. 271 272**System capability**: SystemCapability.ArkUI.ArkUI.Full 273 274## CommonController<sup>18+</sup> 275 276Implements a common controller for managing components related to **promptAction**. 277 278**Atomic service API**: This API can be used in atomic services since API version 18. 279 280**System capability**: SystemCapability.ArkUI.ArkUI.Full 281 282### constructor<sup>18+</sup> 283constructor() 284 285A constructor used to create a controller instance. 286 287**Atomic service API**: This API can be used in atomic services since API version 18. 288 289**System capability**: SystemCapability.ArkUI.ArkUI.Full 290 291### close<sup>18+</sup> 292close(): void 293 294Closes the custom dialog box. If the dialog box is already closed, this API has no effect. 295 296**Atomic service API**: This API can be used in atomic services since API version 18. 297 298**System capability**: SystemCapability.ArkUI.ArkUI.Full 299 300### getState<sup>20+</sup> 301 302getState(): CommonState 303 304Obtains the state of the custom dialog box. 305 306**Atomic service API**: This API can be used in atomic services since API version 20. 307 308**System capability**: SystemCapability.ArkUI.ArkUI.Full 309 310**Return value** 311 312| Type | Description | 313| ------------------------------------------------- | ------------------ | 314| [CommonState](#commonstate20) | State of the custom dialog box.| 315 316## LevelOrder<sup>18+</sup> 317 318Defines the display order of a dialog box. 319 320**Atomic service API**: This API can be used in atomic services since API version 18. 321 322**System capability**: SystemCapability.ArkUI.ArkUI.Full 323 324### clamp<sup>18+</sup> 325static clamp(order: number): LevelOrder 326 327Creates a dialog box level with the specified order. 328 329**Atomic service API**: This API can be used in atomic services since API version 18. 330 331**System capability**: SystemCapability.ArkUI.ArkUI.Full 332 333**Parameters** 334 335| Name| Type | Mandatory| Description | 336| ------ | ------- | ---- | ------------------------------------------------------------ | 337| order | number | Yes | Display order of the dialog box. The value range is [-100000.0, +100000.0]. Values outside this range are clamped to the nearest limit.| 338 339**Return value** 340 341| Type | Description | 342| ------ | ------ | 343| [LevelOrder](#levelorder18) | Current instance.| 344 345### getOrder<sup>18+</sup> 346getOrder(): number 347 348Obtains the display order of this dialog box. 349 350**Atomic service API**: This API can be used in atomic services since API version 18. 351 352**System capability**: SystemCapability.ArkUI.ArkUI.Full 353 354**Return value** 355 356| Type | Description | 357| ------ | ------ | 358| number | Display order of the dialog box.| 359 360## DialogOptions<sup>18+</sup> 361 362Extends [BaseDialogOptions](#basedialogoptions11) to provide enhanced customization capabilities for the dialog box. 363 364**Atomic service API**: This API can be used in atomic services since API version 18. 365 366**System capability**: SystemCapability.ArkUI.ArkUI.Full 367 368| Name | Type | Mandatory| Description | 369| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 370| backgroundColor | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No| Background color of the dialog box.<br>Default value: **Color.Transparent**.<br>**NOTE**<br>The background color will be visually combined with the blur effect when both properties are set. If the resulting effect does not match your design requirements, you can disable the blur effect entirely by explicitly setting the **backgroundBlurStyle** property to **BlurStyle.NONE**.| 371| cornerRadius | [DialogOptionsCornerRadius](#dialogoptionscornerradius18) | No| Background corner radius of the dialog box.<br>You can set separate radiuses for the four rounded corners.<br>Default value: **{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }**<br> The radius of the rounded corners is subject to the component size. Its maximum value is half of the component width or height. If the value is negative, the default value is used.<br> When set to a percentage, the value defines the radius as a percentage of the parent component's width or height.| 372| borderWidth | [DialogOptionsBorderWidth](#dialogoptionsborderwidth18) | No| Border width of the dialog box.<br>You can set the width for all four sides or set separate widths for individual sides.<br>Default value: **0**.<br>Unit: vp.<br> When set to a percentage, the value defines the border width as a percentage of the parent dialog box's width.<br>If the left and right borders are greater than its width, or the top and bottom borders are greater than its height, the dialog box may not display as expected.| 373| borderColor | [DialogOptionsBorderColor](#dialogoptionsbordercolor18) | No| Border color of the dialog box.<br>Default value: **Color.Black**<br> **borderColor** must be used with **borderWidth** in pairs.| 374| borderStyle | [DialogOptionsBorderStyle](#dialogoptionsborderstyle18) | No| Border style of the dialog box.<br>Default value: **BorderStyle.Solid**.<br> **borderStyle** must be used with **borderWidth** in pairs.| 375| width | [Dimension](arkui-ts/ts-types.md#dimension10) | No | Width of the dialog box.<br>**NOTE**<br>- Default maximum value: 400vp<br>- Percentage-based configuration: The reference width of the dialog box is adjusted based on the width of the window where the dialog box is located.| 376| height | [Dimension](arkui-ts/ts-types.md#dimension10) | No | Height of the dialog box.<br>**NOTE**<br>- Default maximum value: 0.9 x (Window height – Safe area)<br>- When this parameter is set to a percentage, the reference height of the dialog box is the height of the window where the dialog box is located minus the safe area. You can decrease or increase the height as needed.| 377| shadow | [DialogOptionsShadow](#dialogoptionsshadow18) | No| Shadow of the dialog box.<br>Default value on 2-in-1 devices: **ShadowStyle.OUTER_FLOATING_MD** when the dialog box is focused and **ShadowStyle.OUTER_FLOATING_SM** otherwise On other devices, the dialog box has no shadow by default.| 378| backgroundBlurStyle | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | No | Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**NOTE**<br>Setting this parameter to **BlurStyle.NONE** disables the background blur. When **backgroundBlurStyle** is set to a value other than **NONE**, do not set **backgroundColor**. If you do, the color display may not produce the expected visual effect.| 379 380## DialogOptionsCornerRadius<sup>18+</sup> 381 382type DialogOptionsCornerRadius = Dimension \| BorderRadiuses 383 384Defines the allowed data types for specifying the background corner radius of a dialog box. 385 386**Atomic service API**: This API can be used in atomic services since API version 18. 387 388**System capability**: SystemCapability.ArkUI.ArkUI.Full 389 390| Type | Description | 391| ------------------------------------------------------------ | ---------------------------- | 392| [Dimension](arkui-ts/ts-types.md#dimension10) | Length type used to represent a size unit.| 393| [BorderRadiuses](arkui-ts/ts-types.md#borderradiuses9) | Type used to describe the corner radius of a component's border.| 394 395## DialogOptionsBorderWidth<sup>18+</sup> 396 397type DialogOptionsBorderWidth = Dimension \| EdgeWidths 398 399Defines the allowed data types for specifying the background border width of a dialog box. 400 401**Atomic service API**: This API can be used in atomic services since API version 18. 402 403**System capability**: SystemCapability.ArkUI.ArkUI.Full 404 405| Type | Description | 406| ------------------------------------------------------------ | ---------------------------- | 407| [Dimension](arkui-ts/ts-types.md#dimension10) | Length type used to represent a size unit.| 408| [EdgeWidths](arkui-ts/ts-types.md#edgewidths9) | Type used to describe the edge width of a component in different directions.| 409 410## DialogOptionsBorderColor<sup>18+</sup> 411 412type DialogOptionsBorderColor = ResourceColor \| EdgeColors 413 414Defines the allowed data types for specifying the background border color of a dialog box. 415 416**Atomic service API**: This API can be used in atomic services since API version 18. 417 418**System capability**: SystemCapability.ArkUI.ArkUI.Full 419 420| Type | Description | 421| ------------------------------------------------------------ | ---------------------------- | 422| [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | Color type used to describe resource colors.| 423| [EdgeColors](arkui-ts/ts-types.md#edgecolors9) | Type used to describe the border color for each edge of a component.| 424 425## DialogOptionsBorderStyle<sup>18+</sup> 426 427type DialogOptionsBorderStyle = BorderStyle \| EdgeStyles 428 429Defines the allowed data types for specifying the background border style of a dialog box. 430 431**Atomic service API**: This API can be used in atomic services since API version 18. 432 433**System capability**: SystemCapability.ArkUI.ArkUI.Full 434 435| Type | Description | 436| ------------------------------------------------------------ | ---------------------------- | 437| [BorderStyle](arkui-ts/ts-appendix-enums.md#borderstyle) | Type used to describe the border style of a component.| 438| [EdgeStyles](arkui-ts/ts-types.md#edgestyles9) | Type used to describe the border style for each edge of a component.| 439 440## DialogOptionsShadow<sup>18+</sup> 441 442type DialogOptionsShadow = ShadowOptions \| ShadowStyle 443 444Defines the allowed data types for specifying the background shadow of a dialog box. 445 446**Atomic service API**: This API can be used in atomic services since API version 18. 447 448**System capability**: SystemCapability.ArkUI.ArkUI.Full 449 450| Type | Description | 451| ------------------------------------------------------------ | ---------------------------- | 452| [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions) | Type used to describe shadow attributes, including the blur radius, color, and offset along the x-axis and y-axis.| 453| [ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10) | Type used to describe the shadow style.| 454 455## CustomDialogOptions<sup>11+</sup> 456 457Extends [BaseDialogOptions](#basedialogoptions11) to provide enhanced customization capabilities for the dialog box. 458 459**Atomic service API**: This API can be used in atomic services since API version 12. 460 461**System capability**: SystemCapability.ArkUI.ArkUI.Full 462 463| Name | Type | Mandatory| Description | 464| ------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 465| builder | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) | Yes | Custom content of the dialog box.<br>**NOTE**<br>The builder needs to be assigned an arrow function in the following format: () => { this.XXX() }, where XXX indicates the internal builder name.<br>Global builders must be created inside the component and called within the internal builder.<br>The width and height percentages of the builder's root node are relative to the size of the dialog box container.<br>The width and height percentages of non-root nodes are relative to the size of their parent node.| 466| backgroundColor <sup>12+</sup>| [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No| Background color of the dialog box.<br>Default value: **Color.Transparent**.<br>**NOTE**<br>When **backgroundColor** is set to a non-transparent color, **backgroundBlurStyle** must be set to **BlurStyle.NONE**; otherwise, the color display may not meet the expected effect.| 467| cornerRadius<sup>12+</sup>| [Dimension](arkui-ts/ts-types.md#dimension10) \| [BorderRadiuses](arkui-ts/ts-types.md#borderradiuses9) | No| Corner radius of the background.<br>You can set separate radiuses for the four corners.<br>Default value: **{ topLeft: '32vp', topRight: '32vp', bottomLeft: '32vp', bottomRight: '32vp' }**<br> The radius of the rounded corners is subject to the component size. Its maximum value is half of the component width or height. If the value is negative, the default value is used.<br> When set to a percentage, the value defines the radius as a percentage of the parent component's width or height.| 468| borderWidth<sup>12+</sup>| [Dimension](arkui-ts/ts-types.md#dimension10) \| [EdgeWidths](arkui-ts/ts-types.md#edgewidths9) | No| Border width of the dialog box.<br>You can set the width for all four sides or set separate widths for individual sides.<br>Default value: **0**.<br>Unit: vp.<br> When set to a percentage, the value defines the border width as a percentage of the parent dialog box's width.<br>If the left and right borders are greater than its width, or the top and bottom borders are greater than its height, the dialog box may not display as expected.| 469| borderColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) \| [EdgeColors](arkui-ts/ts-types.md#edgecolors9) | No| Border color of the dialog box.<br>Default value: **Color.Black**.<br> **borderColor** must be used with **borderWidth** in pairs.| 470| borderStyle<sup>12+</sup> | [BorderStyle](arkui-ts/ts-appendix-enums.md#borderstyle) \| [EdgeStyles](arkui-ts/ts-types.md#edgestyles9) | No| Border style of the dialog box.<br>Default value: **BorderStyle.Solid**.<br> **borderStyle** must be used with **borderWidth** in pairs.| 471| width<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10) | No | Width of the dialog box.<br>**NOTE**<br>- Default maximum width of the dialog box: 400 vp<br>- Percentage-based configuration: The reference width of the dialog box is adjusted based on the width of the window where the dialog box is located.| 472| height<sup>12+</sup> | [Dimension](arkui-ts/ts-types.md#dimension10) | No | Height of the dialog box.<br>**NOTE**<br>- Default maximum height of the dialog box: 0.9 x (Window height – Safe area)<br>- When this parameter is set to a percentage, the reference height of the dialog box is the height of the window where the dialog box is located minus the safe area. You can decrease or increase the height as needed.| 473| shadow<sup>12+</sup>| [ShadowOptions](arkui-ts/ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](arkui-ts/ts-universal-attributes-image-effect.md#shadowstyle10) | No| Shadow of the dialog box.<br>Default value on 2-in-1 devices: **ShadowStyle.OUTER_FLOATING_MD** when the dialog box is focused and **ShadowStyle.OUTER_FLOATING_SM** otherwise On other devices, the dialog box has no shadow by default.| 474| backgroundBlurStyle<sup>12+</sup> | [BlurStyle](arkui-ts/ts-universal-attributes-background.md#blurstyle9) | No | Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**NOTE**<br>Setting this parameter to **BlurStyle.NONE** disables the background blur. When **backgroundBlurStyle** is set to a value other than **NONE**, do not set **backgroundColor**. If you do, the color display may not produce the expected visual effect.| 475 476## BaseDialogOptions<sup>11+</sup> 477 478Defines the options of the dialog box. 479 480**System capability**: SystemCapability.ArkUI.ArkUI.Full 481 482| Name | Type | Mandatory| Description | 483| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 484| maskRect | [Rectangle](arkui-ts/ts-methods-alert-dialog-box.md#rectangle8) | No | Mask area.<br>Default value: **{ x: 0, y: 0, width: '100%', height: '100%' }**<br>**NOTE**<br>**maskRect** does not take effect when **showInSubWindow** is set to **true**.<br>If only partial properties are set, the unspecified properties default to **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 485| alignment | [DialogAlignment](arkui-ts/ts-methods-alert-dialog-box.md#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**<br>**NOTE**<br>If **showInSubWindow** is set to **true** in **UIExtension**, the dialog box is aligned with the host window based on **UIExtension**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 486| offset | [Offset](arkui-ts/ts-types.md#offset) | No | Offset of the dialog box based on the **alignment** settings.<br>Default value: **{ dx: 0 , dy: 0 }**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 487| isModal | boolean | No | Whether the dialog box is a modal, which has a mask applied and does not allow for interaction with other components around the menu. <br>**true**: The dialog box is a modal. <br>**false**: The dialog box is not a modal.<br>Default value: **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 488| showInSubWindow | boolean | No | Whether to show the dialog box in a subwindow when the dialog box needs to be displayed outside the main window. <br>**true**: The dialog box is shown in a subwindow.<br>Default value: **false**, meaning the dialog box is displayed within the application, not in a separate subwindow<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 489| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | No| Callback for interactive dismissal of the dialog box.<br>**NOTE**<br>1. If this callback is registered, the dialog box will not be dismissed immediately after the user touches the mask or the Back button, presses the Esc key, or swipes left or right on the screen. The **reason** parameter in the callback is used to determine whether the dialog box can be dismissed. The reason returned by the component does not support the value **CLOSE_BUTTON**.<br>2. In the **onWillDismiss** callback, another **onWillDismiss** callback is not allowed.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 490| autoCancel<sup>12+</sup> | boolean | No | Whether to dismiss the dialog box when the mask is touched. The value **true** means to dismiss the dialog box when the mask is touched, and **false** means the opposite.<br>Default value: **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 491| maskColor<sup>12+</sup> | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | No | Mask color.<br>Default value: **0x33000000**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 492| transition<sup>12+</sup> | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10) | No | Transition effect for the appearance and disappearance of the dialog box.<br>**NOTE**<br> 1. If this parameter is not set, the default effect is used.<br> 2. Touching the Back button during the appearance animation pauses the appearance animation and starts the disappearance animation. The final effect is one obtained after the curves of the appearance and disappearance animations are combined.<br> 3. Touching the Back button during the exit animation does not affect the animation playback. Touching the Back button again closes the application.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 493| dialogTransition<sup>19+</sup> | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10) | No | Transition effect for the dialog box content. By default, there is no transition effect.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 494| maskTransition<sup>19+</sup> | [TransitionEffect](arkui-ts/ts-transition-animation-component.md#transitioneffect10) | No | Transition effect for the mask. By default, there is no transition effect.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 495| onDidAppear<sup>12+</sup> | () => void | No| Event callback when the dialog box appears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onDidAppear**. The settings take effect next time the dialog box appears.<br>3. If the user dismisses the dialog box immediately after it appears, **onWillDisappear** is invoked before **onDidAppear**.<br>4. If the dialog box is dismissed before its appearance animation is finished, this callback is not invoked.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 496| onDidDisappear<sup>12+</sup> | () => void | No| Event callback when the dialog box disappears.<br>**NOTE**<br>The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > onWillDisappear > onDidDisappear.<br>This callback is not triggered if the dialog box disappearance animation is interrupted (for example, by page navigation).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 497| onWillAppear<sup>12+</sup> | () => void | No| Event callback when the dialog box is about to appear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onWillAppear**. The settings take effect next time the dialog box appears.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 498| onWillDisappear<sup>12+</sup> | () => void | No| Event callback when the dialog box is about to disappear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > onWillDisappear > onDidDisappear.<br>2. If the user dismisses the dialog box immediately after it appears, **onWillDisappear** is invoked before **onDidAppear**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 499| keyboardAvoidMode<sup>12+</sup> | [KeyboardAvoidMode](./arkui-ts/ts-types.md#keyboardavoidmode12) | No| How the dialog box avoids the soft keyboard when it is brought up.<br>Default value: **KeyboardAvoidMode.DEFAULT**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 500| enableHoverMode<sup>14+</sup> | boolean | No | Whether to respond when the device is in semi-folded mode. The value **true** means to respond when the device is in semi-folded mode.<br>Default value: **false**, meaning not to respond when the device is in semi-folded mode.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 501| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](arkui-ts/ts-appendix-enums.md#hovermodeareatype14) | No | Display area of the dialog box in the hover state.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 502| backgroundBlurStyleOptions<sup>19+</sup> | [BackgroundBlurStyleOptions](arkui-ts/ts-universal-attributes-background.md#backgroundblurstyleoptions10) | No| Options for customizing the background blur style. For details about the default value, see **BackgroundBlurStyleOptions**.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 503| backgroundEffect<sup>19+</sup> | [BackgroundEffectOptions](arkui-ts/ts-universal-attributes-background.md#backgroundeffectoptions11) | No| Options for customizing the background effect. For details about the default value, see **BackgroundEffectOptions**.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 504| keyboardAvoidDistance<sup>15+</sup> | [LengthMetrics](js-apis-arkui-graphics.md#lengthmetrics12) | No | Distance between the dialog box and the keyboard after keyboard avoidance is applied.<br>**NOTE**<br>- Default value: **16vp**<br>- Default unit: vp<br>- This parameter takes effect only when **keyboardAvoidMode** is set to **DEFAULT**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 505| levelMode<sup>15+</sup> | [LevelMode](#levelmode15) | No | Display level of the dialog box.<br>**NOTE**<br>- Default value: **LevelMode.OVERLAY**<br>- This parameter takes effect only when **showInSubWindow** is set to **false**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 506| levelUniqueId<sup>15+</sup> | number | No | [Unique ID](js-apis-arkui-frameNode.md#getuniqueid12) of the node under the display level for the page-level dialog box.<br>Value range: a number no less than 0<br>**NOTE**<br>- This parameter takes effect only when **levelMode** is set to **LevelMode.EMBEDDED**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 507| immersiveMode<sup>15+</sup> | [ImmersiveMode](#immersivemode15) | No | Overlay effect for the page-level dialog box.<br>**NOTE**<br>- Default value: **ImmersiveMode.DEFAULT**<br>- This parameter takes effect only when **levelMode** is set to **LevelMode.EMBEDDED**.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 508| levelOrder<sup>18+</sup> | [LevelOrder](#levelorder18) | No | Display order of the dialog box.<br>**NOTE**<br>- Default value: **LevelOrder.clamp(0)**<br>- Dynamic updating is not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 509| focusable<sup>19+</sup> | boolean | No | Whether the dialog box can gain focus. <br>**true**: The dialog box can gain focus.<br>**false**: The dialog box cannot gain focus.<br>Default value: **true**.<br>**NOTE**<br>Only dialog boxes that are displayed on top of the current window can gain focus.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 510 511## DismissDialogAction<sup>12+</sup> 512 513Provides information about the action to dismiss the dialog box. 514 515**Atomic service API**: This API can be used in atomic services since API version 12. 516 517**System capability**: SystemCapability.ArkUI.ArkUI.Full 518 519### Attributes 520 521| Name | Type | Read-only| Optional| Description | 522| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 523| dismiss | Callback<void> | No | No | Callback for dismissing the dialog box. This API is called only when the dialog box needs to be exited.| 524| reason | [DismissReason](#dismissreason12) | No | No | Reason why the dialog box cannot be dismissed. You must specify whether to close the dialog box for each of the listed actions.| 525 526## DismissReason<sup>12+</sup> 527 528Enumerates the reasons for dialog box dismissal. 529 530**System capability**: SystemCapability.ArkUI.ArkUI.Full 531 532| Name | Value | Description | 533| ------------- | ---- | ------------------------------------------------------------ | 534| PRESS_BACK | 0 | Touching the Back button, swiping left or right on the screen, or pressing the Esc key.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 535| TOUCH_OUTSIDE | 1 | Touching the mask.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 536| CLOSE_BUTTON | 2 | Touching the Close button.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 537| SLIDE_DOWN | 3 | Swiping down.<br>**NOTE**<br>This API is effective only in [sheet transition](./arkui-ts/ts-universal-attributes-sheet-transition.md).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 538| SLIDE<sup>20+</sup> | 4 | Swiping from the edge of the screen.<br>**NOTE**<br>This API is effective only in [sheet transition](./arkui-ts/ts-universal-attributes-sheet-transition.md).<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 539 540## LevelMode<sup>15+</sup> 541 542Enumerates the display level modes of the dialog box. 543 544**Atomic service API**: This API can be used in atomic services since API version 15. 545 546**System capability**: SystemCapability.ArkUI.ArkUI.Full 547 548| Name | Value | Description | 549| ------- | ---- | ------------------------------------------------ | 550| OVERLAY | 0 | The dialog box is displayed at the root node level of the application window and remains visible during navigation.| 551| EMBEDDED | 1 | The dialog box is a child of the page's route/navigation and is hidden when the page is hidden.| 552 553## ImmersiveMode<sup>15+</sup> 554 555Enumerates the display area modes of the dialog box mask within a page. 556 557**Atomic service API**: This API can be used in atomic services since API version 15. 558 559**System capability**: SystemCapability.ArkUI.ArkUI.Full 560 561| Name | Value | Description | 562| ------- | ---- | ------------------------------------------------ | 563| DEFAULT | 0 | The dialog box mask follows the layout constraints of its parent node.| 564| EXTEND | 1 | The dialog box mask can extend to cover the status bar and navigation bar for a more immersive look. 565 566## Button 567 568Describes the menu item button in the action menu. 569 570**System capability**: SystemCapability.ArkUI.ArkUI.Full 571 572| Name | Type | Mandatory | Description | 573| ----- | ---------------------------------------- | ---- | ------- | 574| text | string \| [Resource](arkui-ts/ts-types.md#resource) | Yes | Button text.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 575| color | string \| [Resource](arkui-ts/ts-types.md#resource) | Yes | Text color of the button.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 576| primary<sup>12+</sup> | boolean | No | Whether the button responds to the **Enter** key by default when the dialog box has focus and the **Tab** key is not pressed for sequential focus navigation. If there are multiple buttons, set this parameter to **true** for only one button. Otherwise, no button will respond. Multiple dialog boxes can automatically gain focus and respond to user interactions in a sequential manner. <br>**true**: The button responds to the **Enter** key by default.<br>**false**: The button responds to the **Enter** key by default.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 577 578## Example 579 580This example demonstrates how to call **getState()** through **promptAction.DialogController** to obtain the current state of a dialog box. 581 582```ts 583// xxx.ets 584import { BusinessError } from '@kit.BasicServicesKit'; 585import { ComponentContent, promptAction } from '@kit.ArkUI'; 586 587@Component 588struct CustomDialogExample { 589 build() { 590 Column() { 591 Text('Hello') 592 .fontSize(50) 593 .fontWeight(FontWeight.Bold) 594 .margin({ bottom: 36 }) 595 Button('Close Dialog Box') 596 .onClick(() => { 597 if (this.getDialogController()) { 598 this.getDialogController().close(); 599 } 600 }) 601 Button('Obtain State') 602 .onClick(() => { 603 if (this.getDialogController()) { 604 let state: promptAction.CommonState = this.getDialogController().getState(); 605 console.info('state:' + state); // Display the dialog box state. 606 } 607 }) 608 609 }.backgroundColor('#FFF0F0F0') 610 } 611} 612 613@Builder 614function buildText() { 615 CustomDialogExample() 616} 617 618@Entry 619@Component 620struct Index { 621 622 private dialogController: promptAction.DialogController = new promptAction.DialogController() 623 624 build() { 625 Row() { 626 Column() { 627 Button("click me") 628 .onClick(() => { 629 let uiContext = this.getUIContext(); 630 let promptAction = uiContext.getPromptAction(); 631 let contentNode = new ComponentContent(uiContext, wrapBuilder(buildText), 632 ); 633 634 promptAction.openCustomDialogWithController(contentNode, this.dialogController, { 635 636 transition: TransitionEffect.OPACITY.animation({ 637 duration: 3000 638 }) 639 }).then(() => { 640 console.info('succeeded') 641 }).catch((error: BusinessError) => { 642 console.error(`OpenCustomDialogWithController args error code is ${error.code}, message is ${error.message}`); 643 }) 644 }) 645 } 646 .width('100%') 647 .height('100%') 648 } 649 .height('100%') 650 } 651} 652``` 653 654## promptAction.showToast<sup>(deprecated)</sup> 655 656showToast(options: ShowToastOptions): void 657 658Creates and displays a toast. 659 660> **NOTE** 661> 662> This API is deprecated since API version 18. Directly using **showToast** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) and then call the [showToast](js-apis-arkui-UIContext.md#showtoast) API through this object. 663> 664> Since API version 10, you can use the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. 665> 666> The toast has a fixed style and does not support content customization. For specific supported capabilities, see [ShowToastOptions](#showtoastoptions). 667 668**Atomic service API**: This API can be used in atomic services since API version 11. 669 670**System capability**: SystemCapability.ArkUI.ArkUI.Full 671 672**Parameters** 673 674| Name | Type | Mandatory| Description | 675| ------- | ------------------------------------- | ---- | -------------- | 676| options | [ShowToastOptions](#showtoastoptions) | Yes | Toast options.| 677 678**Error codes** 679 680For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 681 682| ID| Error Message | 683| -------- | ------------------------------------------------------------ | 684| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 685| 100001 | Internal error. | 686 687**Example** 688 689```ts 690import { promptAction } from '@kit.ArkUI'; 691import { BusinessError } from '@kit.BasicServicesKit'; 692 693@Entry 694@Component 695struct toastExample { 696 build() { 697 Column() { 698 Button('Show toast').fontSize(20) 699 .onClick(() => { 700 try { 701 promptAction.showToast({ 702 message: 'Hello World', 703 duration: 2000 704 }); 705 } catch (error) { 706 let message = (error as BusinessError).message; 707 let code = (error as BusinessError).code; 708 console.error(`showToast args error code is ${code}, message is ${message}`); 709 }; 710 }) 711 }.height('100%').width('100%').justifyContent(FlexAlign.Center) 712 } 713} 714``` 715 716Below is a toast in API version 11 and earlier versions. 717 718 719 720Below is a toast in API version 12 and later versions. 721 722 723 724## promptAction.showDialog<sup>(deprecated)</sup> 725 726showDialog(options: ShowDialogOptions): Promise<ShowDialogSuccessResponse> 727 728Creates and displays a dialog box in the given settings. This API uses a promise to return the result. 729 730> **NOTE** 731> 732> This API is deprecated since API version 18. Directly using **showDialog** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) and then call the [showDialog](js-apis-arkui-UIContext.md#showdialog-1) API through this object. 733> 734> Since API version 10, you can use the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. 735 736**Atomic service API**: This API can be used in atomic services since API version 11. 737 738**System capability**: SystemCapability.ArkUI.ArkUI.Full 739 740**Parameters** 741 742| Name | Type | Mandatory| Description | 743| ------- | --------------------------------------- | ---- | ------------ | 744| options | [ShowDialogOptions](#showdialogoptions) | Yes | Dialog box options.| 745 746**Return value** 747 748| Type | Description | 749| ------------------------------------------------------------ | ---------------- | 750| Promise<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | Promise used to return the dialog box response result.| 751 752**Error codes** 753 754For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 755 756| ID| Error Message | 757| -------- | ------------------------------------------------------------ | 758| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 759| 100001 | Internal error. | 760 761**Example** 762 763```ts 764import { promptAction } from '@kit.ArkUI'; 765 766promptAction.showDialog({ 767 title: 'Title Info', 768 message: 'Message Info', 769 buttons: [ 770 { 771 text: 'button1', 772 color: '#000000' 773 }, 774 { 775 text: 'button2', 776 color: '#000000' 777 } 778 ], 779}) 780 .then(data => { 781 console.info('showDialog success, click button: ' + data.index); 782 }) 783 .catch((err: Error) => { 784 console.info('showDialog error: ' + err); 785 }) 786``` 787 788 789 790## promptAction.showDialog<sup>(deprecated)</sup> 791 792showDialog(options: ShowDialogOptions, callback: AsyncCallback<ShowDialogSuccessResponse>):void 793 794Creates and displays a dialog box. This API uses an asynchronous callback to return the result. 795 796> **NOTE** 797> 798> This API is deprecated since API version 18. Directly using **showDialog** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) and then call the [showDialog](js-apis-arkui-UIContext.md#showdialog) API through this object. 799> 800> Since API version 10, you can use the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. 801 802**Atomic service API**: This API can be used in atomic services since API version 11. 803 804**System capability**: SystemCapability.ArkUI.ArkUI.Full 805 806**Parameters** 807 808| Name | Type | Mandatory| Description | 809| -------- | ------------------------------------------------------------ | ---- | ------------------------ | 810| options | [ShowDialogOptions](#showdialogoptions) | Yes | Dialog box options.| 811| callback | AsyncCallback<[ShowDialogSuccessResponse](#showdialogsuccessresponse)> | Yes | Callback used to return the dialog box response result. | 812 813**Error codes** 814 815For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 816 817| ID| Error Message | 818| -------- | ------------------------------------------------------------ | 819| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 820| 100001 | Internal error. | 821 822**Example** 823 824```ts 825import { promptAction } from '@kit.ArkUI'; 826import { BusinessError } from '@kit.BasicServicesKit'; 827 828try { 829 promptAction.showDialog({ 830 title: 'showDialog Title Info', 831 message: 'Message Info', 832 buttons: [ 833 { 834 text: 'button1', 835 color: '#000000' 836 }, 837 { 838 text: 'button2', 839 color: '#000000' 840 } 841 ] 842 }, (err, data) => { 843 if (err) { 844 console.info('showDialog err: ' + err); 845 return; 846 } 847 console.info('showDialog success callback, click button: ' + data.index); 848 }); 849} catch (error) { 850 let message = (error as BusinessError).message; 851 let code = (error as BusinessError).code; 852 console.error(`showDialog args error code is ${code}, message is ${message}`); 853}; 854``` 855 856 857 858When the **showInSubWindow** attribute is set to **true**, the toast can be displayed outside the window. 859 860```ts 861import { promptAction } from '@kit.ArkUI'; 862import { BusinessError } from '@kit.BasicServicesKit'; 863 864try { 865 promptAction.showDialog({ 866 title: 'showDialog Title Info', 867 message: 'Message Info', 868 isModal: true, 869 showInSubWindow: true, 870 buttons: [ 871 { 872 text: 'button1', 873 color: '#000000' 874 }, 875 { 876 text: 'button2', 877 color: '#000000' 878 } 879 ] 880 }, (err, data) => { 881 if (err) { 882 console.info('showDialog err: ' + err); 883 return; 884 } 885 console.info('showDialog success callback, click button: ' + data.index); 886 }); 887} catch (error) { 888 let message = (error as BusinessError).message; 889 let code = (error as BusinessError).code; 890 console.error(`showDialog args error code is ${code}, message is ${message}`); 891}; 892``` 893 894 895 896This example demonstrates the usage of dialog box lifecycle callbacks. 897 898```ts 899// xxx.ets 900import { BusinessError } from '@kit.BasicServicesKit'; 901 902@Entry 903@Component 904struct DialogExample { 905 @State log: string = 'Log information:'; 906 build() { 907 Column() { 908 Button('showDialog') 909 .onClick(() => { 910 this.showCustomDialog(); 911 }) 912 Text(this.log).fontSize(30).margin({ top: 200 }) 913 }.width('100%').margin({ top: 5 }) 914 } 915 916 showCustomDialog() { 917 try { 918 this.getUIContext().getPromptAction().showDialog({ 919 title: 'Confirm', 920 message: 'Are you sure you want to continue?', 921 alignment: DialogAlignment.Bottom, 922 buttons: [ 923 { 924 text: 'Cancel', 925 color: '#999999' 926 }, 927 { 928 text: 'OK', 929 color: '#007DFF' 930 } 931 ], 932 onDidAppear: () => { 933 this.log += '# onDidAppear'; 934 console.info("showDialog,is onDidAppear!"); 935 }, 936 onDidDisappear: () => { 937 this.log += '# onDidDisappear'; 938 console.info("showDialog,is onDidDisappear!"); 939 }, 940 onWillAppear: () => { 941 this.log = 'Log information:#onWillAppear'; 942 console.info("showDialog,is onWillAppear!"); 943 }, 944 onWillDisappear: () => { 945 this.log += '# onWillDisappear'; 946 console.info("showDialog,is onWillDisappear!"); 947 }, 948 }) 949 } catch (error) { 950 let err: BusinessError = error as BusinessError; 951 console.error(`Exception caught: ${err.code}, ${err.message}`); 952 } 953 } 954} 955``` 956 957 958 959 960 961## promptAction.showActionMenu<sup>(deprecated)</sup> 962 963showActionMenu(options: ActionMenuOptions, callback: AsyncCallback<ActionMenuSuccessResponse>):void 964 965Creates and displays an action menu. This API uses an asynchronous callback to return the result. 966 967> **NOTE** 968> 969> This API is deprecated since API version 18. Directly using **showActionMenu** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) and then call the [showActionMenu](js-apis-arkui-UIContext.md#showactionmenu11) API through this object. 970> 971> Since API version 11, you can use the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. 972 973**Atomic service API**: This API can be used in atomic services since API version 11. 974 975**System capability**: SystemCapability.ArkUI.ArkUI.Full 976 977**Parameters** 978 979| Name | Type | Mandatory| Description | 980| -------- | ------------------------------------------------------------ | ---- | ------------------ | 981| options | [ActionMenuOptions](#actionmenuoptions) | Yes | Action menu options. | 982| callback | AsyncCallback<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | Yes | Callback used to return the action menu response result.| 983 984**Error codes** 985 986For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 987 988| ID| Error Message | 989| -------- | ------------------------------------------------------------ | 990| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 991| 100001 | Internal error. | 992 993**Example 1** 994 995```ts 996import { promptAction } from '@kit.ArkUI'; 997import { BusinessError } from '@kit.BasicServicesKit'; 998 999try { 1000 promptAction.showActionMenu({ 1001 title: 'Title Info', 1002 buttons: [ 1003 { 1004 text: 'item1', 1005 color: '#666666' 1006 }, 1007 { 1008 text: 'item2', 1009 color: '#000000' 1010 }, 1011 ] 1012 }, (err, data) => { 1013 if (err) { 1014 console.info('showActionMenu err: ' + err); 1015 return; 1016 } 1017 console.info('showActionMenu success callback, click button: ' + data.index); 1018 }) 1019} catch (error) { 1020 let message = (error as BusinessError).message 1021 let code = (error as BusinessError).code 1022 console.error(`showActionMenu args error code is ${code}, message is ${message}`); 1023}; 1024``` 1025 1026 1027 1028**Example 2** 1029 1030This example demonstrates how to configure the lifecycle callbacks for **showActionMenu**. 1031 1032```ts 1033import { promptAction } from '@kit.ArkUI'; 1034 1035@Entry 1036@Component 1037struct Index { 1038 @State isShown: boolean = false 1039 @State textColor: Color = Color.Black 1040 @State blueColor: Color = Color.Blue 1041 1042 @State onWillAppear: boolean = false 1043 @State onDidAppear: boolean = false 1044 @State onWillDisappear: boolean = false 1045 @State onDidDisappear: boolean = false 1046 build() { 1047 Column({ space: 50 }) { 1048 Text('onWillAppear').fontColor(this.onWillAppear ? this.blueColor : this.textColor) 1049 Text('onDidAppear').fontColor(this.onDidAppear ? this.blueColor : this.textColor) 1050 Text('onWillDisappear').fontColor(this.onWillDisappear ? this.blueColor : this.textColor) 1051 Text('onDidDisappear').fontColor(this.onDidDisappear ? this.blueColor : this.textColor) 1052 Button('click') 1053 .width(200) 1054 .height(100) 1055 .margin(100) 1056 .fontColor(this.textColor) 1057 .onClick(() => { 1058 promptAction.showActionMenu({ 1059 title: 'showActionMenu Title Info', 1060 buttons: [ 1061 { 1062 text: 'item1', 1063 color: '#666666' 1064 }, 1065 { 1066 text: 'item2', 1067 color: '#000000' 1068 }, 1069 ], 1070 onWillAppear:() => { 1071 console.info("promptAction menu cycle life onWillAppear"); 1072 this.onWillAppear = true; 1073 }, 1074 onDidAppear:() => { 1075 console.info("promptAction menu cycle life onDidAppear"); 1076 this.onDidAppear = true; 1077 }, 1078 onWillDisappear:() => { 1079 this.isShown = false; 1080 console.info("promptAction menu cycle life onWillDisappear"); 1081 this.onWillDisappear = true; 1082 }, 1083 onDidDisappear:() => { 1084 console.info("promptAction menu cycle life onDidDisappear"); 1085 this.onDidDisappear = true; 1086 } 1087 }) 1088 .then(data => { 1089 console.info('showActionMenu success, click button: ' + data.index); 1090 }) 1091 .catch((err: Error) => { 1092 console.info('showActionMenu error: ' + err); 1093 }) 1094 }) 1095 } 1096 .width('100%') 1097 } 1098} 1099``` 1100 1101 1102 1103## promptAction.showActionMenu<sup>(deprecated)</sup> 1104 1105showActionMenu(options: ActionMenuOptions): Promise<ActionMenuSuccessResponse> 1106 1107Creates and displays an action menu in the given settings. This API uses a promise to return the result. 1108 1109> **NOTE** 1110> 1111> This API is deprecated since API version 18. Directly using **showActionMenu** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) and then call the [showActionMenu](js-apis-arkui-UIContext.md#showactionmenu) API through this object. 1112> 1113> Since API version 10, you can use the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. 1114 1115**Atomic service API**: This API can be used in atomic services since API version 11. 1116 1117**System capability**: SystemCapability.ArkUI.ArkUI.Full 1118 1119**Parameters** 1120 1121| Name | Type | Mandatory| Description | 1122| ------- | --------------------------------------- | ---- | -------------- | 1123| options | [ActionMenuOptions](#actionmenuoptions) | Yes | Action menu options.| 1124 1125**Return value** 1126 1127| Type | Description | 1128| ------------------------------------------------------------ | -------------- | 1129| Promise<[ActionMenuSuccessResponse](#actionmenusuccessresponse)> | Promise used to return the action menu response result.| 1130 1131**Error codes** 1132 1133For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 1134 1135| ID| Error Message | 1136| -------- | ------------------------------------------------------------ | 1137| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1138| 100001 | Internal error. | 1139 1140**Example** 1141 1142```ts 1143import { promptAction } from '@kit.ArkUI'; 1144 1145promptAction.showActionMenu({ 1146 title: 'showActionMenu Title Info', 1147 buttons: [ 1148 { 1149 text: 'item1', 1150 color: '#666666' 1151 }, 1152 { 1153 text: 'item2', 1154 color: '#000000' 1155 }, 1156 ] 1157}) 1158 .then(data => { 1159 console.info('showActionMenu success, click button: ' + data.index); 1160 }) 1161 .catch((err: Error) => { 1162 console.info('showActionMenu error: ' + err); 1163 }) 1164``` 1165 1166 1167 1168## promptAction.openCustomDialog<sup>(deprecated)</sup> 1169 1170openCustomDialog(options: CustomDialogOptions): Promise<number> 1171 1172Opens a custom dialog box. This API uses a promise to return the result. 1173 1174<!--Del-->This API cannot be used in **ServiceExtension**.<!--DelEnd--> 1175 1176**isModal = true** and **showInSubWindow = true** cannot be used at the same time. 1177 1178By default, the width of the dialog box in portrait mode is the width of the window where it is located minus the left and right margins (40 vp for 2-in-1 devices and 16 vp for other devices), and the maximum width is 400 vp. 1179 1180> **NOTE** 1181> 1182> This API is supported since API version 11 and deprecated since API version 18. Directly using **openCustomDialog** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) and then call the [openCustomDialog](js-apis-arkui-UIContext.md#opencustomdialog12-1) API through this object. 1183> 1184> Since API version 12, you can use the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. 1185 1186**Atomic service API**: This API can be used in atomic services since API version 12. 1187 1188**System capability**: SystemCapability.ArkUI.ArkUI.Full 1189 1190**Parameters** 1191 1192| Name | Type | Mandatory| Description | 1193| ------- | --------------------------------------------- | ---- | ------------------ | 1194| options | [CustomDialogOptions](#customdialogoptions11) | Yes | Content of the custom dialog box.| 1195 1196**Return value** 1197 1198| Type | Description | 1199| --------------------- | --------------------------------------- | 1200| Promise<number> | ID of the custom dialog box, which can be used in **closeCustomDialog**.| 1201 1202**Error codes** 1203 1204For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 1205 1206| ID| Error Message | 1207| -------- | ------------------------------------------------------------ | 1208| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1209| 100001 | Internal error. | 1210 1211**Example** 1212 1213```ts 1214import { promptAction } from '@kit.ArkUI'; 1215import { BusinessError } from '@kit.BasicServicesKit'; 1216 1217@Entry 1218@Component 1219struct Index { 1220 private customDialogComponentId: number = 0; 1221 1222 @Builder 1223 customDialogComponent() { 1224 Column() { 1225 Text('Dialog box').fontSize(30) 1226 Row({ space: 50 }) { 1227 Button("OK").onClick(() => { 1228 try { 1229 promptAction.closeCustomDialog(this.customDialogComponentId) 1230 } catch (error) { 1231 let message = (error as BusinessError).message; 1232 let code = (error as BusinessError).code; 1233 console.error(`closeCustomDialog error code is ${code}, message is ${message}`); 1234 } 1235 }) 1236 Button("Cancel").onClick(() => { 1237 try { 1238 promptAction.closeCustomDialog(this.customDialogComponentId) 1239 } catch (error) { 1240 let message = (error as BusinessError).message; 1241 let code = (error as BusinessError).code; 1242 console.error(`closeCustomDialog error code is ${code}, message is ${message}`); 1243 } 1244 }) 1245 } 1246 }.height(200).padding(5).justifyContent(FlexAlign.SpaceBetween) 1247 } 1248 1249 build() { 1250 Row() { 1251 Column({ space: 20 }) { 1252 Text('In-component dialog box') 1253 .fontSize(30) 1254 .onClick(() => { 1255 promptAction.openCustomDialog({ 1256 builder: () => { 1257 this.customDialogComponent() 1258 }, 1259 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 1260 console.info("reason" + JSON.stringify(dismissDialogAction.reason)); 1261 console.log("dialog onWillDismiss"); 1262 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 1263 dismissDialogAction.dismiss(); 1264 } 1265 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 1266 dismissDialogAction.dismiss(); 1267 } 1268 } 1269 }).then((dialogId: number) => { 1270 this.customDialogComponentId = dialogId; 1271 }) 1272 .catch((error: BusinessError) => { 1273 console.error(`openCustomDialog error code is ${error.code}, message is ${error.message}`); 1274 }) 1275 }) 1276 } 1277 .width('100%') 1278 } 1279 .height('100%') 1280 } 1281} 1282 1283``` 1284 1285This example demonstrates how to set styles of a dialog box, including the width, height, background color, and shadow. 1286 1287> **NOTE** 1288> 1289> Directly using **openCustomDialog** can lead to ambiguous instance issues. To avoid this, it is recommended that you obtain a [PromptAction](js-apis-arkui-UIContext.md#promptaction) instance using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext), and then call [openCustomDialog](js-apis-arkui-UIContext.md#opencustomdialog12-1) on the obtained instance. 1290 1291```ts 1292import { LevelMode, ImmersiveMode } from '@kit.ArkUI'; 1293 1294let customDialogId: number = 0; 1295 1296@Builder 1297function customDialogBuilder(uiContext: UIContext) { 1298 Column() { 1299 Text('Custom dialog Message').fontSize(10) 1300 Row() { 1301 Button("OK").onClick(() => { 1302 uiContext.getPromptAction().closeCustomDialog(customDialogId); 1303 }) 1304 Blank().width(50) 1305 Button("Cancel").onClick(() => { 1306 uiContext.getPromptAction().closeCustomDialog(customDialogId); 1307 }) 1308 } 1309 } 1310} 1311 1312@Entry 1313@Component 1314struct Index { 1315 @State message: string = 'Hello World'; 1316 private uiContext: UIContext = this.getUIContext(); 1317 1318 @Builder 1319 customDialogComponent() { 1320 customDialogBuilder(this.uiContext) 1321 } 1322 1323 build() { 1324 Row() { 1325 Column() { 1326 Text(this.message).id("test_text") 1327 .fontSize(50) 1328 .fontWeight(FontWeight.Bold) 1329 .onClick(() => { 1330 const node: FrameNode | null = this.uiContext.getFrameNodeById("test_text") || null; 1331 this.uiContext.getPromptAction().openCustomDialog({ 1332 builder: () => { 1333 this.customDialogComponent() 1334 }, 1335 keyboardAvoidMode: KeyboardAvoidMode.NONE, 1336 showInSubWindow: false, 1337 offset: { dx: 5, dy: 5 }, 1338 backgroundColor: 0xd9ffffff, 1339 cornerRadius: 20, 1340 width: '80%', 1341 height: 200, 1342 borderWidth: 1, 1343 borderStyle: BorderStyle.Dashed, // borderStyle must be used with borderWidth in pairs. 1344 borderColor: Color.Blue, // borderColor must be used with borderWidth in pairs. 1345 shadow: ({ 1346 radius: 20, 1347 color: Color.Grey, 1348 offsetX: 50, 1349 offsetY: 0 1350 }), 1351 levelMode: LevelMode.EMBEDDED, 1352 levelUniqueId: node?.getUniqueId(), 1353 immersiveMode: ImmersiveMode.DEFAULT, 1354 }).then((dialogId: number) => { 1355 customDialogId = dialogId; 1356 }) 1357 }) 1358 } 1359 .width('100%') 1360 } 1361 .height('100%') 1362 } 1363} 1364``` 1365 1366 1367 1368This example shows how to implement a dialog box on a page. 1369 1370> **NOTE** 1371> 1372> Directly using **openCustomDialog** can lead to ambiguous instance issues. To avoid this, it is recommended that you obtain a [PromptAction](js-apis-arkui-UIContext.md#promptaction) instance using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext), and then call [openCustomDialog](js-apis-arkui-UIContext.md#opencustomdialog12-1) on the obtained instance. 1373 1374```ts 1375// Index.ets 1376import { LevelMode, ImmersiveMode } from '@kit.ArkUI'; 1377 1378let customDialogId: number = 0; 1379 1380@Builder 1381function customDialogBuilder(uiContext: UIContext) { 1382 Column() { 1383 Text('Custom dialog Message').fontSize(10).height(100) 1384 Row() { 1385 Button("Next").onClick(() => { 1386 uiContext.getRouter().pushUrl({ url: 'pages/Next' }); 1387 }) 1388 Blank().width(50) 1389 Button("Close").onClick(() => { 1390 uiContext.getPromptAction().closeCustomDialog(customDialogId); 1391 }) 1392 } 1393 }.padding(20) 1394} 1395 1396@Entry 1397@Component 1398struct Index { 1399 @State message: string = 'Hello World'; 1400 private uiContext: UIContext = this.getUIContext(); 1401 1402 @Builder 1403 customDialogComponent() { 1404 customDialogBuilder(this.uiContext) 1405 } 1406 1407 build() { 1408 Row() { 1409 Column() { 1410 Text(this.message).id("test_text") 1411 .fontSize(50) 1412 .fontWeight(FontWeight.Bold) 1413 .onClick(() => { 1414 const node: FrameNode | null = this.uiContext.getFrameNodeById("test_text") || null; 1415 this.uiContext.getPromptAction().openCustomDialog({ 1416 builder: () => { 1417 this.customDialogComponent() 1418 }, 1419 levelMode: LevelMode.EMBEDDED, 1420 levelUniqueId: node?.getUniqueId(), 1421 immersiveMode: ImmersiveMode.DEFAULT, 1422 }).then((dialogId: number) => { 1423 customDialogId = dialogId; 1424 }) 1425 }) 1426 } 1427 .width('100%') 1428 } 1429 .height('100%') 1430 } 1431} 1432``` 1433 1434```ts 1435// Next.ets 1436@Entry 1437@Component 1438struct Next { 1439 @State message: string = 'Back'; 1440 1441 build() { 1442 Row() { 1443 Column() { 1444 Button(this.message) 1445 .onClick(() => { 1446 this.getUIContext().getRouter().back(); 1447 }) 1448 } 1449 .width('100%') 1450 } 1451 .height('100%') 1452 } 1453} 1454``` 1455 1456 1457 1458## promptAction.closeCustomDialog<sup>(deprecated)</sup> 1459 1460closeCustomDialog(dialogId: number): void 1461 1462Closes the specified custom dialog box. 1463 1464> **NOTE** 1465> 1466> This API is supported since API version 11 and deprecated since API version 18. Directly using **closeCustomDialog** can lead to the issue of [ambiguous UI context](../../ui/arkts-global-interface.md#ambiguous-ui-context). To avoid this, obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object using the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) and then call the [closeCustomDialog](js-apis-arkui-UIContext.md#closecustomdialog12-1) API through this object. 1467> 1468> Since API version 12, you can use the [getPromptAction](js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](js-apis-arkui-UIContext.md#uicontext) to obtain the [PromptAction](js-apis-arkui-UIContext.md#promptaction) object associated with the current UI context. 1469 1470**Atomic service API**: This API can be used in atomic services since API version 12. 1471 1472**System capability**: SystemCapability.ArkUI.ArkUI.Full 1473 1474**Parameters** 1475 1476| Name | Type | Mandatory| Description | 1477| -------- | ------ | ---- | -------------------------------- | 1478| dialogId | number | Yes | ID of the custom dialog box to close. It is returned from **openCustomDialog**.| 1479 1480**Error codes** 1481 1482For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [promptAction Error Codes](errorcode-promptAction.md). 1483 1484| ID| Error Message | 1485| -------- | ------------------------------------------------------------ | 1486| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1487| 100001 | Internal error. | 1488 1489**Example** 1490 1491See the example of [promptAction.openCustomDialog](#promptactionopencustomdialogdeprecated). 1492
