1# Alert Dialog Box 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) | 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.<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.<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**: text of the button.<br>**fontColor**: font color of the button.<br>**backgroundColor**: background color of the button.<br>**action**: callback when the button is selected.| 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](#rectangle10) | 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 33Priorities of the **confirm** parameters: **fontColor** and **backgroundColor** > **style** > **defaultFocus** 34 35| backgroundColor | fontColor | style | defaultFocus | Effect | 36| --------------- | --------- | --------------------------- | ------------ | -------- | 37| Green | Red | - | - | Red text on green background| 38| Green | - | DialogButtonStyle.HIGHLIGHT | - | White text on green background| 39| Green | - | DialogButtonStyle.DEFAULT | - | Blue text on green background| 40| Green | - | - | TRUE | White text on green background| 41| Green | - | - | FALSE/- | Blue text on green background| 42| - | Red | DialogButtonStyle.HIGHLIGHT | - | Red text on blue background| 43| - | Red | DialogButtonStyle.DEFAULT | - | Red text on white background| 44| - | Red | - | TRUE | Red text on blue background| 45| - | Red | - | FALSE/- | Red text on white background| 46| - | - | DialogButtonStyle.HIGHLIGHT | - | White text on blue background| 47| - | - | DialogButtonStyle.DEFAULT | - | Blue text on white background| 48| - | - | - | TRUE | White text on blue background| 49| - | - | - | FALSE/- | Blue text on white background| 50 51## AlertDialogParamWithButtons 52| Name | Type | Mandatory | Description | 53| --------------- | ---------------------- | ------------ | --------------------- | 54| title | [ResourceStr](ts-types.md#resourcestr) | No | Title of the dialog box. | 55| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No| Subtitle of the dialog box.| 56| message | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the dialog box. | 57| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.<br>Default value: **true** | 58| 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**: text of the button.<br>**fontColor**: font color of the button.<br>**backgroundColor**: background color of the button.<br>**action**: callback when the button is selected.| 59| 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**: text of the button.<br>**fontColor**: font color of the button.<br>**backgroundColor**: background color of the button.<br>**action**: callback when the button is selected.| 60| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked. | 61| alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**| 62| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.| 63| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.| 64| maskRect<sup>10+</sup> | [Rectangle](#rectangle10) | 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%' }**| 65 66## AlertDialogParamWithOptions<sup>10+</sup> 67| Name | Type | Mandatory | Description | 68| --------------- | ---------------------- | ------------ | --------------------- | 69| title | [ResourceStr](ts-types.md#resourcestr) | No | Title of the dialog box. | 70| subtitle<sup>10+</sup> | [ResourceStr](ts-types.md#resourcestr) | No | Subtitle of the dialog box. | 71| message | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the dialog box. | 72| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.<br>Default value: **true** | 73| cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked. | 74| alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**| 75| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.| 76| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.| 77| maskRect<sup>10+</sup>| [Rectangle](#rectangle10) | 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%' }**| 78| buttons<sup>10+</sup> | Array<[AlertDialogButtonOptions](#alertdialogbuttonoptions10)> | No | Buttons in the dialog box.| 79|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.| 80 81## AlertDialogButtonOptions<sup>10+</sup> 82| Name | Type | Mandatory | Description | 83| ------------------| ---------------------- | ------------ | --------------------- | 84| enabled | boolean | No | Whether to respond when the button is clicked.<br>Default value: **true** | 85| defaultFocus | boolean | No | Whether the button is the default focus.<br>Default value: **false** | 86| style | [DialogButtonStyle](#dialogbuttonstyle10) | No | Style of the button.<br>Default value: **DialogButtonStyle.DEFAULT** | 87| value | [ResourceStr](ts-types.md#resourcestr) | Yes | Text of the button. If the value is null, the button is not displayed. | 88| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the button. | 89| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the button. | 90| action | () => void | Yes | Callback when the button is selected. | 91 92## DialogButtonDirection<sup>10+</sup> 93| Name | Description | 94| -------------------------- | --------- | 95| AUTO | Buttons are laid out horizontally when there are two or fewer buttons and vertically otherwise.| 96| HORIZONTAL | Buttons are laid out horizontally.| 97| VERTICAL | Buttons are laid out vertically.| 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## DialogAlignment 118 119| Name | Description | 120| ------------------------ | ------- | 121| Top | Vertical top alignment.| 122| Center | Vertical center alignment.| 123| Bottom | Vertical bottom alignment.| 124| Default | Default alignment. | 125| TopStart<sup>8+</sup> | Top left alignment. | 126| TopEnd<sup>8+</sup> | Top right alignment. | 127| CenterStart<sup>8+</sup> | Center left alignment. | 128| CenterEnd<sup>8+</sup> | Center right alignment. | 129| BottomStart<sup>8+</sup> | Bottom left alignment. | 130| BottomEnd<sup>8+</sup> | Bottom right alignment. | 131 132## Rectangle<sup>10+</sup> 133 134The **Rectangle** type is used to represent a mask area of a dialog box. 135 136| Name | Type | Mandatory| Description | 137|--------|------------------------------|----|-----------------------------------| 138| 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**| 139| 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**| 140| width | [Length](ts-types.md#length) | No | Width of the mask area of the dialog box.<br>Default value: **'100%'** | 141| height | [Length](ts-types.md#length) | No | Height of the mask area of the dialog box.<br>Default value: **'100%'** | 142 143> **NOTE** 144> 145> **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. 146> 147> **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. 148> 149> The percentage is calculated based on the width and height of the window. 150 151## DialogButtonStyle<sup>10+</sup> 152 153| Name | Description | 154| --------- | --------------------------------- | 155| DEFAULT | Blue text on white background (black background under the dark theme).| 156| HIGHLIGHT | White text on blue background. | 157 158## Example 159 160```ts 161// xxx.ets 162@Entry 163@Component 164struct AlertDialogExample { 165 build() { 166 Column({ space: 5 }) { 167 Button('one button dialog') 168 .onClick(() => { 169 AlertDialog.show( 170 { 171 title: 'title', 172 message: 'text', 173 autoCancel: true, 174 alignment: DialogAlignment.Bottom, 175 offset: { dx: 0, dy: -20 }, 176 gridCount: 3, 177 confirm: { 178 value: 'button', 179 action: () => { 180 console.info('Button-clicking callback') 181 } 182 }, 183 cancel: () => { 184 console.info('Closed callbacks') 185 } 186 } 187 ) 188 }) 189 .backgroundColor(0x317aff) 190 Button('two button dialog') 191 .onClick(() => { 192 AlertDialog.show( 193 { 194 title: 'title', 195 subtitle: 'subtitle', 196 message: 'text', 197 autoCancel: true, 198 alignment: DialogAlignment.Bottom, 199 gridCount: 4, 200 offset: { dx: 0, dy: -20 }, 201 primaryButton: { 202 value: 'cancel', 203 action: () => { 204 console.info('Callback when the first button is clicked') 205 } 206 }, 207 secondaryButton: { 208 enabled: true, 209 defaultFocus: true, 210 style: DialogButtonStyle.HIGHLIGHT, 211 value: 'ok', 212 action: () => { 213 console.info('Callback when the second button is clicked') 214 } 215 }, 216 cancel: () => { 217 console.info('Closed callbacks') 218 } 219 } 220 ) 221 }).backgroundColor(0x317aff) 222 Button('three button dialog') 223 .onClick(() => { 224 AlertDialog.show( 225 { 226 title: 'title', 227 subtitle: 'subtitle', 228 message: 'text', 229 autoCancel: true, 230 alignment: DialogAlignment.Bottom, 231 gridCount: 4, 232 offset: { dx: 0, dy: -20 }, 233 buttonDirection: DialogButtonDirection.HORIZONTAL, 234 buttons: [ 235 { 236 value: 'Button', 237 action: () => { 238 console.info('Callback when button1 is clicked') 239 } 240 }, 241 { 242 value: 'Button', 243 action: () => { 244 console.info('Callback when button2 is clicked') 245 } 246 }, 247 { 248 value: 'Button', 249 enabled: true, 250 defaultFocus: true, 251 style: DialogButtonStyle.HIGHLIGHT, 252 action: () => { 253 console.info('Callback when button3 is clicked') 254 } 255 }, 256 ], 257 cancel: () => { 258 console.info('Closed callbacks') 259 } 260 } 261 ) 262 }).backgroundColor(0x317aff) 263 }.width('100%').margin({ top: 5 }) 264 } 265} 266``` 267 268 269
