1# Date Picker Dialog Box (DatePickerDialog) 2 3A date picker dialog box is a dialog box that allows users to select a date from the given range. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 8. 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> Since API version 10, you can use the [showDatePickerDialog](../js-apis-arkui-UIContext.md#showdatepickerdialog) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext) to obtain the UI context. 12 13## DatePickerDialog.show 14 15static show(options?: DatePickerDialogOptions) 16 17Shows a date 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 | [DatePickerDialogOptions](#datepickerdialogoptions) | No | Parameters of the date picker dialog box.| 28 29## DatePickerDialogOptions 30 31Inherited from [DatePickerOptions](ts-basic-components-datepicker.md#datepickeroptions). 32 33**System capability**: SystemCapability.ArkUI.ArkUI.Full 34 35| Name| Type| Mandatory| Description| 36| -------- | -------- | -------- | -------- | 37| lunar | boolean | No| Whether to display the lunar calendar. The value **true** means to display the lunar calendar, and **false** means the opposite.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| showTime<sup>10+</sup> | boolean | No| Whether to display the time item. The value **true** means to display the time item, and **false** means the opposite.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 39| useMilitaryTime<sup>10+</sup> | boolean | No| Whether to display time in 24-hour format. The value **true** means to display time in 24-hour format, and **false** means the opposite.<br>Default value: **false**<br>**NOTE**<br>When the display time is in 12-hour format, the AM/PM zone does not change depending on the hour portion.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 40| lunarSwitch<sup>10+</sup> | boolean | No| Whether to display the lunar calendar switch. The value **true** means to display the lunar calendar switch, and **false** means the opposite.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 41| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.<br>Default value:<br>{<br>color: '#ff182431',<br>font: {<br>size: '14fp', <br>weight: FontWeight.Regular<br>}<br>}<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 42| textStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of all items except the top, bottom, and selected items.<br>Default value:<br>{<br>color: '#ff182431',<br>font: {<br>size: '16fp', <br>weight: FontWeight.Regular<br>}<br>}<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 43| selectedTextStyle<sup>10+</sup> | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.<br>Default value:<br>{<br>color: '#ff007dff',<br>font: {<br>size: '20vp', <br>weight: FontWeight.Medium<br>}<br>} <br>**Atomic service API**: This API can be used in atomic services since API version 11.| 44| acceptButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](#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.| 45| cancelButtonStyle<sup>12+</sup> | [PickerDialogButtonStyle](#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.| 46| alignment<sup>10+</sup> | [DialogAlignment](ts-methods-alert-dialog-box.md#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.<br>Default value: **DialogAlignment.Default**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 47| offset<sup>10+</sup> | [Offset](ts-types.md#offset) | No | Offset of the dialog box based on the **alignment** settings.<br>Default value: **{ dx: 0 , dy: 0 }**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 48| maskRect<sup>10+</sup>| [Rectangle](ts-methods-alert-dialog-box.md#rectangle8) | No | Mask area of the dialog box. Events outside the mask area are transparently transmitted, and events within the mask area are not.<br>Default value: **{ x: 0, y: 0, width: '100%', height: '100%' }**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 49| onAccept<sup>(deprecated)</sup> | (value: [DatePickerResult](ts-basic-components-datepicker.md#datepickerresult)) => void | No| Callback invoked when the OK button in the dialog box is clicked.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 10. You are advised to use **onDateAccept** instead.| 50| onCancel | () => void | No| Callback invoked 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.| 51| onChange<sup>(deprecated)</sup> | (value: [DatePickerResult](ts-basic-components-datepicker.md#datepickerresult)) => void | No| Callback invoked when the selected item in the picker changes.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 10. You are advised to use **onDateChange** instead.| 52| onDateAccept<sup>10+</sup> | (value: Date) => void | No| Callback invoked when the OK button in the dialog box is clicked.<br>**NOTE**<br>When **showTime** is set to **true**, the hour and minute in the value returned by the callback are the hour and minute selected in the picker. Otherwise, the hour and minute are the hour and minute of the system time.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 53| onDateChange<sup>10+</sup> | (value: Date) => void | No| Callback invoked when the selected item in the picker changes.<br>**NOTE**<br>When **showTime** is set to **true**, the hour and minute in the value returned by the callback are the hour and minute selected in the picker. Otherwise, the hour and minute are the hour and minute of the system time.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 54| backgroundColor<sup>11+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No| Backplane color of the dialog box.<br>Default value: **Color.Transparent**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 55| 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>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| onDidAppear<sup>12+</sup> | () => void | No| Event callback when the dialog box appears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > 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 closes the dialog box immediately after it appears, **onWillDisappear** is invoked before **onDidAppear**.<br>4. If the dialog box is closed 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> | () => void | No| Event callback when the dialog box disappears.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > onWillDisappear > onDidDisappear.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| onWillAppear<sup>12+</sup> | () => void | No| Event callback when the dialog box is about to appear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > 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> | () => void | No| Event callback when the dialog box is about to disappear.<br>**NOTE**<br>1. The normal timing sequence is as follows: onWillAppear > onDidAppear > (onDateAccept/onCancel/onDateChange) > 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 | 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| dateTimeOptions<sup>12+</sup> | [DateTimeOptions](../../apis-localization-kit/js-apis-intl.md#datetimeoptions) | No| Whether to display a leading zero for the hours and minutes. Currently only the configuration of the **hour** and **minute** parameters is supported.<br>Default value:<br>**hour**: In the 24-hour format, it defaults to **2-digit**, which means a leading zero is used; In the 12-hour format, it defaults to **numeric**, which means no leading zero is used.<br>**minute**: defaults to **2-digit**, which means a leading zero is used.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 62 63## PickerDialogButtonStyle<sup>12+</sup> 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 69| Name | Type | Mandatory | Description | 70| ----- | ---------------------------------------- | ---- | ------------------------- | 71| type | [ButtonType](ts-basic-components-button.md#buttontype) | No | Button type. | 72| style | [ButtonStyleMode](ts-basic-components-button.md#buttonstylemode11) | No | Style and importance of the button.| 73| role | [ButtonRole](ts-basic-components-button.md#buttonrole12) | No | Role of the the button. | 74| fontSize | [Length](ts-types.md#length) | No | Font size of the button.| 75| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the button. | 76| fontWeight | [FontWeight](ts-appendix-enums.md#fontweight) \| number \| string| No | Font weight of the button. For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a thicker font.| 77| fontStyle | [FontStyle](ts-appendix-enums.md#fontstyle) | No | Font style of the button. | 78| fontFamily | [Resource](ts-types.md#resource) \| string | No | Font family of the button. The 'HarmonyOS Sans' font and [registered custom fonts](../js-apis-font.md) are supported.| 79| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the button. | 80| borderRadius | [Length](ts-types.md#length) \| [BorderRadiuses](ts-types.md#borderradiuses9)| No | Rounded corner radius of the button.| 81| primary | boolean | No | Whether the button responds to the **Enter** key by default when the dialog box has focus and the **Tab** key is not pressed for sequential focus navigation.| 82 83**Handling in the case of exceptions** 84 85| Exception | Result | 86| -------- | ------------------------------------------------------------ | 87| The start date is later than the end date, and the selected date is not set. | The start date, end date, and selected date are set to the default values. | 88| The start date is later than the end date, and the selected date is earlier than the default start date. | The start date and end date are set to the default values, and the selected date is set to the default start date. | 89| The start date is later than the end date, and the selected date is later than the default end date. | The start date and end date are set to the default values, and the selected date is set to the default end date. | 90| The start date is later than the end date, and the selected date is within the range of the default start date and end date. | The start date and end date are set to the default values, and the selected date is set to the specified value.| 91| The selected date is earlier than the start date. | The selected date is set to the start date. | 92| The selected date is later than the end date. | The selected date is set to the end date. | 93| The start date is later than the current system date, and the selected date is not set. | The selected date is set to the start date. | 94| The end date is earlier than the current system date, and the selected date is not set. | The selected date is set to the end date. | 95| The set date is in invalid format, for example, **'1999-13-32'**. | The default value is used. | 96| The start date or end date is earlier than the valid date range. | The start date or end date is set to the earliest date in the valid date range. | 97| The start date or end date is later than the valid date range. | The start date or end date is set to the latest date in the valid date range. | 98 99The valid date range is from 1900-1-31 to 2100-12-31. 100 101The exception detection and handling with the selected date comes after that with the start date and end date. 102 103## Example 104 105### Example 1 106 107This example shows the basic usage of **DatePickerDialog**. 108 109```ts 110// xxx.ets 111@Entry 112@Component 113struct DatePickerDialogExample { 114 selectedDate: Date = new Date("2010-1-1") 115 116 build() { 117 Column() { 118 Button("DatePickerDialog") 119 .margin(20) 120 .onClick(() => { 121 DatePickerDialog.show({ 122 start: new Date("2000-1-1"), 123 end: new Date("2100-12-31"), 124 selected: this.selectedDate, 125 showTime:true, 126 useMilitaryTime:false, 127 disappearTextStyle: {color: Color.Pink, font: {size: '22fp', weight: FontWeight.Bold}}, 128 textStyle: {color: '#ff00ff00', font: {size: '18fp', weight: FontWeight.Normal}}, 129 selectedTextStyle: {color: '#ff182431', font: {size: '14fp', weight: FontWeight.Regular}}, 130 onDateAccept: (value: Date) => { 131 // Use the setFullYear method to set the date when the OK button is touched. In this way, when the date picker dialog box is displayed again, the selected date is the date last confirmed. 132 this.selectedDate = value 133 console.info("DatePickerDialog:onDateAccept()" + value.toString()) 134 }, 135 onCancel: () => { 136 console.info("DatePickerDialog:onCancel()") 137 }, 138 onDateChange: (value: Date) => { 139 console.info("DatePickerDialog:onDateChange()" + value.toString()) 140 }, 141 onDidAppear: () => { 142 console.info("DatePickerDialog:onDidAppear()") 143 }, 144 onDidDisappear: () => { 145 console.info("DatePickerDialog:onDidDisappear()") 146 }, 147 onWillAppear: () => { 148 console.info("DatePickerDialog:onWillAppear()") 149 }, 150 onWillDisappear: () => { 151 console.info("DatePickerDialog:onWillDisappear()") 152 } 153 }) 154 }) 155 156 Button("Lunar DatePickerDialog") 157 .margin(20) 158 .onClick(() => { 159 DatePickerDialog.show({ 160 start: new Date("2000-1-1"), 161 end: new Date("2100-12-31"), 162 selected: this.selectedDate, 163 lunar: true, 164 disappearTextStyle: {color: Color.Pink, font: {size: '22fp', weight: FontWeight.Bold}}, 165 textStyle: {color: '#ff00ff00', font: {size: '18fp', weight: FontWeight.Normal}}, 166 selectedTextStyle: {color: '#ff182431', font: {size: '14fp', weight: FontWeight.Regular}}, 167 onDateAccept: (value: Date) => { 168 this.selectedDate = value 169 console.info("DatePickerDialog:onDateAccept()" + value.toString()) 170 }, 171 onCancel: () => { 172 console.info("DatePickerDialog:onCancel()") 173 }, 174 onDateChange: (value: Date) => { 175 console.info("DatePickerDialog:onDateChange()" + value.toString()) 176 }, 177 onDidAppear: () => { 178 console.info("DatePickerDialog:onDidAppear()") 179 }, 180 onDidDisappear: () => { 181 console.info("DatePickerDialog:onDidDisappear()") 182 }, 183 onWillAppear: () => { 184 console.info("DatePickerDialog:onWillAppear()") 185 }, 186 onWillDisappear: () => { 187 console.info("DatePickerDialog:onWillDisappear()") 188 } 189 }) 190 }) 191 }.width('100%') 192 } 193} 194``` 195 196 197 198### Example 2 199 200This example shows how to customize the button style. 201 202```ts 203// xxx.ets 204@Entry 205@Component 206struct DatePickerDialogExample { 207 selectedDate: Date = new Date("2010-1-1") 208 209 build() { 210 Column() { 211 Button("DatePickerDialog") 212 .margin(20) 213 .onClick(() => { 214 DatePickerDialog.show({ 215 start: new Date("2000-1-1"), 216 end: new Date("2100-12-31"), 217 selected: this.selectedDate, 218 showTime:true, 219 useMilitaryTime:false, 220 disappearTextStyle: {color: Color.Pink, font: {size: '22fp', weight: FontWeight.Bold}}, 221 textStyle: {color: '#ff00ff00', font: {size: '18fp', weight: FontWeight.Normal}}, 222 selectedTextStyle: {color: '#ff182431', font: {size: '14fp', weight: FontWeight.Regular}}, 223 acceptButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Red, 224 fontSize: '26fp', fontWeight: FontWeight.Bolder, fontStyle: FontStyle.Normal, fontFamily: 'sans-serif', backgroundColor:'#80834511', 225 borderRadius: 20 }, 226 cancelButtonStyle: { type: ButtonType.Normal, style: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL, fontColor: Color.Blue, 227 fontSize: '16fp', fontWeight: FontWeight.Normal, fontStyle: FontStyle.Italic, fontFamily: 'sans-serif', backgroundColor:'#50182431', 228 borderRadius: 10 }, 229 onDateAccept: (value: Date) => { 230 // Use the setFullYear method to set the date when the OK button is touched. In this way, when the date picker dialog box is displayed again, the selected date is the date last confirmed. 231 this.selectedDate = value 232 console.info("DatePickerDialog:onDateAccept()" + value.toString()) 233 }, 234 onCancel: () => { 235 console.info("DatePickerDialog:onCancel()") 236 }, 237 onDateChange: (value: Date) => { 238 console.info("DatePickerDialog:onDateChange()" + value.toString()) 239 }, 240 onDidAppear: () => { 241 console.info("DatePickerDialog:onDidAppear()") 242 }, 243 onDidDisappear: () => { 244 console.info("DatePickerDialog:onDidDisappear()") 245 }, 246 onWillAppear: () => { 247 console.info("DatePickerDialog:onWillAppear()") 248 }, 249 onWillDisappear: () => { 250 console.info("DatePickerDialog:onWillDisappear()") 251 } 252 }) 253 }) 254 }.width('100%') 255 } 256} 257``` 258 259 260 261> **NOTE** 262> 263> To implement a fully customized date picker dialog box, create a [custom dialog box](ts-methods-custom-dialog-box.md) and then implement the [\<DatePicker>](ts-basic-components-datepicker.md) component. 264
