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](../apis/js-apis-arkui-UIContext.md#uicontext). 10> 11> Since API version 10, you can use the [showAlertDialog](../apis/js-apis-arkui-UIContext.md#showalertdialog) API in [UIContext](../apis/js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. 12 13## Attributes 14 15| Name | Type | Description| 16| ---- | --------------- | -------- | 17| show | [AlertDialogParamWithConfirm](#alertdialogparamwithconfirm) \| [AlertDialogParamWithButtons](#alertdialogparamwithbuttons) \| [AlertDialogParamWithOptions](#alertdialogparamwithoptions10)<sup>10+</sup> | Defines and displays the **\<AlertDialog>** component.| 18 19## AlertDialogParamWithConfirm 20| Name | Type | Mandatory | Description | 21| ---------- | ---------------- | ---------- | ------------------------------- | 22| title | [ResourceStr](ts-types.md#resourcestr) | No | Title of the dialog box.| 23| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Subtitle of the dialog box.| 24| message | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the dialog box.| 25| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked. The value **true** means to close the dialog box when the overlay is clicked, and **false** means the opposite.<br>Default value: **true**| 26| confirm | {<br>enabled<sup>10+</sup>?: boolean,<br>defaultFocus<sup>10+</sup>?: boolean,<br>style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10),<br>value: [ResourceStr](ts-types.md#resourcestr),<br>fontColor?: [ResourceColor](ts-types.md#resourcecolor),<br>backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),<br>action: () => void<br>} | No | Information about the confirm button.<br>**enabled**: whether to respond when the button is clicked. The value **true** means to respond when the button is clicked, and **false** means the opposite.<br>Default value: **true**<br>**defaultFocus**: whether the button is the default focus. The value **true** means that the button is the default focus, and **false** means the opposite.<br>Default value: **false**<br>**style**: button style.<br>Default value: **DialogButtonStyle.DEFAULT**<br>**value**: button text.<br>**fontColor**: font color of the button.<br>**backgroundColor**: background color of the button.<br>**action**: callback upon button clicking.| 27| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked.| 28| alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**| 29| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.<br>Default value: **{ dx: 0 , dy: 0 }**| 30| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.<br>Default value: **4**| 31| 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%' }**| 32| showInSubWindow<sup>11+</sup> | boolean | No| Whether to show the dialog box in a sub-window 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**.| 33| 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**| 34| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Backplane color of the dialog box.<br>Default value: **Color.Transparent**| 35| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-appendix-enums.md#blurstyle9) | No| Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**| 36 37## AlertDialogParamWithButtons 38| Name | Type | Mandatory | Description | 39| --------------- | ---------------------- | ------------ | --------------------- | 40| title | [ResourceStr](ts-types.md#resourcestr) | No | Title of the dialog box. | 41| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Subtitle of the dialog box.| 42| message | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the dialog box. | 43| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.<br>Default value: **true** | 44| primaryButton | {<br>enabled<sup>10+</sup>?: boolean,<br>defaultFocus<sup>10+</sup>?: boolean,<br>style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10),<br>value: [ResourceStr](ts-types.md#resourcestr),<br>fontColor?: [ResourceColor](ts-types.md#resourcecolor),<br>backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),<br>action: () => void;<br>} | No| Information about the confirm button.<br>**enabled**: whether to respond when the button is clicked.<br>Default value: **true**<br>**defaultFocus**: whether the button is the default focus.<br>Default value: **false**<br>**style**: button style.<br>Default value: **DialogButtonStyle.DEFAULT**<br>**value**: button text.<br>**fontColor**: font color of the button.<br>**backgroundColor**: background color of the button.<br>**action**: callback upon button clicking.| 45| secondaryButton | {<br>enabled<sup>10+</sup>?: boolean,<br>defaultFocus<sup>10+</sup>?: boolean,<br>style<sup>10+</sup>?: [DialogButtonStyle](#dialogbuttonstyle10),<br>value: [ResourceStr](ts-types.md#resourcestr),<br>fontColor?: [ResourceColor](ts-types.md#resourcecolor),<br>backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),<br>action: () => void;<br>} | No | Information about the confirm button.<br>**enabled**: whether to respond when the button is clicked.<br>Default value: **true**<br>**defaultFocus**: whether the button is the default focus.<br>Default value: **false**<br>**style**: button style.<br>Default value: **DialogButtonStyle.DEFAULT**<br>**value**: button text.<br>**fontColor**: font color of the button.<br>**backgroundColor**: background color of the button.<br>**action**: callback upon button clicking.| 46| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked. | 47| alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**| 48| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.| 49| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.| 50| 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%' }**| 51| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Backplane color of the dialog box.<br>Default value: **Color.Transparent**| 52| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-appendix-enums.md#blurstyle9) | No| Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**| 53 54## AlertDialogParamWithOptions<sup>10+</sup> 55| Name | Type | Mandatory | Description | 56| --------------- | ---------------------- | ------------ | --------------------- | 57| title | [ResourceStr](ts-types.md#resourcestr) | No | Title of the dialog box. | 58| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Subtitle of the dialog box. | 59| message | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the dialog box. | 60| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.<br>Default value: **true** | 61| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked. | 62| alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**| 63| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.| 64| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.| 65| 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%' }**| 66| buttons<sup>10+</sup> | Array<[AlertDialogButtonOptions](#alertdialogbuttonoptions10)> | No | Buttons in the dialog box.| 67|buttonDirection<sup>10+</sup> | [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.| 68| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Backplane color of the dialog box.<br>Default value: **Color.Transparent**| 69| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-appendix-enums.md#blurstyle9) | No| Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**| 70 71## AlertDialogButtonOptions<sup>10+</sup> 72| Name | Type | Mandatory | Description | 73| ------------------| ---------------------- | ------------ | --------------------- | 74| enabled | boolean | No | Whether to respond when the button is clicked.<br>Default value: **true** | 75| defaultFocus | boolean | No | Whether the button is the default focus.<br>Default value: **false** | 76| style | [DialogButtonStyle](#dialogbuttonstyle10) | No | Style of the button.<br>Default value: **DialogButtonStyle.DEFAULT** | 77| value | [ResourceStr](ts-types.md#resourcestr) | Yes | Text of the button. If the value is null, the button is not displayed. | 78| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the button. | 79| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the button. | 80| action | () => void | Yes | Callback upon button clicking. | 81 82## DialogButtonDirection<sup>10+</sup> 83| Name | Description | 84| -------------------------- | --------- | 85| AUTO | Buttons are laid out horizontally when there are two or fewer buttons and vertically otherwise.| 86| HORIZONTAL | Buttons are laid out horizontally.| 87| VERTICAL | Buttons are laid out vertically.| 88 89Priorities of the **confirm** parameters: **fontColor** and **backgroundColor** > **style** > **defaultFocus** 90 91| backgroundColor | fontColor | style | defaultFocus | Effect | 92| --------------- | --------- | --------------------------- | ------------ | -------- | 93| Green | Red | - | - | Red text on green background| 94| Green | - | DialogButtonStyle.HIGHLIGHT | - | White text on green background| 95| Green | - | DialogButtonStyle.DEFAULT | - | Blue text on green background| 96| Green | - | - | TRUE | White text on green background| 97| Green | - | - | FALSE/- | Blue text on green background| 98| - | Red | DialogButtonStyle.HIGHLIGHT | - | Red text on blue background| 99| - | Red | DialogButtonStyle.DEFAULT | - | Red text on white background| 100| - | Red | - | TRUE | Red text on blue background| 101| - | Red | - | FALSE/- | Red text on white background| 102| - | - | DialogButtonStyle.HIGHLIGHT | - | White text on blue background| 103| - | - | DialogButtonStyle.DEFAULT | - | Blue text on white background| 104| - | - | - | TRUE | White text on blue background| 105| - | - | - | FALSE/- | Blue text on white background| 106 107## DialogAlignment 108 109| Name | Description | 110| ------------------------ | ------- | 111| Top | Vertical top alignment.| 112| Center | Vertical center alignment.| 113| Bottom | Vertical bottom alignment.| 114| Default | Default alignment. | 115| TopStart<sup>8+</sup> | Top left alignment. | 116| TopEnd<sup>8+</sup> | Top right alignment. | 117| CenterStart<sup>8+</sup> | Center left alignment. | 118| CenterEnd<sup>8+</sup> | Center right alignment. | 119| BottomStart<sup>8+</sup> | Bottom left alignment. | 120| BottomEnd<sup>8+</sup> | Bottom right alignment. | 121 122## Rectangle<sup>8+</sup> 123 124The **Rectangle** type is used to represent a mask area of a dialog box. 125 126| Name | Type | Mandatory| Description | 127|--------|------------------------------|----|-----------------------------------| 128| 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**| 129| 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**| 130| width | [Length](ts-types.md#length) | No | Width of the mask area of the dialog box.<br>Default value: **'100%'** | 131| height | [Length](ts-types.md#length) | No | Height of the mask area of the dialog box.<br>Default value: **'100%'** | 132 133> **NOTE** 134> 135> **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. 136> 137> **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. 138> 139> The percentage is calculated based on the width and height of the window. 140 141## DialogButtonStyle<sup>10+</sup> 142 143| Name | Description | 144| --------- | --------------------------------- | 145| DEFAULT | Blue text on white background (black background under the dark theme).| 146| HIGHLIGHT | White text on blue background. | 147 148## Example 149 150### Example 1 151 152```ts 153// xxx.ets 154@Entry 155@Component 156struct AlertDialogExample { 157 build() { 158 Column({ space: 5 }) { 159 Button('one button dialog') 160 .onClick(() => { 161 AlertDialog.show( 162 { 163 title: 'title', 164 message: 'text', 165 autoCancel: true, 166 alignment: DialogAlignment.Bottom, 167 offset: { dx: 0, dy: -20 }, 168 gridCount: 3, 169 confirm: { 170 value: 'button', 171 action: () => { 172 console.info('Button-clicking callback') 173 } 174 }, 175 cancel: () => { 176 console.info('Closed callbacks') 177 } 178 } 179 ) 180 }) 181 .backgroundColor(0x317aff) 182 Button('two button dialog') 183 .onClick(() => { 184 AlertDialog.show( 185 { 186 title: 'title', 187 subtitle: 'subtitle', 188 message: 'text', 189 autoCancel: true, 190 alignment: DialogAlignment.Bottom, 191 gridCount: 4, 192 offset: { dx: 0, dy: -20 }, 193 primaryButton: { 194 value: 'cancel', 195 action: () => { 196 console.info('Callback when the first button is clicked') 197 } 198 }, 199 secondaryButton: { 200 enabled: true, 201 defaultFocus: true, 202 style: DialogButtonStyle.HIGHLIGHT, 203 value: 'ok', 204 action: () => { 205 console.info('Callback when the second button is clicked') 206 } 207 }, 208 cancel: () => { 209 console.info('Closed callbacks') 210 } 211 } 212 ) 213 }).backgroundColor(0x317aff) 214 Button('three button dialog') 215 .onClick(() => { 216 AlertDialog.show( 217 { 218 title: 'title', 219 subtitle: 'subtitle', 220 message: 'text', 221 autoCancel: true, 222 alignment: DialogAlignment.Bottom, 223 gridCount: 4, 224 offset: { dx: 0, dy: -20 }, 225 buttonDirection: DialogButtonDirection.HORIZONTAL, 226 buttons: [ 227 { 228 value: 'Button', 229 action: () => { 230 console.info('Callback when button1 is clicked') 231 } 232 }, 233 { 234 value: 'Button', 235 action: () => { 236 console.info('Callback when button2 is clicked') 237 } 238 }, 239 { 240 value: 'Button', 241 enabled: true, 242 defaultFocus: true, 243 style: DialogButtonStyle.HIGHLIGHT, 244 action: () => { 245 console.info('Callback when button3 is clicked') 246 } 247 }, 248 ], 249 cancel: () => { 250 console.info('Closed callbacks') 251 } 252 } 253 ) 254 }).backgroundColor(0x317aff) 255 }.width('100%').margin({ top: 5 }) 256 } 257} 258``` 259 260 261 262### Example 2 263 264```ts 265// xxx.ets 266@Entry 267@Component 268struct AlertDialogExample { 269 build() { 270 Column({ space: 5 }) { 271 Button('one button dialog') 272 .onClick(() => { 273 AlertDialog.show( 274 { 275 title: 'title', 276 subtitle: 'subtitle', 277 message: 'text', 278 autoCancel: true, 279 alignment: DialogAlignment.Center, 280 gridCount: 4, 281 showInSubWindow: true, 282 isModal: true, 283 offset: { dx: 0, dy: -20 }, 284 buttonDirection: DialogButtonDirection.HORIZONTAL, 285 buttons: [ 286 { 287 value: 'Button', 288 action: () => { 289 console.info('Callback when button1 is clicked') 290 } 291 }, 292 { 293 value: 'Button', 294 action: () => { 295 console.info('Callback when button2 is clicked') 296 } 297 }, 298 { 299 value: 'Button', 300 enabled: true, 301 defaultFocus: true, 302 style: DialogButtonStyle.HIGHLIGHT, 303 action: () => { 304 console.info('Callback when button3 is clicked') 305 } 306 }, 307 ], 308 cancel: () => { 309 console.info('Closed callbacks') 310 } 311 } 312 ) 313 }).backgroundColor(0x317aff) 314 }.width('100%').margin({ top: 5 }) 315 } 316} 317``` 318 319 320
