1# DatePicker
2
3日期选择器组件，用于根据指定日期范围创建日期滑动选择器。
4
5>  **说明：**
6>
7>  该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8
9
10## 子组件
11
12无
13
14
15## 接口
16
17DatePicker(options?: DatePickerOptions)
18
19根据指定范围的Date创建可以选择日期的滑动选择器。
20
21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
22
23**系统能力：** SystemCapability.ArkUI.ArkUI.Full
24
25**参数：**
26
27| 参数名  | 类型                                            | 必填 | 说明                       |
28| ------- | ----------------------------------------------- | ---- | -------------------------- |
29| options | [DatePickerOptions](#datepickeroptions对象说明) | 否   | 配置日期选择器组件的参数。 |
30
31## DatePickerOptions对象说明
32
33**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
34
35**系统能力：** SystemCapability.ArkUI.ArkUI.Full
36
37| 名称     | 类型 | 必填 | 说明                                                         |
38| -------- | ---- | ---- | ------------------------------------------------------------ |
39| start    | Date | 否   | 指定选择器的起始日期。<br/>默认值：Date('1970-1-1')          |
40| end      | Date | 否   | 指定选择器的结束日期。<br/>默认值：Date('2100-12-31')        |
41| selected | Date | 否   | 设置选中项的日期。<br/>默认值：当前系统日期<br />从API version 10开始，该参数支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 |
42
43**异常情形说明:**
44
45| 异常情形   | 对应结果  |
46| -------- |  ------------------------------------------------------------ |
47| 起始日期晚于结束日期，选中日期未设置    | 起始日期、结束日期和选中日期都为默认值  |
48| 起始日期晚于结束日期，选中日期早于起始日期默认值    | 起始日期、结束日期都为默认值，选中日期为起始日期默认值  |
49| 起始日期晚于结束日期，选中日期晚于结束日期默认值    | 起始日期、结束日期都为默认值，选中日期为结束日期默认值  |
50| 起始日期晚于结束日期，选中日期在起始日期与结束日期默认值范围内    | 起始日期、结束日期都为默认值，选中日期为设置的值 |
51| 选中日期早于起始日期    | 选中日期为起始日期  |
52| 选中日期晚于结束日期    | 选中日期为结束日期  |
53| 起始日期晚于当前系统日期，选中日期未设置    | 选中日期为起始日期  |
54| 结束日期早于当前系统日期，选中日期未设置    | 选中日期为结束日期  |
55| 日期格式不符合规范，如‘1999-13-32’   | 取默认值  |
56| 起始日期或结束日期早于系统有效范围    | 起始日期或结束日期取起始日期默认值 |
57| 起始日期或结束日期晚于系统有效范围    | 起始日期或结束日期取结束日期默认值 |
58| 起始日期与结束日期同时早于系统有效范围 | 起始日期与结束日期取系统有效范围最早日期 |
59| 起始日期与结束日期同时晚于系统有效范围 | 起始日期与结束日期取系统有效范围最晚日期 |
60
61系统日期范围：1900-1-31 ~ 2100-12-31
62
63选中日期会在起始日期与结束日期异常处理完成后再进行异常情形判断处理
64
65## 属性
66
67除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
68
69### lunar
70
71lunar(value: boolean)
72
73设置弹窗的日期是否显示农历。
74
75**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
76
77**系统能力：** SystemCapability.ArkUI.ArkUI.Full
78
79**参数：**
80
81| 参数名 | 类型    | 必填 | 说明                                                         |
82| ------ | ------- | ---- | ------------------------------------------------------------ |
83| value  | boolean | 是   | 日期是否显示农历。<br/>-&nbsp;true：展示农历。<br/>-&nbsp;false：不展示农历。<br/>默认值：false |
84
85### disappearTextStyle<sup>10+</sup>
86
87disappearTextStyle(value: PickerTextStyle)
88
89设置所有选项中最上和最下两个选项的文本样式。
90
91**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
92
93**系统能力：** SystemCapability.ArkUI.ArkUI.Full
94
95**参数：**
96
97| 参数名 | 类型                                          | 必填 | 说明                                                         |
98| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ |
99| value  | [PickerTextStyle](#pickertextstyle10类型说明) | 是   | 所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。<br/>默认值：<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
105设置所有选项中除了最上、最下及选中项以外的文本样式。
106
107**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
108
109**系统能力：** SystemCapability.ArkUI.ArkUI.Full
110
111**参数：**
112
113| 参数名 | 类型                                          | 必填 | 说明                                                         |
114| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ |
115| value  | [PickerTextStyle](#pickertextstyle10类型说明) | 是   | 所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。<br/>默认值：<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
121设置选中项的文本样式。
122
123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
124
125**系统能力：** SystemCapability.ArkUI.ArkUI.Full
126
127**参数：**
128
129| 参数名 | 类型                                          | 必填 | 说明                                                         |
130| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ |
131| value  | [PickerTextStyle](#pickertextstyle10类型说明) | 是   | 选中项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20vp', <br/>weight: FontWeight.Medium<br/>}<br/>} |
132
133## PickerTextStyle<sup>10+</sup>类型说明
134
135**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
136
137| 参数名   | 参数类型                                     | 必填   | 参数描述                      |
138| ----- | ---------------------------------------- | ---- | ------------------------- |
139| color | [ResourceColor](ts-types.md#resourcecolor) | 否    | 文本颜色。                     |
140| font  | [Font](ts-types.md#font)                 | 否    | 文本样式。 |
141
142## 事件
143
144除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件：
145
146### onChange<sup>(deprecated)</sup>
147
148onChange(callback: (value: DatePickerResult) => void)
149
150选择日期时触发该事件。
151
152从API version 8 开始支持，从 API version 10 开始废弃，建议使用[onDateChange](#ondatechange10)。
153
154**系统能力：** SystemCapability.ArkUI.ArkUI.Full
155
156**参数：**
157
158| 参数名 | 类型                                          | 必填 | 说明             |
159| ------ | --------------------------------------------- | ---- | ---------------- |
160| value  | [DatePickerResult](#datepickerresult对象说明) | 是   | 返回选中的时间。 |
161
162### onDateChange<sup>10+</sup>
163
164onDateChange(callback: Callback\<Date>)
165
166选择日期时触发该事件。
167
168**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
169
170**系统能力：** SystemCapability.ArkUI.ArkUI.Full
171
172**参数：**
173
174| 参数名   | 类型                                      | 必填 | 说明                                                         |
175| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
176| callback | [Callback](ts-types.md#callback12)\<Date> | 是   | 返回选中的时间，年月日为选中的日期，时分取决于当前系统时间的时分，秒恒为00。 |
177
178## DatePickerResult对象说明
179
180**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
181
182**系统能力：** SystemCapability.ArkUI.ArkUI.Full
183
184| 名称  | 类型   | 只读 | 可选 | 说明                                       |
185| ----- | ------ | ---- | ---- | ------------------------------------------ |
186| year  | number | 否   | 否   | 选中日期的年。                             |
187| month | number | 否   | 否   | 选中日期的月(0~11)，0表示1月，11表示12月。 |
188| day   | number | 否   | 否   | 选中日期的日。                             |
189
190## 示例
191
192该示例实现了日期选择器组件，点击按钮可以切换公历农历。
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('切换公历农历')
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