• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name | Type                                           | Mandatory| Description                      |
26| ------- | ----------------------------------------------- | ---- | -------------------------- |
27| options | [DatePickerOptions](#datepickeroptions) | No  | Parameters of the date picker.|
28
29## DatePickerOptions
30
31| Name    | Type| Mandatory| Description                                                        |
32| -------- | ---- | ---- | ------------------------------------------------------------ |
33| start    | Date | No  | Start date of the picker.<br>Default value: **Date('1970-1-1')**         |
34| end      | Date | No  | End date of the picker.<br>Default value: **Date('2100-12-31')**       |
35| selected | Date | No  | Date of the selected item.<br>Default value: current system date<br>Since API version 10, this parameter supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.|
36
37**Handling in the case of exceptions**
38
39| Exception  | Result |
40| -------- |  ------------------------------------------------------------ |
41| 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. |
42| 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. |
43| 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. |
44| 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.|
45| The selected date is earlier than the start date.   | The selected date is set to the start date. |
46| The selected date is later than the end date.   | The selected date is set to the end date. |
47| 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. |
48| 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. |
49| The set date is in invalid format, for example, **'1999-13-32'**.  | The default value is used. |
50| 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. |
51| 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. |
52
53The valid date range is from 1900-1-31 to 2100-12-31.
54
55The exception detection and handling with the selected date comes after that with the start date and end date.
56
57## Attributes
58
59In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
60
61| Name                            | Type                                     | Description                                                        |
62| -------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
63| lunar                            | boolean                                       | Whether to display the lunar calendar.<br>- **true**: Display the lunar calendar.<br>- **false**: Do not display the lunar calendar.<br>Default value: **false**|
64| disappearTextStyle<sup>10+</sup> | [PickerTextStyle](#pickertextstyle10) | 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>} |
65| textStyle<sup>10+</sup>          | [PickerTextStyle](#pickertextstyle10) | 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>} |
66| selectedTextStyle<sup>10+</sup>  | [PickerTextStyle](#pickertextstyle10) | 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>} |
67
68## PickerTextStyle<sup>10+</sup>
69
70| Name  | Type                                    | Mandatory  | Description                     |
71| ----- | ---------------------------------------- | ---- | ------------------------- |
72| color | [ResourceColor](ts-types.md#resourcecolor) | No   | Font color.                    |
73| font  | [Font](ts-types.md#font)                 | No   | Text style. Only the font size and font width are supported.|
74
75## Events
76
77In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
78
79| Name                                                        | Description                                                    |
80| ------------------------------------------------------------ | ------------------------------------------------------------ |
81| onChange(callback: (value: DatePickerResult) =&gt; void)<sup>(deprecated)</sup> | Triggered when a date is selected.<br>**NOTE**<br>This API is supported since API version 8 and deprecated since API version 10. You are advised to use **onDateChange(callback: (value: Date) => void)** instead.|
82| onDateChange(callback: (value: Date) => void)<sup>10+</sup>  | Triggered when a date is selected.<br>**Date**: 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**.|
83
84## DatePickerResult
85
86| Name   | Type  | Description                         |
87| ----- | ------ | --------------------------- |
88| year  | number | Year of the selected date.                    |
89| month | number | Month of the selected date. The value ranges from 0 to 11. The value **0** indicates January, and **11** indicates December.|
90| day   | number | Day of the selected date.                    |
91
92
93## Example
94
95
96```ts
97// xxx.ets
98@Entry
99@Component
100struct DatePickerExample {
101  @State isLunar: boolean = false
102  private selectedDate: Date = new Date('2021-08-08')
103
104  build() {
105    Column() {
106      Button('Switch Calendar')
107        .margin({ top: 30, bottom: 30 })
108        .onClick(() => {
109          this.isLunar = !this.isLunar
110        })
111      DatePicker({
112        start: new Date('1970-1-1'),
113        end: new Date('2100-1-1'),
114        selected: this.selectedDate
115      })
116        .disappearTextStyle({color: Color.Gray, font: {size: '16fp', weight: FontWeight.Bold}})
117        .textStyle({color: '#ff182431', font: {size: '18fp', weight: FontWeight.Normal}})
118        .selectedTextStyle({color: '#ff0000FF', font: {size: '26fp', weight: FontWeight.Regular}})
119        .lunar(this.isLunar)
120        .onDateChange((value: Date) => {
121          this.selectedDate = value
122          console.info('select current date is: ' + value.toString())
123        })
124
125    }.width('100%')
126  }
127}
128```
129
130![datePicker](figures/DatePickerApi10.gif)
131