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开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。 | 42| mode<sup>18+</sup> | [DatePickerMode](#datepickermode18枚举说明) | 否 | 设置DatePicker显示的日期选项列。<br/>默认值：DatePickerMode.DATE，日期列显示年、月、日三列。 小数值做取整处理。<br/>在DatePickerDialog中，当showTime=true时，此参数不生效，显示默认年月日三列。 | 43 44> **说明：** 45> 46> Date的使用请参考[TimePickerOptions](ts-basic-components-timepicker.md)。 47> 在DatePicker组件滑动过程中修改DatePickerOptions中的属性（start、end、selected）,会导致这些属性无法生效。 48 49 50## DatePickerMode<sup>18+</sup>枚举说明 51 52设置要显示的日期选项列。 53 54**原子化服务API：** 从API version 18开始，该类型支持在原子化服务中使用。 55 56**系统能力：** SystemCapability.ArkUI.ArkUI.Full 57 58| 名称 | 说明 | 59| -------- | -------- | 60| DATE | 日期列显示年、月、日三列。| 61| YEAR_AND_MONTH | 日期列显示年、月二列。| 62| MONTH_AND_DAY | 日期列显示月、日二列。<br/>此模式下，如果月份从12月变化到1月，年份不增加1年；如果月份从1月变化到12月，年份不减少1年；年份始终在当前设置的年份。| 63 64**异常情形说明：** 65 66| 异常情形 | 对应结果 | 67| -------- | ------------------------------------------------------------ | 68| 起始日期晚于结束日期，选中日期未设置 | 起始日期、结束日期和选中日期都为默认值 | 69| 起始日期晚于结束日期，选中日期早于起始日期默认值 | 起始日期、结束日期都为默认值，选中日期为起始日期默认值 | 70| 起始日期晚于结束日期，选中日期晚于结束日期默认值 | 起始日期、结束日期都为默认值，选中日期为结束日期默认值 | 71| 起始日期晚于结束日期，选中日期在起始日期与结束日期默认值范围内 | 起始日期、结束日期都为默认值，选中日期为设置的值 | 72| 选中日期早于起始日期 | 选中日期为起始日期 | 73| 选中日期晚于结束日期 | 选中日期为结束日期 | 74| 起始日期晚于当前系统日期，选中日期未设置 | 选中日期为起始日期 | 75| 结束日期早于当前系统日期，选中日期未设置 | 选中日期为结束日期 | 76| 日期格式不符合规范，如‘1999-13-32’ | 取默认值 | 77| 起始日期或结束日期早于系统有效范围 | 起始日期或结束日期取起始日期默认值 | 78| 起始日期或结束日期晚于系统有效范围 | 起始日期或结束日期取结束日期默认值 | 79| 起始日期与结束日期同时早于系统有效范围 | 起始日期与结束日期取系统有效范围最早日期 | 80| 起始日期与结束日期同时晚于系统有效范围 | 起始日期与结束日期取系统有效范围最晚日期 | 81 82系统日期范围：1900-1-31 ~ 2100-12-31 83 84选中日期会在起始日期与结束日期异常处理完成后再进行异常情形判断处理 85 86## 属性 87 88除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 89 90### lunar 91 92lunar(value: boolean) 93 94设置弹窗的日期是否显示农历。 95 96**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 97 98**系统能力：** SystemCapability.ArkUI.ArkUI.Full 99 100**参数：** 101 102| 参数名 | 类型 | 必填 | 说明 | 103| ------ | ------- | ---- | ------------------------------------------------------------ | 104| value | boolean | 是 | 日期是否显示农历。<br/>- true：展示农历。<br/>- false：不展示农历。<br/>默认值：false | 105 106### lunar<sup>18+</sup> 107 108lunar(isLunar: Optional\<boolean>) 109 110设置弹窗的日期是否显示农历。与[lunar](#lunar)相比，isLunar参数新增了对undefined类型的支持。 111 112**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 113 114**系统能力：** SystemCapability.ArkUI.ArkUI.Full 115 116**参数：** 117 118| 参数名 | 类型 | 必填 | 说明 | 119| ------ | ------- | ---- | ------------------------------------------------------------ | 120| isLunar | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 日期是否显示农历。<br/>- true：展示农历。<br/>- false：不展示农历。<br/>当isLunar的值为undefined时，默认值：false | 121 122### disappearTextStyle<sup>10+</sup> 123 124disappearTextStyle(value: PickerTextStyle) 125 126设置所有选项中最上和最下两个选项的文本样式。 127 128**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 129 130**系统能力：** SystemCapability.ArkUI.ArkUI.Full 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 136| value | [PickerTextStyle](#pickertextstyle10类型说明) | 是 | 所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。<br/>默认值：<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 142设置所有选项中最上和最下两个选项的文本样式。与[disappearTextStyle](#disappeartextstyle10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 143 144**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 145 146**系统能力：** SystemCapability.ArkUI.ArkUI.Full 147 148**参数：** 149 150| 参数名 | 类型 | 必填 | 说明 | 151| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 152| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](#pickertextstyle10类型说明)> | 是 | 所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。<br/>当style的值为undefined时，默认值：<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 158设置所有选项中除了最上、最下及选中项以外的文本样式。 159 160**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 161 162**系统能力：** SystemCapability.ArkUI.ArkUI.Full 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 168| value | [PickerTextStyle](#pickertextstyle10类型说明) | 是 | 所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。<br/>默认值：<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 174设置所有选项中除了最上、最下及选中项以外的文本样式。与[textStyle](#textstyle10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 175 176**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 177 178**系统能力：** SystemCapability.ArkUI.ArkUI.Full 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 184| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](#pickertextstyle10类型说明)> | 是 | 所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。<br/>当style的值为undefined时，默认值：<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 190设置选中项的文本样式。 191 192**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 193 194**系统能力：** SystemCapability.ArkUI.ArkUI.Full 195 196**参数：** 197 198| 参数名 | 类型 | 必填 | 说明 | 199| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 200| value | [PickerTextStyle](#pickertextstyle10类型说明) | 是 | 选中项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20fp', <br/>weight: FontWeight.Medium<br/>}<br/>} | 201 202### selectedTextStyle<sup>18+</sup> 203 204selectedTextStyle(style: Optional\<PickerTextStyle>) 205 206设置选中项的文本样式。与[selectedTextStyle](#selectedtextstyle10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 207 208**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 209 210**系统能力：** SystemCapability.ArkUI.ArkUI.Full 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 216| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[PickerTextStyle](#pickertextstyle10类型说明)> | 是 | 选中项的文本颜色、字号、字体粗细。<br/>当style的值为undefined时，默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20fp', <br/>weight: FontWeight.Medium<br/>}<br/>} | 217 218### enableHapticFeedback<sup>18+</sup> 219 220enableHapticFeedback(enable: Optional\<boolean>) 221 222设置是否开启触控反馈。 223 224**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 225 226**系统能力：** SystemCapability.ArkUI.ArkUI.Full 227 228| 参数名 | 类型 | 必填 | 说明 | 229| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------| 230| enable | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 设置是否开启触控反馈。<br/>默认值：true，true表示开启触控反馈，false表示不开启触控反馈。| 231 232> **说明：** 233> 234> 开启触控反馈时，需要在工程的module.json5中配置requestPermissions字段开启振动权限，配置如下： 235> ```json 236> "requestPermissions": [ 237> { 238> "name": "ohos.permission.VIBRATE", 239> } 240> ] 241> ``` 242 243### digitalCrownSensitivity<sup>18+</sup> 244digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 245 246设置表冠灵敏度。 247 248**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 249 250**系统能力：** SystemCapability.ArkUI.ArkUI.Full 251 252| 参数名 | 参数类型 | 必填 | 参数描述 | 253| ----- | ---------------------------------------- | ---- | ------------------------- | 254| sensitivity | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CrownSensitivity](ts-appendix-enums.md#crownsensitivity18)> | 是 | 表冠灵敏度。 | 255 256> **说明：** 257> 258> 用于穿戴设备圆形屏幕使用。 259 260## PickerTextStyle<sup>10+</sup>类型说明 261 262**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 263 264| 参数名 | 参数类型 | 必填 | 参数描述 | 265| ----- | ---------------------------------------- | ---- | ------------------------- | 266| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 文本颜色。 | 267| font | [Font](ts-types.md#font) | 否 | 文本样式。 | 268 269## 事件 270 271除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 272 273### onChange<sup>(deprecated)</sup> 274 275onChange(callback: (value: DatePickerResult) => void) 276 277选择日期时触发该事件。 278 279从API version 8 开始支持，从 API version 10 开始废弃，建议使用[onDateChange](#ondatechange10)。 280 281**系统能力：** SystemCapability.ArkUI.ArkUI.Full 282 283**参数：** 284 285| 参数名 | 类型 | 必填 | 说明 | 286| ------ | --------------------------------------------- | ---- | ---------------- | 287| value | [DatePickerResult](#datepickerresult对象说明) | 是 | 返回选中的时间。 | 288 289### onDateChange<sup>10+</sup> 290 291onDateChange(callback: (value: Date) => void) 292 293选择日期时触发该事件。 294 295**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 296 297**系统能力：** SystemCapability.ArkUI.ArkUI.Full 298 299**参数：** 300 301| 参数名 | 类型 | 必填 | 说明 | 302| ------ | ---- | ---- | ------------------------------------------------------------ | 303| value | Date | 是 | 返回选中的时间，年月日为选中的日期，时分取决于当前系统时间的时分，秒恒为00。 | 304 305### onDateChange<sup>18+</sup> 306 307onDateChange(callback: Optional\<Callback\<Date>>) 308 309选择日期时触发该事件。与[onDateChange](#ondatechange10)<sup>10+</sup>相比，callback参数新增了对undefined类型的支持。 310 311**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 312 313**系统能力：** SystemCapability.ArkUI.ArkUI.Full 314 315**参数：** 316 317| 参数名 | 类型 | 必填 | 说明 | 318| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 319| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[Callback](ts-types.md#callback12)\<Date>> | 是 | 返回选中的时间，年月日为选中的日期，时分取决于当前系统时间的时分，秒恒为00。<br/>当callback的值为undefined时，不使用回调函数。 | 320 321## DatePickerResult对象说明 322 323**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 324 325**系统能力：** SystemCapability.ArkUI.ArkUI.Full 326 327| 名称 | 类型 | 只读 | 可选 | 说明 | 328| ----- | ------ | ---- | ---- | ------------------------------------------ | 329| year | number | 否 | 否 | 选中日期的年。<br/>取值范围：与start、end有关，如果没有设置start、end，则取start、end默认值[1970， 2100]。 | 330| month | number | 否 | 否 | 选中日期的月的索引值，索引从0开始，0表示1月，11表示12月。<br/>取值范围：与start、end有关，如果没有设置start、end，取值范围为[0， 11]。 | 331| day | number | 否 | 否 | 选中日期的日。<br/>取值范围：与start、end有关，如果没有设置start、end，取值范围为[1， 31]。 | 332 333## 示例 334 335### 示例1（切换公历农历） 336 337该示例实现了日期选择器组件，点击按钮可以切换公历农历。 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('切换公历农历') 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### 示例2（设置文本样式） 374 375该示例通过配置disappearTextStyle、textStyle、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### 示例3（设置显示年、月和月、日列） 407 408该示例通过配置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('切换公历农历') 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
