1# DatePicker 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @luoying_ace_admin--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9滑动选择日期的组件。 10 11> **说明：** 12> 13> - 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> - 该组件不建议开发者在动效过程中修改属性数据。 16> 17> - 该组件最大显示行数在横竖屏模式下存在差异，竖屏为5行，横屏为3行。 18 19 20## 子组件 21 22无 23 24 25## 接口 26 27DatePicker(options?: DatePickerOptions) 28 29根据指定日期范围创建日期选择器。 30 31**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 32 33**系统能力：** SystemCapability.ArkUI.ArkUI.Full 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| ------- | ----------------------------------------------- | ---- | -------------------------- | 39| options | [DatePickerOptions](#datepickeroptions对象说明) | 否 | 配置日期选择器组件的参数。 | 40 41## DatePickerOptions对象说明 42 43日期选择器组件的参数说明。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| -------- | ---- | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 49| start | Date | 否 | 是 | 指定选择器的起始日期。<br/>默认值：Date('1970-1-1')<br/>取值范围：\[Date('1900-01-31'), Date('2100-12-31')]<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 50| end | Date | 否 | 是 | 指定选择器的结束日期。<br/>默认值：Date('2100-12-31')<br/>取值范围：\[Date('1900-01-31'), Date('2100-12-31')]<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| selected | Date | 否 | 是 | 设置选中项的日期。<br/>默认值：当前系统日期。<br/>取值范围：\[Date('1900-01-31'), Date('2100-12-31')]<br />从API version 10开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 52| mode<sup>18+</sup> | [DatePickerMode](#datepickermode18枚举说明) | 否 | 是 | 设置日期展示模式。<br/>默认值：DatePickerMode.DATE，显示年、月、日三列。<br/>在[DatePickerDialog](ts-methods-datepicker-dialog.md)中，当[DatePickerDialogOptions](ts-methods-datepicker-dialog.md#datepickerdialogoptions对象说明)的showTime设置为true时，此参数不生效，默认显示年、月、日三列。<br />**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 53 54> **说明：** 55> 56> - Date的使用请参考[TimePickerOptions](ts-basic-components-timepicker.md#timepickeroptions对象说明)。 57> 58> - 在DatePicker组件滑动过程中修改DatePickerOptions中的属性，会导致这些属性无法生效。 59 60**起始日期、结束日期和选中日期的异常情形说明：** 61 62| 异常情形 | 对应结果 | 63| -------- | ------------------------------------------------------------ | 64| 起始日期晚于结束日期，选中日期未设置。 | 起始日期、结束日期和选中日期都为默认值。 | 65| 起始日期晚于结束日期，选中日期早于起始日期默认值。 | 起始日期、结束日期都为默认值，选中日期为起始日期默认值。 | 66| 起始日期晚于结束日期，选中日期晚于结束日期默认值。 | 起始日期、结束日期都为默认值，选中日期为结束日期默认值。 | 67| 起始日期晚于结束日期，选中日期在起始日期与结束日期默认值范围内。 | 起始日期、结束日期都为默认值，选中日期为设置的值。 | 68| 选中日期早于起始日期。 | 选中日期为起始日期。 | 69| 选中日期晚于结束日期。 | 选中日期为结束日期。 | 70| 起始日期晚于当前系统日期，选中日期未设置。 | 选中日期为起始日期。 | 71| 结束日期早于当前系统日期，选中日期未设置。 | 选中日期为结束日期。 | 72| 日期格式不符合规范，如‘1999-13-32’。 | 取默认值。 | 73| 起始日期或结束日期早于系统有效范围。 | 起始日期或结束日期取起始日期默认值。 | 74| 起始日期或结束日期晚于系统有效范围。 | 起始日期或结束日期取结束日期默认值。 | 75| 起始日期与结束日期同时早于系统有效范围。 | 起始日期与结束日期取系统有效范围最早日期。 | 76| 起始日期与结束日期同时晚于系统有效范围。 | 起始日期与结束日期取系统有效范围最晚日期。 | 77 78> **说明：** 79> 80> 先处理起始日期与结束日期的异常情形，再处理选中日期的异常情形。 81 82## DatePickerMode<sup>18+</sup>枚举说明 83 84设置日期展示模式。 85 86**原子化服务API：** 从API version 18开始，该类型支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90| 名称 | 值 | 说明 | 91| -------- | - |-------- | 92| DATE | 0 | 显示年、月、日三列。| 93| YEAR_AND_MONTH | 1 | 显示年、月二列。| 94| MONTH_AND_DAY | 2 | 显示月、日二列。<br/>在此模式下，年份始终保持不变。| 95 96## 属性 97 98除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 99 100### lunar 101 102lunar(value: boolean) 103 104设置日期是否显示为农历。 105 106**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.ArkUI.ArkUI.Full 109 110**参数：** 111 112| 参数名 | 类型 | 必填 | 说明 | 113| ------ | ------- | ---- | ------------------------------------------------------------ | 114| value | boolean | 是 | 日期是否显示为农历。<br/>- true：显示为农历。<br/>- false：不显示为农历。<br/>默认值：false | 115 116### lunar<sup>18+</sup> 117 118lunar(isLunar: Optional\<boolean>) 119 120设置弹窗的日期是否显示为农历。与[lunar](#lunar)相比，isLunar参数新增了对undefined类型的支持。 121 122**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ------- | ---- | ------------------------------------------------------------ | 130| isLunar | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 日期是否显示为农历。<br/>- true：显示为农历。<br/>- false：不显示为农历。<br/>默认值：false<br/>当isLunar的值为undefined时，使用默认值。 | 131 132### disappearTextStyle<sup>10+</sup> 133 134disappearTextStyle(value: PickerTextStyle) 135 136设置边缘项（以选中项为基准向上或向下的第二项）的文本样式。 137 138**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 139 140**系统能力：** SystemCapability.ArkUI.ArkUI.Full 141 142**参数：** 143 144| 参数名 | 类型 | 必填 | 说明 | 145| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 146| value | [PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明) | 是 | 边缘项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '14fp', <br/>weight: FontWeight.Regular<br/>}<br/>} | 147 148> **说明：** 149> 150> 若选中项向上或向下的可视项数低于两项则无对应边缘项。 151 152### disappearTextStyle<sup>18+</sup> 153 154disappearTextStyle(style: Optional\<PickerTextStyle>) 155 156设置边缘项（以选中项为基准向上或向下的第二项）的文本样式。与[disappearTextStyle<sup>10+</sup>](#disappeartextstyle10)相比，style参数新增了对undefined类型的支持。 157 158**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 159 160**系统能力：** SystemCapability.ArkUI.ArkUI.Full 161 162**参数：** 163 164| 参数名 | 类型 | 必填 | 说明 | 165| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 166| style | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明)> | 是 | 边缘项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '14fp', <br/>weight: FontWeight.Regular<br/>}<br/>}<br/>当style的值为undefined时，使用默认值。 | 167 168> **说明：** 169> 170> 若选中项向上或向下的可视项数低于两项则无对应边缘项。 171 172### textStyle<sup>10+</sup> 173 174textStyle(value: PickerTextStyle) 175 176设置待选项（以选中项为基准向上或向下的第一项）的文本样式。 177 178**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 179 180**系统能力：** SystemCapability.ArkUI.ArkUI.Full 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 186| value | [PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明) | 是 | 待选项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '16fp', <br/>weight: FontWeight.Regular<br/>}<br/>} | 187 188> **说明：** 189> 190> 若选中项向上或向下可视项数低于一项则无对应待选项。 191 192### textStyle<sup>18+</sup> 193 194textStyle(style: Optional\<PickerTextStyle>) 195 196设置待选项（以选中项为基准向上或向下的第一项）的文本样式。与[textStyle<sup>10+</sup>](#textstyle10)相比，style参数新增了对undefined类型的支持。 197 198**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 199 200**系统能力：** SystemCapability.ArkUI.ArkUI.Full 201 202**参数：** 203 204| 参数名 | 类型 | 必填 | 说明 | 205| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 206| style | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明)> | 是 | 待选项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '16fp', <br/>weight: FontWeight.Regular<br/>}<br/>}<br/>当style的值为undefined时，使用默认值。 | 207 208> **说明：** 209> 210> 若选中项向上或向下可视项数低于一项则无对应待选项。 211 212### selectedTextStyle<sup>10+</sup> 213 214selectedTextStyle(value: PickerTextStyle) 215 216设置选中项的文本样式。 217 218**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 219 220**系统能力：** SystemCapability.ArkUI.ArkUI.Full 221 222**参数：** 223 224| 参数名 | 类型 | 必填 | 说明 | 225| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 226| value | [PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明) | 是 | 选中项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20fp', <br/>weight: FontWeight.Medium<br/>}<br/>} | 227 228### selectedTextStyle<sup>18+</sup> 229 230selectedTextStyle(style: Optional\<PickerTextStyle>) 231 232设置选中项的文本样式。与[selectedTextStyle<sup>10+</sup>](#selectedtextstyle10)相比，style参数新增了对undefined类型的支持。 233 234**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 242| style | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明)> | 是 | 选中项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20fp', <br/>weight: FontWeight.Medium<br/>}<br/>}<br/>当style的值为undefined时，使用默认值。 | 243 244### enableHapticFeedback<sup>18+</sup> 245 246enableHapticFeedback(enable: Optional\<boolean>) 247 248设置是否开启触控反馈。 249 250**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 251 252**系统能力：** SystemCapability.ArkUI.ArkUI.Full 253 254**参数：** 255 256| 参数名 | 类型 | 必填 | 说明 | 257| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------| 258| enable | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 设置是否开启触控反馈。<br/>- true：开启触控反馈。<br/>- false：不开启触控反馈。<br/>默认值：true<br/>设置为true后，其生效情况取决于系统的硬件是否支持。<br/>当enable的值为undefined时，使用默认值。| 259 260> **说明：** 261> 262> 开启触控反馈时，需要在工程的src/main/module.json5文件的"module"内配置requestPermissions字段开启振动权限，配置如下： 263> ```json 264> "requestPermissions": [ 265> { 266> "name": "ohos.permission.VIBRATE", 267> } 268> ] 269> ``` 270 271### digitalCrownSensitivity<sup>18+</sup> 272digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 273 274设置表冠灵敏度。 275 276**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 277 278**系统能力：** SystemCapability.ArkUI.ArkUI.Full 279 280**参数：** 281 282| 参数名 | 类型 | 必填 | 说明 | 283| ----- | ---------------------------------------- | ---- | ------------------------- | 284| sensitivity | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[CrownSensitivity](ts-appendix-enums.md#crownsensitivity18)> | 是 | 表冠响应灵敏度。<br/>默认值：CrownSensitivity.MEDIUM，响应速度适中。 | 285 286> **说明：** 287> 288> 用于穿戴设备圆形屏幕使用。组件响应[表冠事件](ts-universal-events-crown.md)，需要先获取焦点。 289 290### canLoop<sup>20+</sup> 291 292canLoop(isLoop: Optional\<boolean>) 293 294设置是否可循环滚动。 295 296**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 297 298**系统能力：** SystemCapability.ArkUI.ArkUI.Full 299 300**参数：** 301 302| 参数名 | 类型 | 必填 | 说明 | 303| ------ | ------- | ---- | ------------------------------------------------------------ | 304| isLoop | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 是否可循环滚动。<br/>- true：可循环滚动，年份随着月份的循环滚动进行联动加减，月份随着日的循环滚动进行联动加减。<br/>- false：不可循环滚动，年、月、日到达本列的顶部或底部时，无法再进行滚动，年、月、日之间也无法再联动加减。<br/>默认值：true<br/>当isLoop的值为undefined时，使用默认值。 | 305 306## 事件 307 308除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 309 310### onChange<sup>(deprecated)</sup> 311 312onChange(callback: (value: DatePickerResult) => void) 313 314选择日期时触发该事件。不能通过双向绑定的状态变量触发。 315 316从API version 8 开始支持，从 API version 10 开始废弃，建议使用[onDateChange](#ondatechange10)。 317 318**系统能力：** SystemCapability.ArkUI.ArkUI.Full 319 320**参数：** 321 322| 参数名 | 类型 | 必填 | 说明 | 323| ------ | --------------------------------------------- | ---- | ---------------- | 324| callback | (value: [DatePickerResult](#datepickerresult对象说明)) => void | 是 | 返回选中的时间。 | 325 326### onDateChange<sup>10+</sup> 327 328onDateChange(callback: Callback\<Date>) 329 330选择日期时触发该事件。不能通过双向绑定的状态变量触发。 331 332**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 333 334**系统能力：** SystemCapability.ArkUI.ArkUI.Full 335 336**参数：** 337 338| 参数名 | 类型 | 必填 | 说明 | 339| ------ | ---- | ---- | ------------------------------------------------------------ | 340| callback | [Callback](ts-types.md#callback12)\<Date> | 是 | 返回选中的时间，年、月、日为选中的日期，时、分取决于当前系统时间的时、分，秒恒为00。 | 341 342### onDateChange<sup>18+</sup> 343 344onDateChange(callback: Optional\<Callback\<Date>>) 345 346选择日期时触发该事件。不能通过双向绑定的状态变量触发。与[onDateChange<sup>10+</sup>](#ondatechange10)相比，callback参数新增了对undefined类型的支持。 347 348**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 349 350**系统能力：** SystemCapability.ArkUI.ArkUI.Full 351 352**参数：** 353 354| 参数名 | 类型 | 必填 | 说明 | 355| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 356| callback | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[Callback](ts-types.md#callback12)\<Date>> | 是 | 返回选中的时间，年、月、日为选中的日期，时、分取决于当前系统时间的时、分，秒恒为00。<br/>当callback的值为undefined时，不使用回调函数。 | 357 358## DatePickerResult对象说明 359 360日期选择器返回的时间格式。 361 362**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 363 364**系统能力：** SystemCapability.ArkUI.ArkUI.Full 365 366| 名称 | 类型 | 只读 | 可选 | 说明 | 367| ----- | ------ | ---- | ---- | ------------------------------------------ | 368| year | number | 否 | 是 | 选中日期的年。<br/>取值范围：与设置的start、end有关，如果没有设置start、end，取值范围为[1970, 2100]。 | 369| month | number | 否 | 是 | 选中日期的月的索引值，索引从0开始，0表示1月，11表示12月。<br/>取值范围：与设置的start、end有关，如果没有设置start、end，取值范围为[0, 11]。 | 370| day | number | 否 | 是 | 选中日期的日。<br/>取值范围：与设置的start、end有关，如果没有设置start、end，取值范围为[1, 31]。 | 371 372## 示例 373 374### 示例1（切换公历农历） 375 376该示例实现了日期选择器组件，点击按钮可以切换公历农历。 377 378 379```ts 380// xxx.ets 381@Entry 382@Component 383struct DatePickerExample { 384 @State isLunar: boolean = false; 385 private selectedDate: Date = new Date('2021-08-08'); 386 387 build() { 388 Column() { 389 Button('切换公历农历') 390 .margin({ top: 30, bottom: 30 }) 391 .onClick(() => { 392 this.isLunar = !this.isLunar; 393 }) 394 DatePicker({ 395 start: new Date('1970-1-1'), 396 end: new Date('2100-1-1'), 397 selected: this.selectedDate 398 }) 399 .lunar(this.isLunar) 400 .onDateChange((value: Date) => { 401 this.selectedDate = value; 402 console.info('select current date is: ' + value.toString()); 403 }) 404 405 }.width('100%') 406 } 407} 408``` 409 410 411 412### 示例2（设置文本样式） 413 414该示例通过配置[disappearTextStyle](#disappeartextstyle10)、[textStyle](#textstyle10)、[selectedTextStyle](#selectedtextstyle10)设置文本样式。 415 416```ts 417// xxx.ets 418@Entry 419@Component 420struct DatePickerExample { 421 private selectedDate: Date = new Date('2021-08-08'); 422 423 build() { 424 Column() { 425 DatePicker({ 426 start: new Date('1970-1-1'), 427 end: new Date('2100-1-1'), 428 selected: this.selectedDate 429 }) 430 .disappearTextStyle({ color: Color.Gray, font: { size: '16fp', weight: FontWeight.Bold } }) 431 .textStyle({ color: '#ff182431', font: { size: '18fp', weight: FontWeight.Normal } }) 432 .selectedTextStyle({ color: '#ff0000FF', font: { size: '26fp', weight: FontWeight.Regular, family: "HarmonyOS Sans", style: FontStyle.Normal } }) 433 .onDateChange((value: Date) => { 434 this.selectedDate = value; 435 console.info('select current date is: ' + value.toString()); 436 }) 437 438 }.width('100%') 439 } 440} 441``` 442 443 444 445### 示例3（设置显示年、月和月、日列） 446 447该示例通过配置mode参数实现显示年、月和月、日列。 448 449```ts 450// xxx.ets 451@Entry 452@Component 453struct DatePickerExample { 454 @State isLunar: boolean = false; 455 private selectedDate: Date = new Date('2025-01-15'); 456 @State datePickerModeList: (DatePickerMode)[] = [ 457 DatePickerMode.DATE, 458 DatePickerMode.YEAR_AND_MONTH, 459 DatePickerMode.MONTH_AND_DAY, 460 ]; 461 @State datePickerModeIndex: number = 0; 462 463 build() { 464 Column() { 465 Button('切换公历农历') 466 .margin({ top: 30, bottom: 30 }) 467 .onClick(() => { 468 this.isLunar = !this.isLunar; 469 }) 470 DatePicker({ 471 start: new Date('1970-1-1'), 472 end: new Date('2100-1-1'), 473 selected: this.selectedDate, 474 mode:this.datePickerModeList[this.datePickerModeIndex] 475 }) 476 .lunar(this.isLunar) 477 .onDateChange((value: Date) => { 478 this.selectedDate = value; 479 console.info('select current date is: ' + value.toString()); 480 }) 481 482 Button('mode :' + this.datePickerModeIndex).margin({ top: 20 }) 483 .onClick(() => { 484 this.datePickerModeIndex++; 485 if(this.datePickerModeIndex >= this.datePickerModeList.length){ 486 this.datePickerModeIndex = 0; 487 } 488 }) 489 }.width('100%') 490 } 491} 492``` 493 494 495### 示例4（设置循环滚动） 496 497从API version 20开始，可以通过配置[canLoop](#canloop20)参数设置DatePicker是否循环滚动。 498 499```ts 500// xxx.ets 501@Entry 502@Component 503struct DatePickerExample { 504 @State isLoop: boolean = true; 505 selectedDate: Date = new Date("2010-1-1"); 506 507 build() { 508 Column() { 509 DatePicker({ 510 start: new Date("2000-1-1"), 511 end: new Date("2100-12-31"), 512 selected: this.selectedDate, 513 }) 514 .canLoop(this.isLoop) 515 .onDateChange((value: Date) => { 516 console.info("DatePicker:onDateChange()" + value.toString()); 517 }) 518 519 Row() { 520 Text('循环滚动').fontSize(20) 521 Toggle({ type: ToggleType.Switch, isOn: true }) 522 .onChange((isOn: boolean) => { 523 this.isLoop = isOn; 524 }) 525 }.position({ x: '60%', y: '40%' }) 526 }.width('100%') 527 } 528} 529``` 530 531
