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)                 | 否    | 文本样式，picker只支持字号、字体粗细的设置。 |
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```ts
195// xxx.ets
196@Entry
197@Component
198struct DatePickerExample {
199  @State isLunar: boolean = false
200  private selectedDate: Date = new Date('2021-08-08')
201
202  build() {
203    Column() {
204      Button('切换公历农历')
205        .margin({ top: 30, bottom: 30 })
206        .onClick(() => {
207          this.isLunar = !this.isLunar
208        })
209      DatePicker({
210        start: new Date('1970-1-1'),
211        end: new Date('2100-1-1'),
212        selected: this.selectedDate
213      })
214        .disappearTextStyle({color: Color.Gray, font: {size: '16fp', weight: FontWeight.Bold}})
215        .textStyle({color: '#ff182431', font: {size: '18fp', weight: FontWeight.Normal}})
216        .selectedTextStyle({color: '#ff0000FF', font: {size: '26fp', weight: FontWeight.Regular}})
217        .lunar(this.isLunar)
218        .onDateChange((value: Date) => {
219          this.selectedDate = value
220          console.info('select current date is: ' + value.toString())
221        })
222
223    }.width('100%')
224  }
225}
226```
227
228![datePicker](figures/DatePickerApi10.gif)
229