1# Alert Dialog Box (AlertDialog) 2 3You can set the text content and response callback for an alert dialog box. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> 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 unclear. For details, see [UIContext](../js-apis-arkui-UIContext.md#uicontext). 10> 11> Since API version 10, you can use the [showAlertDialog](../js-apis-arkui-UIContext.md#showalertdialog) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext), which ensures that the alert dialog box is shown in the intended UI instance. 12 13## AlertDialog 14 15### show 16 17static show(value: AlertDialogParamWithConfirm | AlertDialogParamWithButtons | AlertDialogParamWithOptions) 18 19Shows an alert dialog box. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name | Type | Mandatory| Description| 28| ---- | --------------- | -------- | -------- | 29| value | [AlertDialogParamWithConfirm](#alertdialogparamwithconfirm) \| [AlertDialogParamWithButtons](#alertdialogparamwithbuttons) \| [AlertDialogParamWithOptions](#alertdialogparamwithoptions10)<sup>10+</sup> | Yes| Options of the alert dialog box.| 30 31## AlertDialogParam 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35| Name | Type | Mandatory| Description | 36| --------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 37| title | [ResourceStr](ts-types.md#resourcestr) | No | Title of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 38| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Subtitle of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 39| message | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 40| autoCancel | boolean | No | Whether to close the dialog box when the mask is clicked. The value **true** means to close the dialog box when the mask is clicked, and **false** means the opposite.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 41| cancel | [VoidCallback](ts-types.md#voidcallback12) | No | Callback invoked when the dialog box is closed after the mask is clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 42| alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**NOTE**<br>If **showInSubWindow** is set to **true** in **UIExtension**, the dialog box is aligned with the host window based on **UIExtension**.| 43| offset | [Offset](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.| 44| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.<br>Default value: **4**<br>Value range: an integer no less than 0<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 45| maskRect<sup>10+</sup> | [Rectangle](#rectangle8) | No | Mask area of the dialog box. Events outside the mask area are transparently transmitted, and events within the mask area are not.<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>**Atomic service API**: This API can be used in atomic services since API version 11.| 46| 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>Default value: **false**<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.| 47| isModal<sup>11+</sup> | boolean | No | Whether the dialog box is a modal. A modal dialog box has a mask applied, while a non-modal dialog box does not.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 48| backgroundColor<sup>11+</sup> | [ResourceColor](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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 49| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](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.| 50| backgroundBlurStyleOptions<sup>18+</sup> | [BackgroundBlurStyleOptions](ts-universal-attributes-background.md#backgroundblurstyleoptions10)| No| Options for customizing the background blur style.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 51| backgroundEffect<sup>18+</sup> | [BackgroundEffectOptions](ts-universal-attributes-background.md#backgroundeffectoptions11) | No| Options for customizing the background effect.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 52| onWillDismiss<sup>12+</sup> | Callback<[DismissDialogAction](#dismissdialogaction12)> | No | Callback for interactive closure of the dialog box.<br>**NOTE**<br>1. If this callback is registered, the dialog box will not be closed 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 closed. 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.| 53| cornerRadius<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [BorderRadiuses](ts-types.md#borderradiuses9) \| [LocalizedBorderRadiuses](ts-types.md#localizedborderradiuses12) | No | Radius of the rounded corners of the background.<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.<br>**NOTE**<br>When **cornerRadius** is of type LocalizedBorderRadiuses, the layout order can be dynamically adjusted based on the user's language settings.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 54| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No | Transition effect for the entrance and exit 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 entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit 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.| 55| width<sup>12+</sup> | [Dimension](ts-types.md#dimension10) | No | Width of the dialog box.<br>**NOTE**<br>- Default maximum width of the dialog box: 400 vp<br>- When this parameter is set to a percentage, the reference width of the dialog box is the width of the window where the dialog box is located. You can decrease or increase the width as needed.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| height<sup>12+</sup> | [Dimension](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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 57| borderWidth<sup>12+</sup> | [Dimension](ts-types.md#dimension10) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#localizededgewidths12) | No | <br>You can set the width for all four sides or set separate widths for individual sides.<br>Default value: **0**<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.<br>**NOTE**<br>When **borderWidth** is of type LocalizedEdgeWidths, the layout order can be dynamically adjusted based on the user's language settings.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| borderColor<sup>12+</sup> | [ResourceColor](ts-types.md#resourcecolor) \| [EdgeColors](ts-types.md#edgecolors9) \| [LocalizedEdgeColors](ts-types.md#localizededgecolors12) | No | Border color of the dialog box.<br>Default value: **Color.Black**<br> **borderColor** must be used with **borderWidth** in pairs. **NOTE**<br>When **borderColor** is of type LocalizedEdgeColors, the layout order can be dynamically adjusted based on the user's language settings.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 59| borderStyle<sup>12+</sup> | [BorderStyle](ts-appendix-enums.md#borderstyle) \| [EdgeStyles](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.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 60| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](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<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 61| textStyle<sup>12+</sup> | [TextStyle](#textstyle12) | No | Text style of the message in the dialog box.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 62| enableHoverMode<sup>14+</sup> | boolean | No | Whether to enable the hover state.<br>Default value: **false**, meaning not to enable the hover state.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 63| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](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.| 64| onWillAppear<sup>18+</sup> | Callback<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 > 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 18.| 65| onDidAppear<sup>18+</sup> | Callback<void> | No| Event callback 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. If the dialog is dismissed before its entrance animation is finished, the animation will be interrupted, and **onDidAppear** will not be triggered.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 66| onWillDisappear<sup>18+</sup> | Callback<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 > onWillDisappear > onDidDisappear.<br> **Atomic service API**: This API can be used in atomic services since API version 18.| 67| onDidDisappear<sup>18+</sup> | Callback<void> | No| Event callback when the dialog box disappears.<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 18.| 68| levelMode<sup>15+</sup> | [LevelMode](../js-apis-promptAction.md#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.| 69| 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>**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.| 70| immersiveMode<sup>15+</sup> | [ImmersiveMode](../js-apis-promptAction.md#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.| 71| 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.| 72 73## LevelOrder<sup>18+</sup> 74 75type LevelOrder = LevelOrder 76 77Defines the display order of the dialog box. 78 79**Atomic service API**: This API can be used in atomic services since API version 18. 80 81**System capability**: SystemCapability.ArkUI.ArkUI.Full 82 83| Type | Description | 84| ----------------------------------------------------- | -------------------- | 85| [LevelOrder](../js-apis-promptAction.md#levelorder18) | Display order of the dialog box.| 86 87## AlertDialogParamWithConfirm 88 89Inherits from [AlertDialogParam](#alertdialogparam). 90 91**Atomic service API**: This API can be used in atomic services since API version 11. 92 93**System capability**: SystemCapability.ArkUI.ArkUI.Full 94 95| Name | Type | Mandatory | Description | 96| ---------- | ---------------- | ---------- | ------------------------------- | 97| confirm | [AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18) | No | Information about the confirm button. When the dialog box has focus and focus has not been shifted using the **Tab** key, the button responds to the **Enter** key by default, and multiple dialog boxes can gain focus consecutively to respond automatically. The default response to the **Enter** key does not work when **defaultFocus** is set to **true**.| 98 99Priorities of the **confirm** parameters: **fontColor** and **backgroundColor** > **style** > **defaultFocus** 100 101| backgroundColor | fontColor | style | defaultFocus | Effect | 102| --------------- | --------- | --------------------------- | ------------ | -------- | 103| Green | Red | - | - | Red text on green background| 104| Green | - | DialogButtonStyle.HIGHLIGHT | - | White text on green background| 105| Green | - | DialogButtonStyle.DEFAULT | - | Blue text on green background| 106| Green | - | - | TRUE | White text on green background| 107| Green | - | - | FALSE/- | Blue text on green background| 108| - | Red | DialogButtonStyle.HIGHLIGHT | - | Red text on blue background| 109| - | Red | DialogButtonStyle.DEFAULT | - | Red text on white background| 110| - | Red | - | TRUE | Red text on blue background| 111| - | Red | - | FALSE/- | Red text on white background| 112| - | - | DialogButtonStyle.HIGHLIGHT | - | White text on blue background| 113| - | - | DialogButtonStyle.DEFAULT | - | Blue text on white background| 114| - | - | - | TRUE | White text on blue background| 115| - | - | - | FALSE/- | Blue text on white background| 116 117## AlertDialogParamWithButtons 118 119Inherits from [AlertDialogParam](#alertdialogparam). 120 121**Atomic service API**: This API can be used in atomic services since API version 11. 122 123**System capability**: SystemCapability.ArkUI.ArkUI.Full 124 125| Name | Type | Mandatory | Description | 126| --------------- | ---------------------- | ------------ | --------------------- | 127| primaryButton | [AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18) | Yes| Information about the confirm button. When the dialog box has focus and focus has not been shifted using the **Tab** key, the button responds to the **Enter** key by default, and multiple dialog boxes can gain focus consecutively to respond automatically. The default response to the **Enter** key does not work when **defaultFocus** is set to **true**.| 128| secondaryButton | [AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18) | Yes| Information about the confirm button.| 129 130## AlertDialogParamWithOptions<sup>10+</sup> 131 132Inherits from [AlertDialogParam](#alertdialogparam). 133 134**Atomic service API**: This API can be used in atomic services since API version 11. 135 136**System capability**: SystemCapability.ArkUI.ArkUI.Full 137 138| Name | Type | Mandatory | Description | 139| --------------- | ---------------------- | ------------ | --------------------- | 140| buttons | Array<[AlertDialogButtonOptions](#alertdialogbuttonoptions10)> | Yes | Buttons in the dialog box.| 141|buttonDirection | [DialogButtonDirection](#dialogbuttondirection10)| No | Direction in which buttons are laid out.<br>Default value: **DialogButtonDirection.AUTO**<br>When there are more than three buttons, the Auto mode (which automatically switches to the vertical layout when there are more than two buttons) is recommended. In non-Auto mode, buttons that extend beyond the display area are clipped.| 142 143## AlertDialogButtonOptions<sup>10+</sup> 144 145Inherits from [AlertDialogButtonBaseOptions](#alertdialogbuttonbaseoptions18). 146 147**System capability**: SystemCapability.ArkUI.ArkUI.Full 148 149| Name | Type | Mandatory| Description | 150| --------------------- | ------- | ---- | ------------------------------------------------------------ | 151| 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. This parameter does not take effect when **defaultFocus** is set to **true**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 152 153## AlertDialogButtonBaseOptions<sup>18+</sup> 154 155**Atomic service API**: This API can be used in atomic services since API version 18. 156 157**System capability**: SystemCapability.ArkUI.ArkUI.Full 158 159| Name | Type | Mandatory | Description | 160| ------------------| ---------------------- | ------------ | --------------------- | 161| enabled<sup>10+</sup> | boolean | No | Whether to respond when the button is clicked.<br>Default value: **true**<br>**true**: Respond when the button is clicked. <br>**false**: Do not respond when the button is clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 162| defaultFocus<sup>10+</sup> | boolean | No | Whether the button is the default focus.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 163| style<sup>10+</sup> | [DialogButtonStyle](ts-appendix-enums.md#dialogbuttonstyle10) | No | Style of the button.<br>Default value: **DialogButtonStyle.DEFAULT**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 164| value<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | Yes | Text of the button. If the value is null, the button is not displayed. <br>**Atomic service API**: This API can be used in atomic services since API version 11.| 165| fontColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the button.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 166| backgroundColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the button.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 167| action<sup>10+</sup> | [VoidCallback](ts-types.md#voidcallback12) | Yes | Callback upon button clicking.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 168 169## DialogButtonDirection<sup>10+</sup> 170 171**Atomic service API**: This API can be used in atomic services since API version 11. 172 173**System capability**: SystemCapability.ArkUI.ArkUI.Full 174 175| Name | Value | Description | 176| -------------------------- | --------- | --------- | 177| AUTO | 0 | Buttons are laid out horizontally when there are two or fewer buttons and vertically otherwise.| 178| HORIZONTAL | 1 | Buttons are laid out horizontally.| 179| VERTICAL | 2 | Buttons are laid out vertically.| 180 181## DialogAlignment 182 183**Atomic service API**: This API can be used in atomic services since API version 11. 184 185**System capability**: SystemCapability.ArkUI.ArkUI.Full 186 187| Name | Description | 188| ------------------------ | -------------- | 189| Top | Vertical top alignment.| 190| Center | Vertical center alignment.| 191| Bottom | Vertical bottom alignment.| 192| Default | Default alignment. | 193| TopStart<sup>8+</sup> | Top left alignment. | 194| TopEnd<sup>8+</sup> | Top right alignment. | 195| CenterStart<sup>8+</sup> | Center left alignment. | 196| CenterEnd<sup>8+</sup> | Center right alignment. | 197| BottomStart<sup>8+</sup> | Bottom left alignment. | 198| BottomEnd<sup>8+</sup> | Bottom right alignment. | 199 200## Rectangle<sup>8+</sup> 201 202The **Rectangle** type is used to represent a mask area of a dialog box. 203 204**Widget capability**: This API can be used in ArkTS widgets since API version 9. 205 206**Atomic service API**: This API can be used in atomic services since API version 11. 207 208**System capability**: SystemCapability.ArkUI.ArkUI.Full 209 210| Name | Type | Mandatory| Description | 211|--------|------------------------------|----|-----------------------------------| 212| x | [Length](ts-types.md#length) | No | X coordinate of the mask area of the dialog box relative to the upper left corner of the window.<br>Default value: **0vp**| 213| y | [Length](ts-types.md#length) | No | Y coordinate of the mask area of the dialog box relative to the upper left corner of the window.<br>Default value: **0vp**| 214| width | [Length](ts-types.md#length) | No | Width of the mask area of the dialog box.<br>Default value: **'100%'** | 215| height | [Length](ts-types.md#length) | No | Height of the mask area of the dialog box.<br>Default value: **'100%'** | 216 217> **NOTE** 218> 219> **x** and **y** can be set to a positive or negative percentage value. When **x** is set to **'100%'**, the mask area is moved rightward by the window width. When **x** is set to **'-100%'**, the mask area is moved leftward by the window width. When **y** is set to **'100%'**, the mask area is moved downward by the window height. When **y** is set to **'-100%'**, the mask area is moved upward by the window height. 220> 221> **width** and **height** can be set in percentage and can only be set to positive values. If they are set to negative values, the default values are used instead. 222> 223> The percentage is calculated based on the width and height of the window. 224 225## DismissDialogAction<sup>12+</sup> 226 227Provides information about the action to dismiss the dialog box. 228 229**Atomic service API**: This API can be used in atomic services since API version 12. 230 231**System capability**: SystemCapability.ArkUI.ArkUI.Full 232 233### Properties 234 235| Name | Type | Readable| Writable| Description | 236| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 237| dismiss | Callback<void> | No | No | Callback for closing the dialog box. This API is called only when the dialog box needs to be exited.| 238| reason | [DismissReason](../js-apis-promptAction.md#dismissreason12) | No | No | Reason why the dialog box cannot be closed. You must specify whether to close the dialog box for each of the listed actions.| 239 240## TextStyle<sup>12+</sup> 241 242**Atomic service API**: This API can be used in atomic services since API version 12. 243 244**System capability**: SystemCapability.ArkUI.ArkUI.Full 245 246| Name | Type | Mandatory| Description | 247|--------|------------------------------|----|-----------------------------------| 248| wordBreak | [WordBreak](ts-appendix-enums.md#wordbreak11) | No | Word break rule.<br>Default value: **WordBreak.BREAK_ALL**| 249 250## Example 251 252### Example 1: Displaying Dialog Boxes with Different Numbers of Buttons 253 254> **NOTE** 255> 256> To avoid confusion with **AlertDialog** instances, it is recommended that you obtain a **UIContext** instance using the [getUIContext](../js-apis-arkui-UIContext.md#uicontext) API, and then use the [showAlertDialog](../js-apis-arkui-UIContext.md#showalertdialog) API to invoke the instance's **AlertDialog.show()** method. 257 258This example demonstrates how to display dialog boxes with one, two, and three buttons. 259 260```ts 261// xxx.ets 262@Entry 263@Component 264struct AlertDialogExample { 265 build() { 266 Column({ space: 5 }) { 267 Button('one button dialog') 268 .onClick(() => { 269 // You are advised to use this.getUIContext().showAlertDialog(). 270 AlertDialog.show( 271 { 272 title: 'title', 273 message: 'text', 274 autoCancel: true, 275 alignment: DialogAlignment.Bottom, 276 offset: { dx: 0, dy: -20 }, 277 gridCount: 3, 278 confirm: { 279 value: 'button', 280 action: () => { 281 console.info('Button-clicking callback') 282 } 283 }, 284 cancel: () => { 285 console.info('Closed callbacks') 286 }, 287 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 288 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 289 console.log("dialog onWillDismiss") 290 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 291 dismissDialogAction.dismiss() 292 } 293 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 294 dismissDialogAction.dismiss() 295 } 296 } 297 } 298 ) 299 }) 300 .backgroundColor(0x317aff) 301 Button('two button dialog') 302 .onClick(() => { 303 // You are advised to use this.getUIContext().showAlertDialog(). 304 AlertDialog.show( 305 { 306 title: 'title', 307 subtitle: 'subtitle', 308 message: 'text', 309 autoCancel: true, 310 alignment: DialogAlignment.Bottom, 311 gridCount: 4, 312 offset: { dx: 0, dy: -20 }, 313 primaryButton: { 314 value: 'cancel', 315 action: () => { 316 console.info('Callback when the first button is clicked') 317 } 318 }, 319 secondaryButton: { 320 enabled: true, 321 defaultFocus: true, 322 style: DialogButtonStyle.HIGHLIGHT, 323 value: 'ok', 324 action: () => { 325 console.info('Callback when the second button is clicked') 326 } 327 }, 328 cancel: () => { 329 console.info('Closed callbacks') 330 }, 331 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 332 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 333 console.log("dialog onWillDismiss") 334 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 335 dismissDialogAction.dismiss() 336 } 337 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 338 dismissDialogAction.dismiss() 339 } 340 } 341 } 342 ) 343 }).backgroundColor(0x317aff) 344 Button('three button dialog') 345 .onClick(() => { 346 // You are advised to use this.getUIContext().showAlertDialog(). 347 AlertDialog.show( 348 { 349 title: 'title', 350 subtitle: 'subtitle', 351 message: 'text', 352 autoCancel: true, 353 alignment: DialogAlignment.Bottom, 354 gridCount: 4, 355 offset: { dx: 0, dy: -20 }, 356 buttonDirection: DialogButtonDirection.HORIZONTAL, 357 buttons: [ 358 { 359 value: 'Button', 360 action: () => { 361 console.info('Callback when button1 is clicked') 362 } 363 }, 364 { 365 value: 'Button', 366 action: () => { 367 console.info('Callback when button2 is clicked') 368 } 369 }, 370 { 371 value: 'Button', 372 enabled: true, 373 defaultFocus: true, 374 style: DialogButtonStyle.HIGHLIGHT, 375 action: () => { 376 console.info('Callback when button3 is clicked') 377 } 378 }, 379 ], 380 cancel: () => { 381 console.info('Closed callbacks') 382 }, 383 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 384 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 385 console.log("dialog onWillDismiss") 386 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 387 dismissDialogAction.dismiss() 388 } 389 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 390 dismissDialogAction.dismiss() 391 } 392 } 393 } 394 ) 395 }).backgroundColor(0x317aff) 396 }.width('100%').margin({ top: 5 }) 397 } 398} 399``` 400 401 402 403### Example 2: Opening a Dialog Box Outside the Main Window 404 405This example demonstrates how to configure a dialog box to display outside the main window on a 2-in-1 device by setting **showInSubWindow** to **true**. 406 407> **NOTE** 408> 409> To avoid confusion with **AlertDialog** instances, it is recommended that you obtain a **UIContext** instance using the [getUIContext](../js-apis-arkui-UIContext.md#uicontext) API, and then use the [showAlertDialog](../js-apis-arkui-UIContext.md#showalertdialog) API to invoke the instance's **AlertDialog.show()** method. 410 411```ts 412// xxx.ets 413@Entry 414@Component 415struct AlertDialogExample { 416 build() { 417 Column({ space: 5 }) { 418 Button('one button dialog') 419 .onClick(() => { 420 // You are advised to use this.getUIContext().showAlertDialog(). 421 AlertDialog.show( 422 { 423 title: 'title', 424 subtitle: 'subtitle', 425 message: 'text', 426 autoCancel: true, 427 alignment: DialogAlignment.Center, 428 gridCount: 4, 429 showInSubWindow: true, 430 isModal: true, 431 offset: { dx: 0, dy: -20 }, 432 buttonDirection: DialogButtonDirection.HORIZONTAL, 433 buttons: [ 434 { 435 value: 'Button', 436 action: () => { 437 console.info('Callback when button1 is clicked') 438 } 439 }, 440 { 441 value: 'Button', 442 action: () => { 443 console.info('Callback when button2 is clicked') 444 } 445 }, 446 { 447 value: 'Button', 448 enabled: true, 449 defaultFocus: true, 450 style: DialogButtonStyle.HIGHLIGHT, 451 action: () => { 452 console.info('Callback when button3 is clicked') 453 } 454 }, 455 ], 456 cancel: () => { 457 console.info('Closed callbacks') 458 }, 459 onWillDismiss: (dismissDialogAction: DismissDialogAction) => { 460 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 461 console.log("dialog onWillDismiss") 462 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 463 dismissDialogAction.dismiss() 464 } 465 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 466 dismissDialogAction.dismiss() 467 } 468 } 469 }) 470 }) 471 }.width('100%').margin({ top: 5 }).backgroundColor(0x317aff) 472 } 473} 474``` 475 476 477 478### Example 3: Setting the Dialog Box Animation 479This example illustrates how to use the **transition** API to create custom animation effects for the dialog box's appearance and disappearance. 480 481> **NOTE** 482> 483> To avoid confusion with **AlertDialog** instances, it is recommended that you obtain a **UIContext** instance using the [getUIContext](../js-apis-arkui-UIContext.md#uicontext) API, and then use the [showAlertDialog](../js-apis-arkui-UIContext.md#showalertdialog) API to invoke the instance's **AlertDialog.show()** method. 484 485```ts 486// xxx.ets 487@Entry 488@Component 489struct AlertDialogExample { 490 build() { 491 Column({ space: 5 }) { 492 Button('AlertDialog Set Duration') 493 .onClick(()=>{ 494 // You are advised to use this.getUIContext().showAlertDialog(). 495 AlertDialog.show( 496 { 497 title: 'AlertDialog 1', 498 message: 'Set Animation Duration open 3 second, close 100ms', 499 autoCancel: true, 500 alignment: DialogAlignment.Top, 501 offset: { dx: 0, dy: -20 }, 502 gridCount: 3, 503 transition:TransitionEffect.asymmetric(TransitionEffect.OPACITY 504 .animation({ duration: 3000, curve: Curve.Sharp }).combine(TransitionEffect.scale({x: 1.5, y: 1.5}).animation({duration: 3000, curve: Curve.Sharp})), 505 TransitionEffect.OPACITY.animation({ duration: 100, curve: Curve.Smooth }) 506 .combine(TransitionEffect.scale({x: 0.5, y: 0.5}).animation({duration: 100, curve: Curve.Smooth}))), 507 confirm: { 508 value: 'button', 509 action: () => { 510 console.info('Button-clicking callback') 511 } 512 }, 513 cancel: () => { 514 console.info('Closed callbacks') 515 } 516 } 517 ) 518 }) 519 .backgroundColor(0x317aff).height("88px") 520 }.width('100%').margin({ top: 5 }) 521 } 522} 523``` 524 525 526 527### Example 4: Setting the Dialog Box Style 528This example demonstrates how to set styles of an alert dialog box, including the width, height, background color, and shadow. 529 530> **NOTE** 531> 532> To avoid confusion with **AlertDialog** instances, it is recommended that you obtain a **UIContext** instance using the [getUIContext](../js-apis-arkui-UIContext.md#uicontext) API, and then use the [showAlertDialog](../js-apis-arkui-UIContext.md#showalertdialog) API to invoke the instance's **AlertDialog.show()** method. 533 534```ts 535// xxx.ets 536@Entry 537@Component 538struct AlertDialogExample { 539 build() { 540 Column({ space: 5 }) { 541 Button('one button dialog') 542 .onClick(() => { 543 // You are advised to use this.getUIContext().showAlertDialog(). 544 AlertDialog.show( 545 { 546 title: 'title', 547 message: 'text', 548 autoCancel: true, 549 alignment: DialogAlignment.Center, 550 offset: { dx: 0, dy: -20 }, 551 gridCount: 3, 552 width: 300, 553 height: 200, 554 cornerRadius: 20, 555 borderWidth: 1, 556 borderStyle: BorderStyle.Dashed,// borderStyle must be used with borderWidth in pairs. 557 borderColor: Color.Blue,// borderColor must be used with borderWidth in pairs. 558 backgroundColor: Color.White, 559 shadow: ({ radius: 20, color: Color.Grey, offsetX: 50, offsetY: 0}), 560 textStyle: { wordBreak: WordBreak.BREAK_ALL }, 561 confirm: { 562 value: 'button', 563 action: () => { 564 console.info('Button-clicking callback') 565 } 566 }, 567 cancel: () => { 568 console.info('Closed callbacks') 569 }, 570 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 571 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)) 572 console.log("dialog onWillDismiss") 573 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 574 dismissDialogAction.dismiss() 575 } 576 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 577 dismissDialogAction.dismiss() 578 } 579 } 580 } 581 ) 582 }) 583 .backgroundColor(0x317aff) 584 }.width('100%').margin({ top: 5 }) 585 } 586} 587``` 588 589 590 591### Example 5: Configuring a Dialog Box in the Hover State 592 593This example demonstrates how to set the layout area of a dialog box in hover mode on a foldable device. 594 595```ts 596@Entry 597@Component 598struct AlertDialogExample { 599 build() { 600 Column({ space: 5 }) { 601 Button('one button dialog') 602 .onClick(() => { 603 AlertDialog.show( 604 { 605 title: 'title', 606 message: 'text', 607 autoCancel: true, 608 alignment: DialogAlignment.Bottom, 609 gridCount: 3, 610 confirm: { 611 value: 'button', 612 action: () => { 613 console.info('Button-clicking callback') 614 } 615 }, 616 cancel: () => { 617 console.info('Closed callbacks') 618 }, 619 onWillDismiss:(dismissDialogAction: DismissDialogAction)=> { 620 console.info("reason=" + JSON.stringify(dismissDialogAction.reason)); 621 console.log("dialog onWillDismiss"); 622 if (dismissDialogAction.reason == DismissReason.PRESS_BACK) { 623 dismissDialogAction.dismiss(); 624 } 625 if (dismissDialogAction.reason == DismissReason.TOUCH_OUTSIDE) { 626 dismissDialogAction.dismiss(); 627 } 628 }, 629 enableHoverMode: true, 630 hoverModeArea: HoverModeAreaType.TOP_SCREEN 631 } 632 ) 633 }) 634 .backgroundColor(0x317aff) 635 }.width('100%').margin({ top: 5 }) 636 } 637} 638``` 639 640 641
