1# Calendar Picker Dialog Box (CalendarPickerDialog) 2 3A calendar picker dialog box is a dialog box that allows users to select a date from a calendar picker. 4 5> **NOTE** 6> 7> This component is supported since API version 10. 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](../js-apis-arkui-UIContext.md#uicontext). 10 11## CalendarPickerDialog 12 13### show 14 15static show(options?: CalendarDialogOptions) 16 17Shows a calendar picker dialog box. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name | Type | Mandatory| Description | 26| ------- | ------------------------------------------------------- | ---- | -------------------------- | 27| options | [CalendarDialogOptions](#calendardialogoptions) | No | Parameters of the calendar picker dialog box.| 28 29## CalendarDialogOptions 30 31Inherits from [CalendarOptions](ts-basic-components-calendarpicker.md#calendaroptions). 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35| Name | Type | Mandatory| Description | 36| ---------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 37| onAccept | [Callback](ts-types.md#callback12)\<Date> | No | Triggered when the OK button in the dialog box is clicked.<br>The selected date value is returned.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| onCancel | [VoidCallback](ts-types.md#voidcallback12) | No | 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. | 39| onChange | [Callback](ts-types.md#callback12)\<Date> | No | Triggered when the selection in the picker changes the selected date.<br>The selected date value is returned.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 40| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| 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.| 41| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| 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.| 42| acceptButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](ts-methods-datepicker-dialog.md#pickerdialogbuttonstyle12) | No| 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.| 43| cancelButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](ts-methods-datepicker-dialog.md#pickerdialogbuttonstyle12) | No| 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.| 44| onDidAppear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| 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.| 45| onDidDisappear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| 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.| 46| onWillAppear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| 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.| 47| onWillDisappear<sup>12+</sup> | [VoidCallback](ts-types.md#voidcallback12) | No| 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.| 48| shadow<sup>12+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | 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.| 49| enableHoverMode<sup>14+</sup> | boolean | No | Whether to enable the hover mode.<br>Default value: **false**, meaning not to enable the hover mode.<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 50| hoverModeArea<sup>14+</sup> | [HoverModeAreaType](ts-appendix-enums.md#hovermodeareatype14) | No | Display area of the dialog box in hover mode.<br>Default value: **HoverModeAreaType.BOTTOM_SCREEN**<br>**Atomic service API**: This API can be used in atomic services since API version 14.| 51 52> **NOTE** 53> 54> 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. 55 56## Example 57 58### Example 1: Setting the Background 59 60This example demonstrates how to set the dialog box background using **backgroundColor**, **backgroundBlurStyle**, and **shadow**. 61 62```ts 63// xxx.ets 64@Entry 65@Component 66struct CalendarPickerDialogExample { 67 private selectedDate: Date = new Date('2024-04-23') 68 69 build() { 70 Column() { 71 Button("Show CalendarPicker Dialog") 72 .margin(20) 73 .onClick(() => { 74 console.info("CalendarDialog.show") 75 CalendarPickerDialog.show({ 76 selected: this.selectedDate, 77 backgroundColor: Color.White, 78 backgroundBlurStyle: BlurStyle.NONE, 79 shadow: ShadowStyle.OUTER_FLOATING_SM, 80 onAccept: (value) => { 81 this.selectedDate = value 82 console.info("calendar onAccept:" + JSON.stringify(value)) 83 }, 84 onCancel: () => { 85 console.info("calendar onCancel") 86 }, 87 onChange: (value) => { 88 console.info("calendar onChange:" + JSON.stringify(value)) 89 }, 90 onDidAppear: () => { 91 console.info("calendar onDidAppear") 92 }, 93 onDidDisappear: () => { 94 console.info("calendar onDidDisappear") 95 }, 96 onWillAppear: () => { 97 console.info("calendar onWillAppear") 98 }, 99 onWillDisappear: () => { 100 console.info("calendar onWillDisappear") 101 } 102 }) 103 }) 104 }.width('100%') 105 } 106} 107``` 108 109 110 111### Example 2: Customizing the Button Style 112 113This example demonstrates how to customize the button style using **acceptButtonStyle** and **cancelButtonStyle**. 114 115```ts 116// xxx.ets 117@Entry 118@Component 119struct CalendarPickerDialogExample { 120 private selectedDate: Date = new Date() 121 122 build() { 123 Column() { 124 Button("Show CalendarPicker Dialog") 125 .margin(20) 126 .onClick(() => { 127 console.info("CalendarDialog.show") 128 CalendarPickerDialog.show({ 129 selected: this.selectedDate, 130 acceptButtonStyle: { 131 type: ButtonType.Normal, 132 style: ButtonStyleMode.NORMAL, 133 role: ButtonRole.NORMAL, 134 fontColor: 'rgb(81, 81, 216)', 135 fontSize: '26fp', 136 fontWeight: FontWeight.Bolder, 137 fontStyle: FontStyle.Normal, 138 fontFamily: 'sans-serif', 139 backgroundColor: '#A6ACAF', 140 borderRadius: 20 141 }, 142 cancelButtonStyle: { 143 type: ButtonType.Normal, 144 style: ButtonStyleMode.NORMAL, 145 role: ButtonRole.NORMAL, 146 fontColor: Color.Blue, 147 fontSize: '16fp', 148 fontWeight: FontWeight.Normal, 149 fontStyle: FontStyle.Italic, 150 fontFamily: 'sans-serif', 151 backgroundColor: '#50182431', 152 borderRadius: 10 153 }, 154 onAccept: (value) => { 155 this.selectedDate = value 156 console.info("calendar onAccept:" + JSON.stringify(value)) 157 } 158 }) 159 }) 160 }.width('100%') 161 } 162} 163``` 164 165 166 167### Example 3: Configuring a Dialog Box in the Hover State 168 169This example demonstrates how to set the layout area of a dialog box in hover mode on a foldable device. 170 171```ts 172@Entry 173@Component 174struct CalendarPickerDialogExample { 175 private selectedDate: Date = new Date('2024-04-23'); 176 177 build() { 178 Column() { 179 Button("Show CalendarPicker Dialog") 180 .margin(20) 181 .onClick(() => { 182 console.info("CalendarDialog.show") 183 CalendarPickerDialog.show({ 184 selected: this.selectedDate, 185 onAccept: (value) => { 186 console.info("calendar onAccept:" + JSON.stringify(value)) 187 }, 188 onCancel: () => { 189 console.info("calendar onCancel") 190 }, 191 onChange: (value) => { 192 console.info("calendar onChange:" + JSON.stringify(value)) 193 }, 194 onDidAppear: () => { 195 console.info("calendar onDidAppear") 196 }, 197 onDidDisappear: () => { 198 console.info("calendar onDidDisappear") 199 }, 200 onWillAppear: () => { 201 console.info("calendar onWillAppear") 202 }, 203 onWillDisappear: () => { 204 console.info("calendar onWillDisappear") 205 }, 206 enableHoverMode: true, 207 hoverModeArea: HoverModeAreaType.TOP_SCREEN, 208 }) 209 }) 210 }.width('100%') 211 } 212} 213``` 214 215 216 217### Example 4: Setting the Background Style for the Selected Date 218 219This example demonstrates how to customize the background style of the selected date using **hintRadius**. 220 221```ts 222// xxx.ets 223@Entry 224@Component 225struct CalendarPickerDialogExample { 226 private selectedDate: Date = new Date('2024-04-23') 227 228 build() { 229 Column() { 230 Button("Show CalendarPicker Dialog") 231 .margin(20) 232 .onClick(() => { 233 console.info("CalendarDialog.show") 234 CalendarPickerDialog.show({ 235 selected: this.selectedDate, 236 hintRadius: 1, 237 onAccept: (value) => { 238 this.selectedDate = value 239 console.info("calendar onAccept:" + JSON.stringify(value)) 240 } 241 }) 242 }) 243 }.width('100%') 244 } 245} 246``` 247 248 249 250### Example 5: Setting Start and End Dates 251 252This example demonstrates how to set the start and end dates for the calendar picker dialog box using **start** and **end**. 253 254```ts 255// xxx.ets 256@Entry 257@Component 258struct CalendarPickerDialogExample { 259 private selectedDate: Date = new Date('2025-01-01') 260 private startDate: Date = new Date('2024-01-10') 261 private endDate: Date = new Date('2025-1-10') 262 263 build() { 264 Column() { 265 Text('Calendar date picker').fontSize(30) 266 Button("Show CalendarPicker Dialog") 267 .margin(20) 268 .onClick(() => { 269 console.info("CalendarDialog.show") 270 CalendarPickerDialog.show({ 271 start: this.startDate, 272 end: this.endDate, 273 selected: this.selectedDate, 274 }) 275 }) 276 }.width('100%').margin({ top: 350 }) 277 } 278} 279``` 280 281
