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
43**Handling in the case of exceptions**
44
45| Exception  | Result |
46| -------- |  ------------------------------------------------------------ |
47| 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. |
48| 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. |
49| 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. |
50| 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.|
51| The selected date is earlier than the start date.   | The start date is set to the selected date. |
52| The selected date is later than the end date.   | The selected date is set to the end date. |
53| 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. |
54| 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. |
55| The set date is in invalid format, for example, **'1999-13-32'**.  | The default value is used. |
56| 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.|
57| 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.|
58| 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.|
59| 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.|
60
61The valid date range is from 1900-1-31 to 2100-12-31.
62
63The exception detection and handling with the selected date comes after that with the start date and end date.
64
65## Attributes
66
67In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
68
69### lunar
70
71lunar(value: boolean)
72
73Specifies whether to display the lunar calendar.
74
75**Atomic service API**: This API can be used in atomic services since API version 11.
76
77**System capability**: SystemCapability.ArkUI.ArkUI.Full
78
79**Parameters**
80
81| Name| Type   | Mandatory| Description                                                        |
82| ------ | ------- | ---- | ------------------------------------------------------------ |
83| 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**|
84
85### disappearTextStyle<sup>10+</sup>
86
87disappearTextStyle(value: PickerTextStyle)
88
89Sets the text style for the top and bottom items.
90
91**Atomic service API**: This API can be used in atomic services since API version 11.
92
93**System capability**: SystemCapability.ArkUI.ArkUI.Full
94
95**Parameters**
96
97| Name| Type                                         | Mandatory| Description                                                        |
98| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ |
99| 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>} |
100
101### textStyle<sup>10+</sup>
102
103textStyle(value: PickerTextStyle)
104
105Sets the text style for all items except the top, bottom, and selected items.
106
107**Atomic service API**: This API can be used in atomic services since API version 11.
108
109**System capability**: SystemCapability.ArkUI.ArkUI.Full
110
111**Parameters**
112
113| Name| Type                                         | Mandatory| Description                                                        |
114| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ |
115| 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>} |
116
117### selectedTextStyle<sup>10+</sup>
118
119selectedTextStyle(value: PickerTextStyle)
120
121Sets the text style for the selected item.
122
123**Atomic service API**: This API can be used in atomic services since API version 11.
124
125**System capability**: SystemCapability.ArkUI.ArkUI.Full
126
127**Parameters**
128
129| Name| Type                                         | Mandatory| Description                                                        |
130| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ |
131| 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>} |
132
133## PickerTextStyle<sup>10+</sup>
134
135**Atomic service API**: This API can be used in atomic services since API version 11.
136
137| Name  | Type                                    | Mandatory  | Description                     |
138| ----- | ---------------------------------------- | ---- | ------------------------- |
139| color | [ResourceColor](ts-types.md#resourcecolor) | No   | Font color.                    |
140| font  | [Font](ts-types.md#font)                 | No   | Text style. Only the font size and font weight are supported. |
141
142## Events
143
144In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
145
146### onChange<sup>(deprecated)</sup>
147
148onChange(callback: (value: DatePickerResult) => void)
149
150Triggered when a date is selected.
151
152This API is supported since API version 8 and deprecated since API version 10. You are advised to use [onDateChange](#ondatechange10) instead.
153
154**System capability**: SystemCapability.ArkUI.ArkUI.Full
155
156**Parameters**
157
158| Name| Type                                         | Mandatory| Description            |
159| ------ | --------------------------------------------- | ---- | ---------------- |
160| value  | [DatePickerResult](#datepickerresult) | Yes  | Selected time.|
161
162### onDateChange<sup>10+</sup>
163
164onDateChange(callback: Callback\<Date>)
165
166Triggered when a date is selected.
167
168**Atomic service API**: This API can be used in atomic services since API version 11.
169
170**System capability**: SystemCapability.ArkUI.ArkUI.Full
171
172**Parameters**
173
174| Name| Type| Mandatory| Description                                                        |
175| ------ | ---- | ---- | ------------------------------------------------------------ |
176| callback  | [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**.|
177
178## DatePickerResult
179
180**Atomic service API**: This API can be used in atomic services since API version 11.
181
182**System capability**: SystemCapability.ArkUI.ArkUI.Full
183
184| Name | Type  | Read Only| Optional| Description                                      |
185| ----- | ------ | ---- | ---- | ------------------------------------------ |
186| year  | number | No  | No  | Year of the selected date.                            |
187| month | number | No  | No  | Month of the selected date. The value ranges from 0 to 11. The value **0** indicates January, and **11** indicates December.|
188| day   | number | No  | No  | Day of the selected date.                            |
189
190## Example
191
192This example implements a date picker that allows users to switch between the Gregorian (solar) calendar and the lunar calendar by clicking a button.
193
194
195```ts
196// xxx.ets
197@Entry
198@Component
199struct DatePickerExample {
200  @State isLunar: boolean = false
201  private selectedDate: Date = new Date('2021-08-08')
202
203  build() {
204    Column() {
205      Button('Switch Calendar')
206        .margin({ top: 30, bottom: 30 })
207        .onClick(() => {
208          this.isLunar = !this.isLunar
209        })
210      DatePicker({
211        start: new Date('1970-1-1'),
212        end: new Date('2100-1-1'),
213        selected: this.selectedDate
214      })
215        .disappearTextStyle({color: Color.Gray, font: {size: '16fp', weight: FontWeight.Bold}})
216        .textStyle({color: '#ff182431', font: {size: '18fp', weight: FontWeight.Normal}})
217        .selectedTextStyle({color: '#ff0000FF', font: {size: '26fp', weight: FontWeight.Regular, family: "HarmonyOS Sans", style: FontStyle.Normal}})
218        .lunar(this.isLunar)
219        .onDateChange((value: Date) => {
220          this.selectedDate = value
221          console.info('select current date is: ' + value.toString())
222        })
223
224    }.width('100%')
225  }
226}
227```
228
229![datePicker](figures/DatePickerApi10.gif)
230