1# DatePicker 2 3The **DatePicker** component allows users to select a date from the given range. 4 5> **NOTE** 6> 7> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12Not supported 13 14 15## APIs 16 17DatePicker(options?: DatePickerOptions) 18 19Creates a date picker in the given date range. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name | Type | Mandatory| Description | 28| ------- | ----------------------------------------------- | ---- | -------------------------- | 29| options | [DatePickerOptions](#datepickeroptions) | No | Parameters of the date picker.| 30 31## DatePickerOptions 32 33**Atomic service API**: This API can be used in atomic services since API version 11. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37| Name | Type| Mandatory| Description | 38| -------- | ---- | ---- | ------------------------------------------------------------ | 39| start | Date | No | Start date of the picker.<br>Default value: **Date('1970-1-1')** | 40| end | Date | No | End date of the picker.<br>Default value: **Date('2100-12-31')** | 41| selected | Date | No | Date of the selected item.<br>Default value: current system date<br>Since API version 10, this parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).| 42| mode<sup>18+</sup> | [DatePickerMode](#datepickermode18) | No | Date columns to be displayed.<br>Default value: **DatePickerMode.DATE**, which means to display three columns: year, month, and day. Decimal values are rounded off.<br>In **DatePickerDialog**, with **showTime=true**, this parameter has no effect and the default three columns for year, month, and day are displayed.| 43 44> **NOTE** 45> 46> For details about how to use **Date**, see [TimePickerOptions](ts-basic-components-timepicker.md). 47> Modifying the **DatePickerOptions** properties, such as **start**, **end**, or **selected**, during the scrolling process of the **DatePicker** component may not take effect. 48 49 50## DatePickerMode<sup>18+</sup> 51 52Sets the date columns to be displayed. 53 54**Atomic service API**: This API can be used in atomic services since API version 18. 55 56**System capability**: SystemCapability.ArkUI.ArkUI.Full 57 58| Name| Description| 59| -------- | -------- | 60| DATE | The date displays three columns: year, month, and day.| 61| YEAR_AND_MONTH | The date displays two columns: year and month.| 62| MONTH_AND_DAY | The date displays two columns: month and day.<br>In this mode, if the month changes from December to January, the year does not increment by one; if the month changes from January to December, the year does not decrement by one. The year remains fixed at the currently set value.| 63 64**Handling in the case of exceptions** 65 66| Exception | Result | 67| -------- | ------------------------------------------------------------ | 68| 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. | 69| 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. | 70| 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. | 71| 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.| 72| The selected date is earlier than the start date. | The start date is set to the selected date. | 73| The selected date is later than the end date. | The selected date is set to the end date. | 74| The start date is later than the current system date, and the selected date is not set. | The start date is set to the selected date. | 75| The end date is earlier than the current system date, and the selected date is not set. | The end date is set to the selected date. | 76| The set date is in invalid format, for example, **'1999-13-32'**. | The default value is used. | 77| The start date or end date is earlier than the earliest date in the valid date range. | The start date or end date is set to the default state date.| 78| The start date or end date is later than the latest date in the valid date range. | The start date or end date is set to the default end date.| 79| Both the start date and end date are earlier than the earliest date in the valid date range.| The start date and end date are set to the earliest date in the valid date range.| 80| Both the start date and end date are later than the latest date in the valid date range.| The start date and end date are set to the latest date in the valid date range.| 81 82The valid date range is from 1900-1-31 to 2100-12-31. 83 84The exception detection and handling with the selected date comes after that with the start date and end date. 85 86## Attributes 87 88In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 89 90### lunar 91 92lunar(value: boolean) 93 94Specifies whether to display the lunar calendar. 95 96**Atomic service API**: This API can be used in atomic services since API version 11. 97 98**System capability**: SystemCapability.ArkUI.ArkUI.Full 99 100**Parameters** 101 102| Name| Type | Mandatory| Description | 103| ------ | ------- | ---- | ------------------------------------------------------------ | 104| value | boolean | Yes | Whether to display the lunar calendar.<br>- **true**: Display the lunar calendar.<br>- **false**: Do not display the lunar calendar.<br>Default value: **false**| 105 106### lunar<sup>18+</sup> 107 108lunar(isLunar: Optional\<boolean>) 109 110Specifies whether to display the lunar calendar. Compared to [lunar](#lunar), this API supports the **undefined** type for the **isLunar** parameter. 111 112**Atomic service API**: This API can be used in atomic services since API version 18. 113 114**System capability**: SystemCapability.ArkUI.ArkUI.Full 115 116**Parameters** 117 118| Name| Type | Mandatory| Description | 119| ------ | ------- | ---- | ------------------------------------------------------------ | 120| isLunar | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether to display the lunar calendar.<br>- **true**: Display the lunar calendar.<br>- **false**: Do not display the lunar calendar.<br>If **isLunar** is set to **undefined**, the default value **false** is used.| 121 122### disappearTextStyle<sup>10+</sup> 123 124disappearTextStyle(value: PickerTextStyle) 125 126Sets the text style for the top and bottom items. 127 128**Atomic service API**: This API can be used in atomic services since API version 11. 129 130**System capability**: SystemCapability.ArkUI.ArkUI.Full 131 132**Parameters** 133 134| Name| Type | Mandatory| Description | 135| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 136| value | [PickerTextStyle](#pickertextstyle10) | Yes | Font color, font size, and font weight of the top and bottom items.<br>Default value:<br>{<br>color: '#ff182431',<br>font: {<br>size: '14fp', <br>weight: FontWeight.Regular<br>}<br>} | 137 138### disappearTextStyle<sup>18+</sup> 139 140disappearTextStyle(style: Optional\<PickerTextStyle>) 141 142Sets the text style for the top and bottom items. Compared to [disappearTextStyle](#disappeartextstyle10)<sup>10+</sup>, this API supports the **undefined** type for the **style** parameter. 143 144**Atomic service API**: This API can be used in atomic services since API version 18. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148**Parameters** 149 150| Name| Type | Mandatory| Description | 151| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 152| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](#pickertextstyle10)> | Yes | Font color, font size, and font weight of the top and bottom items.<br>If **style** is set to **undefined**, the default value is used:<br>{<br>color: '#ff182431',<br>font: {<br>size: '14fp', <br>weight: FontWeight.Regular<br>}<br>} | 153 154### textStyle<sup>10+</sup> 155 156textStyle(value: PickerTextStyle) 157 158Sets the text style for all items except the top, bottom, and selected items. 159 160**Atomic service API**: This API can be used in atomic services since API version 11. 161 162**System capability**: SystemCapability.ArkUI.ArkUI.Full 163 164**Parameters** 165 166| Name| Type | Mandatory| Description | 167| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 168| value | [PickerTextStyle](#pickertextstyle10) | Yes | Font color, font size, and font weight 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>} | 169 170### textStyle<sup>18+</sup> 171 172textStyle(style: Optional\<PickerTextStyle>) 173 174Sets the text style for all items except the top, bottom, and selected items. Compared to [textStyle](#textstyle10)<sup>10+</sup>, this API supports the **undefined** type for the **style** parameter. 175 176**Atomic service API**: This API can be used in atomic services since API version 18. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Parameters** 181 182| Name| Type | Mandatory| Description | 183| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 184| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](#pickertextstyle10)> | Yes | Font color, font size, and font weight of all items except the top, bottom, and selected items.<br>If **style** is set to **undefined**, the default value is used:<br>{<br>color: '#ff182431',<br>font: {<br>size: '16fp', <br>weight: FontWeight.Regular<br>}<br>} | 185 186### selectedTextStyle<sup>10+</sup> 187 188selectedTextStyle(value: PickerTextStyle) 189 190Sets the text style for the selected item. 191 192**Atomic service API**: This API can be used in atomic services since API version 11. 193 194**System capability**: SystemCapability.ArkUI.ArkUI.Full 195 196**Parameters** 197 198| Name| Type | Mandatory| Description | 199| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 200| value | [PickerTextStyle](#pickertextstyle10) | Yes | Font color, font size, and font weight of the selected item.<br>Default value:<br>{<br>color: '#ff007dff',<br>font: {<br>size: '20vp', <br>weight: FontWeight.Medium<br>}<br>} | 201 202### selectedTextStyle<sup>18+</sup> 203 204selectedTextStyle(style: Optional\<PickerTextStyle>) 205 206Sets the text style for the selected item. Compared to [selectedTextStyle](#selectedtextstyle10)<sup>10+</sup>, this API supports the **undefined** type for the **style** parameter. 207 208**Atomic service API**: This API can be used in atomic services since API version 18. 209 210**System capability**: SystemCapability.ArkUI.ArkUI.Full 211 212**Parameters** 213 214| Name| Type | Mandatory| Description | 215| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 216| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](#pickertextstyle10)> | Yes | Font color, font size, and font weight of the selected item.<br>If **style** is set to **undefined**, the default value is used:<br>{<br>color: '#ff007dff',<br>font: {<br>size: '20vp', <br>weight: FontWeight.Medium<br>}<br>} | 217 218### enableHapticFeedback<sup>18+</sup> 219 220enableHapticFeedback(enable: Optional\<boolean>) 221 222Sets whether to enable haptic feedback. 223 224**Atomic service API**: This API can be used in atomic services since API version 18. 225 226**System capability**: SystemCapability.ArkUI.ArkUI.Full 227 228| Name| Type | Mandatory | Description | 229| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------| 230| enable | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether to enable haptic feedback.<br>**true** (default): Haptic feedback is enabled.<br>**false**: Haptic feedback is disabled.| 231 232> **NOTE** 233> 234> To enable haptic feedback, you must declare the ohos.permission.VIBRATE permission under **requestPermissions** in the **module.json5** file of the project. 235> ```json 236> "requestPermissions": [ 237> { 238> "name": "ohos.permission.VIBRATE", 239> } 240> ] 241> ``` 242 243### digitalCrownSensitivity<sup>18+</sup> 244digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 245 246Sets the sensitivity to the digital crown rotation. 247 248**Atomic service API**: This API can be used in atomic services since API version 18. 249 250**System capability**: SystemCapability.ArkUI.ArkUI.Full 251 252| Name | Type | Mandatory | Description | 253| ----- | ---------------------------------------- | ---- | ------------------------- | 254| sensitivity | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CrownSensitivity](ts-appendix-enums.md#crownsensitivity18)> | Yes | Sensitivity to the digital crown rotation.<br>Default value: **CrownSensitivity.MEDIUM** | 255 256> **NOTE** 257> 258> This API is only available to circular screens on wearable devices. The component needs to obtain focus before responding to the [crown event](ts-universal-events-crown.md). 259 260## PickerTextStyle<sup>10+</sup> 261 262**Atomic service API**: This API can be used in atomic services since API version 11. 263 264| Name | Type | Mandatory | Description | 265| ----- | ---------------------------------------- | ---- | ------------------------- | 266| color | [ResourceColor](ts-types.md#resourcecolor) | No | Font color. | 267| font | [Font](ts-types.md#font) | No | Text style.| 268 269## Events 270 271In addition to the [universal events](ts-component-general-events.md), the following events are supported. 272 273### onChange<sup>(deprecated)</sup> 274 275onChange(callback: (value: DatePickerResult) => void) 276 277Triggered when a date is selected. 278 279This API is supported since API version 8 and deprecated since API version 10. You are advised to use [onDateChange](#ondatechange10) instead. 280 281**System capability**: SystemCapability.ArkUI.ArkUI.Full 282 283**Parameters** 284 285| Name| Type | Mandatory| Description | 286| ------ | --------------------------------------------- | ---- | ---------------- | 287| value | [DatePickerResult](#datepickerresult) | Yes | Selected time.| 288 289### onDateChange<sup>10+</sup> 290 291onDateChange(callback: (value: Date) => void) 292 293Triggered when a date is selected. 294 295**Atomic service API**: This API can be used in atomic services since API version 11. 296 297**System capability**: SystemCapability.ArkUI.ArkUI.Full 298 299**Parameters** 300 301| Name| Type| Mandatory| Description | 302| ------ | ---- | ---- | ------------------------------------------------------------ | 303| value | Date | Yes | Selected time, where the year, month, and day portions are subject to the selection, the hour and minute portions are subject to the current system time, and the second portion is always **00**.| 304 305### onDateChange<sup>18+</sup> 306 307onDateChange(callback: Optional\<Callback\<Date>>) 308 309Triggered when a date is selected. Compared to [onDateChange](#ondatechange10)<sup>10+</sup>, this API supports the **undefined** type for the **callback** parameter. 310 311**Atomic service API**: This API can be used in atomic services since API version 18. 312 313**System capability**: SystemCapability.ArkUI.ArkUI.Full 314 315**Parameters** 316 317| Name | Type | Mandatory| Description | 318| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 319| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[Callback](ts-types.md#callback12)\<Date>> | Yes | Selected time, where the year, month, and day portions are subject to the selection, the hour and minute portions are subject to the current system time, and the second portion is always **00**.<br>If **callback** is set to **undefined**, the callback function is not used.| 320 321## DatePickerResult 322 323**Atomic service API**: This API can be used in atomic services since API version 11. 324 325**System capability**: SystemCapability.ArkUI.ArkUI.Full 326 327| Name | Type | Read Only| Optional| Description | 328| ----- | ------ | ---- | ---- | ------------------------------------------ | 329| year | number | No | No | Year of the selected date.<br>Value range: depends on **start** and **end**. If **start** and **end** are not set, the default range is [1970, 2100]. | 330| month | number | No | No | Month index of the selected date. The index is zero-based.<br>**0** indicates January, and **11** indicates December.<br>Value range: depends on **start** and **end**. If **start** and **end** are not set, the default range is [0, 11].| 331| day | number | No | No | Day of the selected date.<br>Value range: depends on **start** and **end**. If **start** and **end** are not set, the default range is [1, 31]. | 332 333## Example 334 335### Example 1: Switching Between Gregorian and Lunar Calendars 336 337This example implements a date picker that allows users to switch between the Gregorian (solar) calendar and the lunar calendar by clicking a button. 338 339 340```ts 341// xxx.ets 342@Entry 343@Component 344struct DatePickerExample { 345 @State isLunar: boolean = false 346 private selectedDate: Date = new Date('2021-08-08') 347 348 build() { 349 Column() { 350 Button('Switch Calendar') 351 .margin({ top: 30, bottom: 30 }) 352 .onClick(() => { 353 this.isLunar = !this.isLunar 354 }) 355 DatePicker({ 356 start: new Date('1970-1-1'), 357 end: new Date('2100-1-1'), 358 selected: this.selectedDate 359 }) 360 .lunar(this.isLunar) 361 .onDateChange((value: Date) => { 362 this.selectedDate = value 363 console.info('select current date is: ' + value.toString()) 364 }) 365 366 }.width('100%') 367 } 368} 369``` 370 371 372 373### Example 2: Setting the Text Style 374 375This example shows how to customize the text style using **disappearTextStyle**, **textStyle**, and **selectedTextStyle**. 376 377```ts 378// xxx.ets 379@Entry 380@Component 381struct DatePickerExample { 382 private selectedDate: Date = new Date('2021-08-08') 383 384 build() { 385 Column() { 386 DatePicker({ 387 start: new Date('1970-1-1'), 388 end: new Date('2100-1-1'), 389 selected: this.selectedDate 390 }) 391 .disappearTextStyle({ color: Color.Gray, font: { size: '16fp', weight: FontWeight.Bold } }) 392 .textStyle({ color: '#ff182431', font: { size: '18fp', weight: FontWeight.Normal } }) 393 .selectedTextStyle({ color: '#ff0000FF', font: { size: '26fp', weight: FontWeight.Regular, family: "HarmonyOS Sans", style: FontStyle.Normal } }) 394 .onDateChange((value: Date) => { 395 this.selectedDate = value 396 console.info('select current date is: ' + value.toString()) 397 }) 398 399 }.width('100%') 400 } 401} 402``` 403 404 405 406### Example 3: Displaying Year and Month, or Month and Day Columns 407 408This example demonstrates how to display year and month, or month and day columns using **mode**. 409 410```ts 411// xxx.ets 412@Entry 413@Component 414struct DatePickerExample { 415 @State isLunar: boolean = false 416 private selectedDate: Date = new Date('2025-01-15') 417 @State datePickerModeList: (DatePickerMode)[] = [ 418 DatePickerMode.DATE, 419 DatePickerMode.YEAR_AND_MONTH, 420 DatePickerMode.MONTH_AND_DAY, 421 ] 422 @State datePickerModeIndex: number = 0; 423 424 build() { 425 Column() { 426 Button('Switch Calendar') 427 .margin({ top: 30, bottom: 30 }) 428 .onClick(() => { 429 this.isLunar = !this.isLunar 430 }) 431 DatePicker({ 432 start: new Date('1970-1-1'), 433 end: new Date('2100-1-1'), 434 selected: this.selectedDate, 435 mode:this.datePickerModeList[this.datePickerModeIndex] 436 }) 437 .lunar(this.isLunar) 438 .onDateChange((value: Date) => { 439 this.selectedDate = value 440 console.info('select current date is: ' + value.toString()) 441 }) 442 443 Button('mode :' + this.datePickerModeIndex).margin({ top: 20 }) 444 .onClick(() => { 445 this.datePickerModeIndex++ 446 if(this.datePickerModeIndex >= this.datePickerModeList.length){ 447 this.datePickerModeIndex = 0 448 } 449 }) 450 }.width('100%') 451 } 452} 453``` 454 455
