1# Calendar Picker Dialog Box (CalendarPickerDialog) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @luoying_ace_admin--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9A calendar picker dialog box is a dialog box that allows users to select a date from a calendar picker. 10 11> **NOTE** 12> 13> This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 14> 15> 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](../../../ui/arkts-global-interface.md). For details, see [UIContext](../arkts-apis-uicontext-uicontext.md). 16 17## CalendarPickerDialog 18 19### show 20 21static show(options?: CalendarDialogOptions): void 22 23Shows a calendar picker dialog box. 24 25**Atomic service API**: This API can be used in atomic services since API version 11. 26 27**System capability**: SystemCapability.ArkUI.ArkUI.Full 28 29**Device behavior differences**: On wearables, calling this API results in a runtime exception indicating that the API is undefined. On other devices, the API works correctly. 30 31**Parameters** 32 33| Name | Type | Mandatory| Description | 34| ------- | ------------------------------------------------------- | ---- | -------------------------- | 35| options | [CalendarDialogOptions](#calendardialogoptions) | No | Parameters of the calendar picker dialog box.| 36 37## CalendarDialogOptions 38 39Defines the configuration options of the calendar picker dialog box. 40 41Inherits from [CalendarOptions](ts-basic-components-calendarpicker.md#calendaroptions). 42 43**System capability**: SystemCapability.ArkUI.ArkUI.Full 44 45| Name | Type | Read-Only| Optional| Description | 46| ---------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 47| onAccept | [Callback](ts-types.md#callback12)\<Date> | No | Yes | Triggered when the OK button in the dialog box is clicked.<br>The callback parameter represents the selected date value.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 48| onCancel | [VoidCallback](ts-types.md#voidcallback12) | No | Yes | Triggered when the Cancel button in the dialog box is clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 49| onChange | [Callback](ts-types.md#callback12)\<Date> | No | Yes | Triggered when the selection in the picker changes the selected date.<br>The callback parameter represents the selected date value.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 50| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Yes| Backplane color of the dialog box.<br>Default value: **Color.Transparent**<br>**NOTE**<br>When **backgroundColor** is set to a non-transparent color, **backgroundBlurStyle** must be set to **BlurStyle.NONE**; otherwise, the color display may not meet the expected effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 51| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Yes| Background blur style of the dialog box.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**NOTE**<br>Setting this parameter to **BlurStyle.NONE** disables the background blur. When **backgroundBlurStyle** is set to a value other than **NONE**, do not set **backgroundColor**. If you do, the color display may not produce the expected visual effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 52| backgroundBlurStyleOptions<sup>19+</sup> | [BackgroundBlurStyleOptions](ts-universal-attributes-background.md#backgroundblurstyleoptions10) | No| Yes| Options for customizing the background blur style.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 53| backgroundEffect<sup>19+</sup> | [BackgroundEffectOptions](ts-universal-attributes-background.md#backgroundeffectoptions11) | No| Yes| Options for customizing the background effect.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 54| acceptButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](ts-picker-common.md#pickerdialogbuttonstyle12) | No| Yes| Style of the accept button.<br>**NOTE**<br>In the **acceptButtonStyle** and **cancelButtonStyle** configurations, only one **primary** field can be set to **true** at most. If both the **primary** fields are set to **true**, neither will take effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 55| cancelButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](ts-picker-common.md#pickerdialogbuttonstyle12) | No| Yes| Style of the cancel button.<br>**NOTE**<br>In the **acceptButtonStyle** and **cancelButtonStyle** configurations, only one **primary** field can be set to **true** at most. If both the **primary** fields are set to **true**, neither will take effect.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| onDidAppear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| Yes| Event callback when the dialog box appears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onDidAppear**. The settings take effect next time the dialog box appears.<br>3. If the user dismisses the dialog box immediately after it appears, **onWillDisappear** is invoked before **onDidAppear**.<br>4. If the dialog box is dismissed before its entrance animation is finished, this callback is not invoked.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 57| onDidDisappear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| Yes| Event callback when the dialog box disappears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| onWillAppear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| Yes| Event callback when the dialog box is about to appear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>2. You can set the callback event for changing the dialog box display effect in **onWillAppear**. The settings take effect next time the dialog box appears.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 59| onWillDisappear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| Yes| Event callback when the dialog box is about to disappear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onAccept/onCancel/onChange) > onWillDisappear > onDidDisappear.<br>2. If the user closes the dialog box immediately after it appears, **onWillDisappear** is invoked before **onDidAppear**.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 60| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | Yes | Shadow of the dialog box.<br> Default value on 2-in-1 devices: **ShadowStyle.OUTER_FLOATING_MD** when the dialog box is focused and **ShadowStyle.OUTER_FLOATING_SM** otherwise<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 61| enableHoverMode<sup>14+</sup> | boolean | No | Yes | Whether to respond when the device is in semi-folded mode.<br>Default value: **false**. The value **true** means to respond when the device is in semi-folded mode, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 62| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](ts-appendix-enums.md#hovermodeareatype14) | No | Yes | Display area of the dialog box when the device is in semi-folded mode.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 63| markToday<sup>19+</sup> | boolean | No | Yes | Whether to highlight the current system date.<br>Default value: **false**. The value **true** means to highlight the current system date, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 19.| 64 65> **NOTE** 66> 67> When the application window is resized, the width of the dialog box is continuously compressed. If the window width is reduced below a certain threshold, the content of the dialog box may not be fully visible. To ensure that the content of the **CalendarPickerDialog** component is fully displayed, the minimum window width required is 386 vp. 68 69## Example 70 71### Example 1: Setting the Background 72 73This example demonstrates how to set the calendar picker dialog box's background using **backgroundColor**, **backgroundBlurStyle**, and **shadow** in [CalendarDialogOptions](#calendardialogoptions). 74 75```ts 76// xxx.ets 77@Entry 78@Component 79struct CalendarPickerDialogExample { 80 private selectedDate: Date = new Date('2024-04-23'); 81 82 build() { 83 Column() { 84 Button("Show CalendarPicker Dialog") 85 .margin(20) 86 .onClick(() => { 87 console.info("CalendarDialog.show"); 88 CalendarPickerDialog.show({ 89 selected: this.selectedDate, 90 backgroundColor: Color.Gray, 91 backgroundBlurStyle: BlurStyle.NONE, 92 shadow: ShadowStyle.OUTER_FLOATING_SM, 93 onAccept: (value) => { 94 this.selectedDate = value; 95 console.info("calendar onAccept:" + JSON.stringify(value)); 96 }, 97 onCancel: () => { 98 console.info("calendar onCancel"); 99 }, 100 onChange: (value) => { 101 console.info("calendar onChange:" + JSON.stringify(value)); 102 }, 103 onDidAppear: () => { 104 console.info("calendar onDidAppear"); 105 }, 106 onDidDisappear: () => { 107 console.info("calendar onDidDisappear"); 108 }, 109 onWillAppear: () => { 110 console.info("calendar onWillAppear"); 111 }, 112 onWillDisappear: () => { 113 console.info("calendar onWillDisappear"); 114 } 115 }); 116 }) 117 }.width('100%') 118 } 119} 120``` 121 122 123 124### Example 2: Customizing the Button Style 125 126This example shows how to customize the calendar picker dialog box's buttons by configuring **acceptButtonStyle** and **cancelButtonStyle** in [CalendarDialogOptions](#calendardialogoptions). 127 128```ts 129// xxx.ets 130@Entry 131@Component 132struct CalendarPickerDialogExample { 133 private selectedDate: Date = new Date(); 134 135 build() { 136 Column() { 137 Button("Show CalendarPicker Dialog") 138 .margin(20) 139 .onClick(() => { 140 console.info("CalendarDialog.show"); 141 CalendarPickerDialog.show({ 142 selected: this.selectedDate, 143 acceptButtonStyle: { 144 type: ButtonType.Normal, 145 style: ButtonStyleMode.NORMAL, 146 role: ButtonRole.NORMAL, 147 fontColor: 'rgb(81, 81, 216)', 148 fontSize: '26fp', 149 fontWeight: FontWeight.Bolder, 150 fontStyle: FontStyle.Normal, 151 fontFamily: 'sans-serif', 152 backgroundColor: '#A6ACAF', 153 borderRadius: 20 154 }, 155 cancelButtonStyle: { 156 type: ButtonType.Normal, 157 style: ButtonStyleMode.NORMAL, 158 role: ButtonRole.NORMAL, 159 fontColor: Color.Blue, 160 fontSize: '16fp', 161 fontWeight: FontWeight.Normal, 162 fontStyle: FontStyle.Italic, 163 fontFamily: 'sans-serif', 164 backgroundColor: '#50182431', 165 borderRadius: 10 166 }, 167 onAccept: (value) => { 168 this.selectedDate = value; 169 console.info("calendar onAccept:" + JSON.stringify(value)); 170 } 171 }); 172 }) 173 }.width('100%') 174 } 175} 176``` 177 178 179 180### Example 3: Configuring a Dialog Box in the Hover State 181 182This example demonstrates how to set the layout area of a dialog box when the device is in semi-folded mode. 183 184```ts 185@Entry 186@Component 187struct CalendarPickerDialogExample { 188 private selectedDate: Date = new Date('2024-04-23'); 189 190 build() { 191 Column() { 192 Button("Show CalendarPicker Dialog") 193 .margin(20) 194 .onClick(() => { 195 console.info("CalendarDialog.show"); 196 CalendarPickerDialog.show({ 197 selected: this.selectedDate, 198 onAccept: (value) => { 199 console.info("calendar onAccept:" + JSON.stringify(value)); 200 }, 201 onCancel: () => { 202 console.info("calendar onCancel"); 203 }, 204 onChange: (value) => { 205 console.info("calendar onChange:" + JSON.stringify(value)); 206 }, 207 onDidAppear: () => { 208 console.info("calendar onDidAppear"); 209 }, 210 onDidDisappear: () => { 211 console.info("calendar onDidDisappear"); 212 }, 213 onWillAppear: () => { 214 console.info("calendar onWillAppear"); 215 }, 216 onWillDisappear: () => { 217 console.info("calendar onWillDisappear"); 218 }, 219 enableHoverMode: true, 220 hoverModeArea: HoverModeAreaType.TOP_SCREEN, 221 }); 222 }) 223 }.width('100%') 224 } 225} 226``` 227 228 229 230### Example 4: Setting the Background Style for the Selected Date 231 232This example demonstrates how to customize the background style of the selected date using **hintRadius** in [CalendarOptions](ts-basic-components-calendarpicker.md#calendaroptions). 233 234```ts 235// xxx.ets 236@Entry 237@Component 238struct CalendarPickerDialogExample { 239 private selectedDate: Date = new Date('2024-04-23'); 240 241 build() { 242 Column() { 243 Button("Show CalendarPicker Dialog") 244 .margin(20) 245 .onClick(() => { 246 console.info("CalendarDialog.show"); 247 CalendarPickerDialog.show({ 248 selected: this.selectedDate, 249 hintRadius: 1, 250 onAccept: (value) => { 251 this.selectedDate = value; 252 console.info("calendar onAccept:" + JSON.stringify(value)); 253 } 254 }); 255 }) 256 }.width('100%') 257 } 258} 259``` 260 261 262 263### Example 5: Setting Start and End Dates 264 265This example demonstrates how to set the start and end dates for the calendar picker dialog box using **start** and **end** in [CalendarOptions](ts-basic-components-calendarpicker.md#calendaroptions). 266 267```ts 268// xxx.ets 269@Entry 270@Component 271struct CalendarPickerDialogExample { 272 private selectedDate: Date = new Date('2025-01-01'); 273 private startDate: Date = new Date('2024-01-10'); 274 private endDate: Date = new Date('2025-1-10'); 275 276 build() { 277 Column() { 278 Text('Calendar date picker').fontSize(30) 279 Button("Show CalendarPicker Dialog") 280 .margin(20) 281 .onClick(() => { 282 console.info("CalendarDialog.show"); 283 CalendarPickerDialog.show({ 284 start: this.startDate, 285 end: this.endDate, 286 selected: this.selectedDate, 287 }); 288 }) 289 }.width('100%').margin({ top: 350 }) 290 } 291} 292``` 293 294 295 296### Example 6: Highlighting the Current System Date and Disabling a Specific Date Range 297 298This example shows how to highlight the current system date using **markToday** in [CalendarDialogOptions](#calendardialogoptions) and disable a specific date range using **disabledDateRange** in [CalendarOptions](ts-basic-components-calendarpicker.md#calendaroptions). 299 300```ts 301// xxx.ets 302@Entry 303@Component 304struct CalendarPickerExample { 305 private disabledDateRange: DateRange[] = [ 306 { start: new Date('2025-01-01'), end: new Date('2025-01-02') }, 307 { start: new Date('2025-01-09'), end: new Date('2025-01-10') }, 308 { start: new Date('2025-01-15'), end: new Date('2025-01-16') }, 309 { start: new Date('2025-01-19'), end: new Date('2025-01-19') }, 310 { start: new Date('2025-01-22'), end: new Date('2025-01-25') } 311 ]; 312 313 build() { 314 Column() { 315 Button("Show CalendarPicker Dialog") 316 .margin(20) 317 .onClick(() => { 318 console.info("CalendarDialog.show"); 319 CalendarPickerDialog.show({ markToday: true, disabledDateRange: this.disabledDateRange }); 320 }) 321 }.width('100%').margin({ top: 350 }) 322 } 323} 324``` 325 326 327 328### Example 7: Customizing the Background Blur Effect 329 330This example demonstrates how to customize the background blur effect by configuring [backgroundBlurStyleOptions](#calendardialogoptions). This functionality is supported since API version 19. 331 332```ts 333@Entry 334@Component 335struct CalendarPickerDialogExample { 336 private selectedDate: Date = new Date('2025-08-05'); 337 338 build() { 339 Stack({ alignContent: Alignment.Top }) { 340 Image($r('app.media.bg')) 341 Column() { 342 Button("Show CalendarPicker Dialog") 343 .margin(20) 344 .onClick(() => { 345 CalendarPickerDialog.show({ 346 selected: this.selectedDate, 347 hintRadius: 1, 348 backgroundColor: undefined, 349 backgroundBlurStyle: BlurStyle.Thin, 350 backgroundBlurStyleOptions: { 351 colorMode: ThemeColorMode.LIGHT, 352 adaptiveColor: AdaptiveColor.AVERAGE, 353 scale: 1, 354 blurOptions: { grayscale: [20, 20] }, 355 }, 356 }); 357 }) 358 }.width('100%') 359 } 360 } 361} 362``` 363 364 365 366### Example 8: Customizing the Background Effect 367 368This example demonstrates how to customize the background effect by configuring [backgroundEffect](#calendardialogoptions). This functionality is supported since API version 19. 369 370```ts 371@Entry 372@Component 373struct CalendarPickerDialogExample { 374 private selectedDate: Date = new Date('2025-08-05'); 375 376 build() { 377 Stack({ alignContent: Alignment.Top }) { 378 Image($r('app.media.bg')) 379 Column() { 380 Button("Show CalendarPicker Dialog") 381 .margin(20) 382 .onClick(() => { 383 CalendarPickerDialog.show({ 384 selected: this.selectedDate, 385 hintRadius: 1, 386 backgroundColor: undefined, 387 backgroundBlurStyle: BlurStyle.Thin, 388 backgroundEffect: { 389 radius: 60, 390 saturation: 0, 391 brightness: 1, 392 color: Color.White, 393 blurOptions: { grayscale: [20, 20] } 394 }, 395 }); 396 }) 397 }.width('100%') 398 } 399 } 400} 401``` 402 403 404
