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-universal-attributes-size.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) | Yes| Bottom offset type of the dialog box.| 75| title | [ResourceStr](ts-types.md#resourcestr) | No| Title of the dialog box.| 76| subtitle | [ResourceStr](ts-types.md#resourcestr) | No| Subtitle of the dialog box.| 77| titleColor | [ResourceStr](ts-types.md#resourcestr) \| [Color](ts-appendix-enums.md#color) | No| Font color of the dialog box title.| 78| subtitleColor | [ResourceStr](ts-types.md#resourcestr) \| [Color](ts-appendix-enums.md#color) | No| Font color of the dialog box subtitle.| 79| backgroundImage | [Resource](ts-types.md#resource) | No| Background image of the dialog box.| 80| foregroundImage | [Resource](ts-types.md#resource) | No| Foreground image of the dialog box.| 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.| 84| onDialogClose | Callback\<void\> | No| Custom action triggered by clicking the close button.| 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-universal-events-click.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```ts 136// ../entryability/EntryAbility 137import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 138import { hilog } from '@kit.PerformanceAnalysisKit'; 139import { window } from '@kit.ArkUI'; 140import { BusinessError } from '@kit.BasicServicesKit'; 141 142let dialogUIContext: UIContext | null = null; 143 144export function getDialogUIContext(): UIContext | null { 145 return dialogUIContext; 146} 147 148export default class EntryAbility extends UIAbility { 149 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 150 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 151 } 152 153 onDestroy(): void { 154 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 155 } 156 157 onWindowStageCreate(windowStage: window.WindowStage): void { 158 // Main window is created, set main page for this ability 159 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 160 161 windowStage.loadContent('pages/Index', (err) => { 162 if (err.code) { 163 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 164 return; 165 } 166 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 167 }); 168 169 let windowClass: window.Window | undefined = undefined; 170 windowStage.getMainWindow((err: BusinessError, data) => { 171 let errCode: number = err.code; 172 if (errCode) { 173 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 174 return; 175 } 176 windowClass = data; 177 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 178 dialogUIContext = windowClass.getUIContext(); 179 }) 180 181 // Obtain the main window. 182 windowStage.getMainWindow((err, data) => { 183 if (err.code) { 184 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 185 return; 186 } 187 windowClass = data; 188 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 189 // Set the window to full screen. 190 windowClass.setWindowLayoutFullScreen(false) 191 }) 192 } 193 194 onWindowStageDestroy(): void { 195 // Main window is destroyed, release UI related resources 196 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); 197 } 198 199 onForeground(): void { 200 // Ability has brought to foreground 201 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground'); 202 } 203 204 onBackground(): void { 205 // Ability has back to background 206 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground'); 207 } 208} 209``` 210 211```ts 212// Index.ets 213import { getDialogUIContext } from '../entryability/EntryAbility'; 214import { UIContext, InterstitialDialogAction, IconStyle, TitlePosition, BottomOffset } from '@kit.ArkUI'; 215 216@Entry 217@Component 218struct Index { 219 build() { 220 Row() { 221 Column() { 222 Text("show dialog") 223 .fontSize(50) 224 .fontWeight(FontWeight.Bold) 225 .onClick(() => { 226 let ctx: UIContext | null = getDialogUIContext(); 227 let interstitialDialogAction: InterstitialDialogAction = new InterstitialDialogAction({ 228 uiContext: ctx as UIContext, 229 title: "Title", 230 subtitle: "Subtitle", 231 titleColor: 'rgb(255, 192, 0)', 232 subtitleColor: Color.Red, 233 backgroundImage: $r('app.media.testBackgroundImg'), 234 foregroundImage: $r('app.media.testForegroundImg'), 235 iconStyle: IconStyle.DARK, 236 titlePosition: TitlePosition.TOP, 237 bottomOffsetType: BottomOffset.OFFSET_FOR_NONE, 238 onDialogClick: () => { console.log('outer dialog click action') }, 239 onDialogClose: () => { console.log('outer close action') } 240 }); 241 interstitialDialogAction.openDialog(); 242 }) 243 } 244 .width('100%') 245 } 246 .height('100%') 247 .backgroundColor('rgba(0, 0, 0, 0.1)') 248 } 249} 250``` 251 252 253 254### Example 2 255 256In 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. 257 258```ts 259// ../entryability/EntryAbility 260import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 261import { hilog } from '@kit.PerformanceAnalysisKit'; 262import { window } from '@kit.ArkUI'; 263import { BusinessError } from '@kit.BasicServicesKit'; 264 265let dialogUIContext: UIContext | null = null; 266 267export function getDialogUIContext(): UIContext | null { 268 if (getDialogUIContext === null) { 269 hilog.info(0x0000, 'testTag', '%{public}s', 'getDialogUIContext is null'); 270 } 271 return dialogUIContext; 272} 273 274export default class EntryAbility extends UIAbility { 275 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 276 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 277 } 278 279 onDestroy(): void { 280 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 281 } 282 283 onWindowStageCreate(windowStage: window.WindowStage): void { 284 // Main window is created, set main page for this ability 285 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 286 287 windowStage.loadContent('pages/Index', (err) => { 288 if (err.code) { 289 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 290 return; 291 } 292 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 293 }); 294 295 let windowClass: window.Window | undefined = undefined; 296 windowStage.getMainWindow((err: BusinessError, data) => { 297 let errCode: number = err.code; 298 if (errCode) { 299 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 300 return; 301 } 302 windowClass = data; 303 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 304 dialogUIContext = windowClass.getUIContext(); 305 }) 306 307 // Obtain the main window. 308 windowStage.getMainWindow((err, data) => { 309 if (err.code) { 310 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 311 return; 312 } 313 windowClass = data; 314 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 315 // Set the window to full screen. 316 windowClass.setWindowLayoutFullScreen(false) 317 }) 318 } 319 320 onWindowStageDestroy(): void { 321 // Main window is destroyed, release UI related resources 322 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); 323 } 324 325 onForeground(): void { 326 // Ability has brought to foreground 327 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground'); 328 } 329 330 onBackground(): void { 331 // Ability has back to background 332 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground'); 333 } 334} 335``` 336 337```ts 338// Index.ets 339import { getDialogUIContext } from '../entryability/EntryAbility'; 340import { UIContext, InterstitialDialogAction, IconStyle, TitlePosition, BottomOffset } from '@kit.ArkUI'; 341 342@Entry 343@Component 344struct Index { 345 build() { 346 Row() { 347 Column() { 348 Text("show dialog") 349 .fontSize(50) 350 .fontWeight(FontWeight.Bold) 351 .onClick(() => { 352 let ctx: UIContext | null = getDialogUIContext(); 353 let interstitialDialogAction: InterstitialDialogAction = new InterstitialDialogAction({ 354 uiContext: ctx as UIContext, 355 title: "Title", 356 subtitle: "Subtitle", 357 titleColor: 'rgb(255, 192, 0)', 358 subtitleColor: Color.Red, 359 backgroundImage: $r('app.media.testBackgroundImg'), 360 foregroundImage: $r('app.media.testForegroundImg'), 361 iconStyle: IconStyle.LIGHT, 362 titlePosition: TitlePosition.BOTTOM, 363 bottomOffsetType: BottomOffset.OFFSET_FOR_BAR, 364 onDialogClick: () => { console.log('outer dialog click action') }, 365 onDialogClose: () => { console.log('outer close action') } 366 }); 367 interstitialDialogAction.openDialog(); 368 }) 369 } 370 .width('100%') 371 } 372 .height('100%') 373 .backgroundColor('rgba(0, 0, 0, 0.1)') 374 } 375} 376``` 377 378 379
