1# InterstitialDialogAction 2 3The **InterstitialDialogAction** component is a dialog box used in atomic services to temporarily display information that requires user attention or actions to be taken while maintaining the current context. Users can trigger corresponding actions by clicking different areas of the dialog box. 4 5> **NOTE** 6> 7> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11``` 12import { InterstitialDialogAction, IconStyle, TitlePosition, BottomOffset } from '@kit.ArkUI'; 13``` 14 15## Child Components 16 17Not supported 18 19## Attributes 20 21The [universal attributes](ts-component-general-attributes.md) are not supported. 22 23## InterstitialDialogAction 24 25Implements an **InterstitialDialogAction** instance. For details, see [Example](#example). 26 27### constructor 28 29constructor(dialogOptions: DialogOptions) 30 31A constructor used to create an **InterstitialDialogAction** instance. 32 33**Atomic service API**: This API can be used in atomic services since API version 12. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37**Parameters** 38 39| Name| Type| Mandatory| Description| 40| - | - | - | - | 41| dialogOptions | [DialogOptions](#dialogoptions)| Yes| Attributes specific to the dialog box.| 42 43### openDialog 44 45openDialog(): void 46 47Opens the dialog box. 48 49**Atomic service API**: This API can be used in atomic services since API version 12. 50 51**System capability**: SystemCapability.ArkUI.ArkUI.Full 52 53### closeDialog 54 55closeDialog(): void 56 57Closes the dialog box. 58 59**Atomic service API**: This API can be used in atomic services since API version 12. 60 61**System capability**: SystemCapability.ArkUI.ArkUI.Full 62 63## DialogOptions 64 65**Atomic service API**: This API can be used in atomic services since API version 12. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69Defines the attributes specific to the dialog box and custom click actions for the user. 70 71| Name| Type| Mandatory| Description| 72| - | - | - | - | 73| uiContext | [UIContext](../js-apis-arkui-UIContext.md#uicontext) | Yes| UI context.| 74| bottomOffsetType | [BottomOffset](#bottomoffset) | No| Bottom offset type of the dialog box. Default value: **[BottomOffset](#bottomoffset).OFFSET_FOR_BAR**.| 75| title | [ResourceStr](ts-types.md#resourcestr) | No| Title of the dialog box. The default value is an empty string.| 76| subtitle | [ResourceStr](ts-types.md#resourcestr) | No| Subtitle of the dialog box. The default value is an empty string.| 77| titleColor | [ResourceStr](ts-types.md#resourcestr) \| [Color](ts-appendix-enums.md#color) | No| Font color of the dialog box title. <br>Default value: **$r('sys.color.ohos_id_color_text_primary_contrary')**.| 78| subtitleColor | [ResourceStr](ts-types.md#resourcestr) \| [Color](ts-appendix-enums.md#color) | No| Font color of the dialog box subtitle. <br>Default value: **$r('sys.color.ohos_id_color_text_secondary_contrary')**.| 79| backgroundImage | [Resource](ts-types.md#resource) | No| Background image of the dialog box. The default background color is a solid color background with the color value **#EBEEF5**.| 80| foregroundImage | [Resource](ts-types.md#resource) | No| Foreground image of the dialog box. The default value is empty, meaning no foreground image is displayed.| 81| iconStyle | [IconStyle](#iconstyle) | No| Style of the close button icon (light or dark).<br>Default value: **[IconStyle](#iconstyle).Light**| 82| titlePosition | [TitlePosition](#titleposition) | No| Vertical position of the title relative to the subtitle in the dialog box.<br>Default value: **[TitlePosition](#titleposition).Top**| 83| onDialogClick | Callback\<void\> | No| Custom action triggered by clicking anywhere on the dialog box. The default value is to close the dialog box only.| 84| onDialogClose | Callback\<void\> | No| Custom action triggered by clicking the close button. The default value is to close the dialog box only.| 85 86## IconStyle 87 88**Atomic service API**: This API can be used in atomic services since API version 12. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92Sets the color style of the close button. By default, the close button is set to light color. 93 94| Name| Value| Description| 95| - | - | - | 96| DARK | 0 | The close button is in dark color.| 97| LIGHT | 1 | The close button is in light color.<br>Default value.| 98 99## TitlePosition 100 101**Atomic service API**: This API can be used in atomic services since API version 12. 102 103**System capability**: SystemCapability.ArkUI.ArkUI.Full 104 105Defines the vertical position of the title relative to the subtitle in the dialog box. By default, the title is above the subtitle. 106 107| Name| Value| Description| 108| - | - | - | 109| TOP | 0 | The title is above the subtitle.<br>Default value.| 110| BOTTOM | 1 | The title is below the subtitle.| 111 112## BottomOffset 113 114**Atomic service API**: This API can be used in atomic services since API version 12. 115 116**System capability**: SystemCapability.ArkUI.ArkUI.Full 117 118Defines the distance between the popup and the bottom in different scenario modes, based on the presence or absence of a menu bar, with the default being the distance when there is no menu bar. 119 120| Name| Value| Description| 121| - | - | - | 122| OFFSET_FOR_BAR | 0 | Distance from the bottom of the window when there is a menu bar.<br>Default value. It sets the dialog box 88 vp away from the bottom of the window.| 123| OFFSET_FOR_NONE | 1 | Distance from the bottom of the window when there is no menu bar.<br>It sets the dialog box 44 vp away from the bottom of the window.| 124 125## Events 126The [universal events](ts-component-general-events.md) are not supported. 127 128## Example 129 130### Example 1 131 132In this example, 133color values are assigned to the title and subtitle using two different parameter types; the close button is set to dark color; the title is set to above the subtitle; and the distance type is set to the distance used when there is no menu bar. 134 135<!--code_no_check--> 136```ts 137// ../entryability/EntryAbility 138import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 139import { hilog } from '@kit.PerformanceAnalysisKit'; 140import { window } from '@kit.ArkUI'; 141import { BusinessError } from '@kit.BasicServicesKit'; 142 143let dialogUIContext: UIContext | null = null; 144 145export function getDialogUIContext(): UIContext | null { 146 return dialogUIContext; 147} 148 149export default class EntryAbility extends UIAbility { 150 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 151 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 152 } 153 154 onDestroy(): void { 155 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 156 } 157 158 onWindowStageCreate(windowStage: window.WindowStage): void { 159 // Main window is created, set main page for this ability 160 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 161 162 windowStage.loadContent('pages/Index', (err) => { 163 if (err.code) { 164 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 165 return; 166 } 167 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 168 }); 169 170 let windowClass: window.Window | undefined = undefined; 171 windowStage.getMainWindow((err: BusinessError, data) => { 172 let errCode: number = err.code; 173 if (errCode) { 174 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 175 return; 176 } 177 windowClass = data; 178 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 179 dialogUIContext = windowClass.getUIContext(); 180 }) 181 182 // Obtain the main window. 183 windowStage.getMainWindow((err, data) => { 184 if (err.code) { 185 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 186 return; 187 } 188 windowClass = data; 189 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 190 // Set the window to full screen. 191 windowClass.setWindowLayoutFullScreen(false) 192 }) 193 } 194 195 onWindowStageDestroy(): void { 196 // Main window is destroyed, release UI related resources 197 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); 198 } 199 200 onForeground(): void { 201 // Ability has brought to foreground 202 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground'); 203 } 204 205 onBackground(): void { 206 // Ability has back to background 207 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground'); 208 } 209} 210``` 211<!--code_no_check--> 212```ts 213// Index.ets 214import { getDialogUIContext } from '../entryability/EntryAbility'; 215import { UIContext, InterstitialDialogAction, IconStyle, TitlePosition, BottomOffset } from '@kit.ArkUI'; 216 217@Entry 218@Component 219struct Index { 220 build() { 221 Row() { 222 Column() { 223 Text("show dialog") 224 .fontSize(50) 225 .fontWeight(FontWeight.Bold) 226 .onClick(() => { 227 let ctx: UIContext | null = getDialogUIContext(); 228 let interstitialDialogAction: InterstitialDialogAction = new InterstitialDialogAction({ 229 uiContext: ctx as UIContext, 230 title: "Title", 231 subtitle: "Subtitle", 232 titleColor: 'rgb(255, 192, 0)', 233 subtitleColor: Color.Red, 234 backgroundImage: $r('app.media.testBackgroundImg'), 235 foregroundImage: $r('app.media.testForegroundImg'), 236 iconStyle: IconStyle.DARK, 237 titlePosition: TitlePosition.TOP, 238 bottomOffsetType: BottomOffset.OFFSET_FOR_NONE, 239 onDialogClick: () => { console.log('outer dialog click action') }, 240 onDialogClose: () => { console.log('outer close action') } 241 }); 242 interstitialDialogAction.openDialog(); 243 }) 244 } 245 .width('100%') 246 } 247 .height('100%') 248 .backgroundColor('rgba(0, 0, 0, 0.1)') 249 } 250} 251``` 252 253 254 255### Example 2 256 257In this example, color values are assigned to the title and subtitle using two different parameter types; the close button is set to light color; the title is set to below the subtitle; and the distance type is set to the distance used when there is a menu bar. 258 259<!--code_no_check--> 260```ts 261// ../entryability/EntryAbility 262import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 263import { hilog } from '@kit.PerformanceAnalysisKit'; 264import { window } from '@kit.ArkUI'; 265import { BusinessError } from '@kit.BasicServicesKit'; 266 267let dialogUIContext: UIContext | null = null; 268 269export function getDialogUIContext(): UIContext | null { 270 if (getDialogUIContext === null) { 271 hilog.info(0x0000, 'testTag', '%{public}s', 'getDialogUIContext is null'); 272 } 273 return dialogUIContext; 274} 275 276export default class EntryAbility extends UIAbility { 277 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 278 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 279 } 280 281 onDestroy(): void { 282 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 283 } 284 285 onWindowStageCreate(windowStage: window.WindowStage): void { 286 // Main window is created, set main page for this ability 287 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 288 289 windowStage.loadContent('pages/Index', (err) => { 290 if (err.code) { 291 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 292 return; 293 } 294 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 295 }); 296 297 let windowClass: window.Window | undefined = undefined; 298 windowStage.getMainWindow((err: BusinessError, data) => { 299 let errCode: number = err.code; 300 if (errCode) { 301 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 302 return; 303 } 304 windowClass = data; 305 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 306 dialogUIContext = windowClass.getUIContext(); 307 }) 308 309 // Obtain the main window. 310 windowStage.getMainWindow((err, data) => { 311 if (err.code) { 312 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 313 return; 314 } 315 windowClass = data; 316 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 317 // Set the window to full screen. 318 windowClass.setWindowLayoutFullScreen(false) 319 }) 320 } 321 322 onWindowStageDestroy(): void { 323 // Main window is destroyed, release UI related resources 324 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); 325 } 326 327 onForeground(): void { 328 // Ability has brought to foreground 329 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground'); 330 } 331 332 onBackground(): void { 333 // Ability has back to background 334 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground'); 335 } 336} 337``` 338<!--code_no_check--> 339```ts 340// Index.ets 341import { getDialogUIContext } from '../entryability/EntryAbility'; 342import { UIContext, InterstitialDialogAction, IconStyle, TitlePosition, BottomOffset } from '@kit.ArkUI'; 343 344@Entry 345@Component 346struct Index { 347 build() { 348 Row() { 349 Column() { 350 Text("show dialog") 351 .fontSize(50) 352 .fontWeight(FontWeight.Bold) 353 .onClick(() => { 354 let ctx: UIContext | null = getDialogUIContext(); 355 let interstitialDialogAction: InterstitialDialogAction = new InterstitialDialogAction({ 356 uiContext: ctx as UIContext, 357 title: "Title", 358 subtitle: "Subtitle", 359 titleColor: 'rgb(255, 192, 0)', 360 subtitleColor: Color.Red, 361 backgroundImage: $r('app.media.testBackgroundImg'), 362 foregroundImage: $r('app.media.testForegroundImg'), 363 iconStyle: IconStyle.LIGHT, 364 titlePosition: TitlePosition.BOTTOM, 365 bottomOffsetType: BottomOffset.OFFSET_FOR_BAR, 366 onDialogClick: () => { console.log('outer dialog click action') }, 367 onDialogClose: () => { console.log('outer close action') } 368 }); 369 interstitialDialogAction.openDialog(); 370 }) 371 } 372 .width('100%') 373 } 374 .height('100%') 375 .backgroundColor('rgba(0, 0, 0, 0.1)') 376 } 377} 378``` 379 380 381
