1# @ohos.atomicservice.InterstitialDialogAction (Dialog Box) 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 25InterstitialDialogAction { 26 uiContext: UIContext, 27 contentNode: ComponentContent\<object\>, 28 dialogParam: DialogParams, 29 bottomOffsetType?: BottomOffset, 30 constructor: (dialogOptions: DialogOptions), 31 openDialog(): Callback\<void\>, 32 closeDialog(): Callback\<void\> 33} 34 35**Atomic service API**: This API can be used in atomic services since API version 12. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39**Parameters** 40 41| Name | Type | Mandatory | Description | 42| - | - | - | - | 43| uiContext | [UIContext](../js-apis-arkui-UIContext.md#uicontext) | Yes | UI context. | 44| contentNode | [ComponentContent](../js-apis-arkui-ComponentContent.md)\<object\> | Yes | Component node object. | 45| dialogParam | [DialogParams](#dialogparams) | Yes | Parameters of the dialog box. | 46| bottomOffsetType | [BottomOffset](#bottomoffset) | No | Type of distance with the bottom of the window<br>Default value: **[BottomOffset](#bottomoffset).OFFSET_FOR_BAR** | 47| constructor | (dialogOptions: [DialogOptions](#dialogoptions)) | Yes | Constructor used to create an **InterstitialDialogAction** instance. | 48| openDialog | Callback\<void\> | No | Opens the dialog box. | 49| closeDialog | Callback\<void\> | Yes | Closes the dialog box. | 50 51## DialogParams 52 53**Atomic service API**: This API can be used in atomic services since API version 12. 54 55**System capability**: SystemCapability.ArkUI.ArkUI.Full 56 57Defines the unique attributes of the dialog box and the default close action function. 58 59| Name | Type | Mandatory | Description | 60| - | - | - | - | 61| dialogOptions | [DialogOptions](#dialogoptions) | Yes | Unique attributes of the dialog box. | 62| defaultCloseAction | Callback\<void\> | Yes | Default close action executed when the dialog box or the close button is clicked. | 63 64## DialogOptions 65 66**Atomic service API**: This API can be used in atomic services since API version 12. 67 68**System capability**: SystemCapability.ArkUI.ArkUI.Full 69 70Defines the unique attributes of the dialog box and custom click actions for the user. 71 72| Name| Type | Mandatory | Description | 73| - | - | - | - | 74| uiContext | [UIContext](../js-apis-arkui-UIContext.md#uicontext) | Yes | UI context. | 75| title | [ResourceColor](ts-types.md#resourcecolor) | No | Title of the dialog box. | 76| subtitle | [ResourceColor](ts-types.md#resourcecolor) | No | Subtitle of the dialog box. | 77| titleColor | [ResourceColor](ts-types.md#resourcecolor) \| [Color](ts-appendix-enums.md#color) | No | Font color of the dialog box title. | 78| subtitleColor | [ResourceColor](ts-types.md#resourcecolor) \| [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 in relation 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 in relation 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 { getMyUiContext } 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 = getMyUiContext(); 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 return dialogUIContext; 269} 270 271export default class EntryAbility extends UIAbility { 272 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 273 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 274 } 275 276 onDestroy(): void { 277 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 278 } 279 280 onWindowStageCreate(windowStage: window.WindowStage): void { 281 // Main window is created, set main page for this ability 282 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 283 284 windowStage.loadContent('pages/Index', (err) => { 285 if (err.code) { 286 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 287 return; 288 } 289 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 290 }); 291 292 let windowClass: window.Window | undefined = undefined; 293 windowStage.getMainWindow((err: BusinessError, data) => { 294 let errCode: number = err.code; 295 if (errCode) { 296 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 297 return; 298 } 299 windowClass = data; 300 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 301 dialogUIContext = windowClass.getUIContext(); 302 }) 303 304 // Obtain the main window. 305 windowStage.getMainWindow((err, data) => { 306 if (err.code) { 307 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 308 return; 309 } 310 windowClass = data; 311 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 312 // Set the window to full screen. 313 windowClass.setWindowLayoutFullScreen(false) 314 }) 315 } 316 317 onWindowStageDestroy(): void { 318 // Main window is destroyed, release UI related resources 319 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy'); 320 } 321 322 onForeground(): void { 323 // Ability has brought to foreground 324 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground'); 325 } 326 327 onBackground(): void { 328 // Ability has back to background 329 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground'); 330 } 331} 332``` 333 334```ts 335// Index.ets 336import { getMyUiContext } from '../entryability/EntryAbility'; 337import { UIContext, InterstitialDialogAction, IconStyle, TitlePosition, BottomOffset } from '@kit.ArkUI'; 338 339@Entry 340@Component 341struct Index { 342 build() { 343 Row() { 344 Column() { 345 Text("show dialog") 346 .fontSize(50) 347 .fontWeight(FontWeight.Bold) 348 .onClick(() => { 349 let ctx: UIContext | null = getMyUiContext(); 350 let interstitialDialogAction: InterstitialDialogAction = new InterstitialDialogAction({ 351 uiContext: ctx as UIContext, 352 title: "Title", 353 subtitle: "Subtitle", 354 titleColor: 'rgb(255, 192, 0)', 355 subtitleColor: Color.Red, 356 backgroundImage: $r('app.media.testBackgroundImg'), 357 foregroundImage: $r('app.media.testForegroundImg'), 358 iconStyle: IconStyle.LIGHT, 359 titlePosition: TitlePosition.BOTTOM, 360 bottomOffsetType: BottomOffset.OFFSET_FOR_BAR, 361 onDialogClick: () => { console.log('outer dialog click action') }, 362 onDialogClose: () => { console.log('outer close action') } 363 }); 364 interstitialDialogAction.openDialog(); 365 }) 366 } 367 .width('100%') 368 } 369 .height('100%') 370 .backgroundColor('rgba(0, 0, 0, 0.1)') 371 } 372} 373``` 374 375 376
