1# TimePicker 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 27TimePicker(options?: TimePickerOptions) 28 29创建滑动选择器，默认使用24小时的时间区间。 30 31**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 32 33**系统能力：** SystemCapability.ArkUI.ArkUI.Full 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| ------- | ----------------------------------------------- | ---- | ------------------------ | 39| options | [TimePickerOptions](#timepickeroptions对象说明) | 否 | 配置时间选择组件的参数。 | 40 41## TimePickerOptions对象说明 42 43时间选择器组件的参数说明。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| -------------------- | ----------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | 49| selected | Date | 否 | 是 | 设置选中项的时间。<br/>默认值：当前系统时间<br />从API version 10开始，该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 50| format<sup>11+</sup> | [TimePickerFormat](#timepickerformat11枚举说明) | 否 | 是 | 指定需要显示的TimePicker的格式。<br/>默认值：TimePickerFormat.HOUR_MINUTE <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 51| start<sup>18+</sup> | Date | 否 | 是 | 指定时间选择组件的起始时间。<br/>默认值：Date(0, 0, 0, 0, 0, 0)<br/>**说明：**<br/>1. 仅设置的小时和分钟生效。<br/>2. 设置了start且为非默认值的场景下，loop不生效。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 52| end<sup>18+</sup> | Date | 否 | 是 | 指定时间选择组件的结束时间。<br/>默认值：Date(0, 0, 0, 23, 59, 59)<br/>**说明：**<br/>1. 仅设置的小时和分钟生效。<br/>2. 设置了end且为非默认值的场景下，loop不生效。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 53 54> **说明：** 55> 56> - 在TimePicker组件滑动过程中修改TimePickerOptions中的属性，会导致这些属性无法生效。 57> 58> - Date对象用于处理日期和时间，使用方式如下。 59> 60> **方式1：** new Date() 61> 62> 获取系统当前日期和时间。 63> 64> **方式2：** new Date(value: number | string) 65> 66> | 参数名 | 类型 | 必填 | 说明 | 67> | ------- | ------ | ---- | ------ | 68> | value | number \| string | 是 | 设置日期格式。<br/>number：毫秒，自1970年1月1日 00:00:00以来的毫秒数。<br/>string：时间格式的字符串，如‘2025-02-20 08:00:00’或‘2025-02-20T08:00:00’。| 69> 70> **方式3：** new Date(year: number, monthIndex: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number) 71> 72> | 参数名 | 类型 | 必填 | 说明 | 73> | --------| ------ | ---- | ------ | 74> | year | number | 是 | 设置年份，例如2025。| 75> | monthIndex | number | 是 | 设置月份索引，例如2，代表3月份。| 76> | date | number | 否 | 设置日期，例如10。（如果设置hours，则date不能省略）| 77> | hours | number | 否 | 设置小时，例如15。（如果设置minutes，则hours不能省略）| 78> | minutes | number | 否 | 设置分钟，例如20。（如果设置seconds，则minutes不能省略）| 79> | seconds | number | 否 | 设置秒，例如20。（如果设置ms，则seconds不能省略）| 80> | ms | number | 否 | 设置毫秒，例如10。| 81 82**起始时间和结束时间的异常情形说明：** 83 84| 异常情形 | 对应结果 | 85| -------- | ------------------------------------------------------------ | 86| 起始时间晚于结束时间。 | 起始时间、结束时间都为默认值。 | 87| 选中时间早于起始时间。 | 选中时间为起始时间。 | 88| 选中时间晚于结束时间。 | 选中时间为结束时间。 | 89| 起始时间晚于当前系统时间，选中时间未设置。 | 选中时间为起始时间。 | 90| 结束时间早于当前系统时间，选中时间未设置。 | 选中时间为结束时间。 | 91| 时间格式不符合规范，如'01:61:61'。 | 取默认值。 | 92 93## TimePickerFormat<sup>11+</sup>枚举说明 94 95时间选择器的数据格式。 96 97**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 98 99**系统能力：** SystemCapability.ArkUI.ArkUI.Full 100 101| 名称 | 值 | 说明 | 102| ------------------ | - | ------------------------ | 103| HOUR_MINUTE | - | 按照小时和分钟进行显示。 | 104| HOUR_MINUTE_SECOND | - | 按照小时、分钟和秒进行显示。 | 105 106## 属性 107 108除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 109 110### useMilitaryTime 111 112useMilitaryTime(value: boolean) 113 114设置时间是否以24小时制展示，默认以12小时制展示。 115 116**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 117 118**系统能力：** SystemCapability.ArkUI.ArkUI.Full 119 120**参数：** 121 122| 参数名 | 类型 | 必填 | 说明 | 123| ------ | ------- | ---- | ------------------------------------------ | 124| value | boolean | 是 | 时间是否以24小时制展示。<br/>- true：时间以24小时制展示。<br/>- false：时间以12小时制展示。<br/>默认值：false | 125 126### useMilitaryTime<sup>18+</sup> 127 128useMilitaryTime(isMilitaryTime: Optional\<boolean>) 129 130设置展示时间是否为24小时制，默认展示时间为12小时制。与[useMilitaryTime](#usemilitarytime)相比，isMilitaryTime参数新增了对undefined类型的支持。 131 132**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 133 134**系统能力：** SystemCapability.ArkUI.ArkUI.Full 135 136**参数：** 137 138| 参数名 | 类型 | 必填 | 说明 | 139| ------ | ------- | ---- | ------------------------------------------ | 140| isMilitaryTime | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 展示时间是否为24小时制。<br/>- true：展示时间为24小时制。<br/>- false：展示时间为12小时制。<br/>默认值：false<br/>当isMilitaryTime的值为undefined时，使用默认值。| 141 142### disappearTextStyle<sup>10+</sup> 143 144disappearTextStyle(value: PickerTextStyle) 145 146设置边缘项（以选中项为基准向上或向下的第二项）的文本颜色、字号、字体粗细。 147 148**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 156| value | [PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明) | 是 | 边缘项的文本颜色、字号和字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '14fp', <br/>weight: FontWeight.Regular<br/>}<br/>} | 157 158> **说明：** 159> 160> 若选中项向上或向下的可视项数低于两项则无对应边缘项。 161 162### disappearTextStyle<sup>18+</sup> 163 164disappearTextStyle(style: Optional\<PickerTextStyle>) 165 166设置边缘项（以选中项为基准向上或向下的第二项）的文本颜色、字号、字体粗细。与[disappearTextStyle<sup>10+</sup>](#disappeartextstyle10)相比，style参数新增了对undefined类型的支持。 167 168**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 169 170**系统能力：** SystemCapability.ArkUI.ArkUI.Full 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 176| 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时，使用默认值。 | 177 178> **说明：** 179> 180> 若选中项向上或向下的可视项数低于两项则无对应边缘项。 181 182### textStyle<sup>10+</sup> 183 184textStyle(value: PickerTextStyle) 185 186设置待选项（以选中项为基准向上或向下的第一项）的文本颜色、字号、字体粗细。 187 188**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 189 190**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 196| value | [PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明) | 是 | 待选项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff182431',<br/>font: {<br/>size: '16fp', <br/>weight: FontWeight.Regular<br/>}<br/>} | 197 198> **说明：** 199> 200> 若选中项向上或向下可视项数低于一项则无对应待选项。 201 202### textStyle<sup>18+</sup> 203 204textStyle(style: Optional\<PickerTextStyle>) 205 206设置待选项（以选中项为基准向上或向下的第一项）的文本颜色、字号、字体粗细。与[textStyle<sup>10+</sup>](#textstyle10)相比，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#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时，使用默认值。 | 217 218> **说明：** 219> 220> 若选中项向上或向下可视项数低于一项则无对应待选项。 221 222### selectedTextStyle<sup>10+</sup> 223 224selectedTextStyle(value: PickerTextStyle) 225 226设置选中项的文本颜色、字号和字体粗细。 227 228**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 229 230**系统能力：** SystemCapability.ArkUI.ArkUI.Full 231 232**设备行为差异：** 该属性在Wearable设备上使用无效果，在其他设备中可正常生效。 233 234**参数：** 235 236| 参数名 | 类型 | 必填 | 说明 | 237| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 238| value | [PickerTextStyle](ts-picker-common.md#pickertextstyle对象说明) | 是 | 选中项的文本颜色、字号、字体粗细。<br/>默认值：<br/>{<br/>color: '#ff007dff',<br/>font: {<br/>size: '20fp', <br/>weight: FontWeight.Medium<br/>}<br/>} | 239 240### selectedTextStyle<sup>18+</sup> 241 242selectedTextStyle(style: Optional\<PickerTextStyle>) 243 244设置选中项的文本颜色、字号及字体粗细。与[selectedTextStyle<sup>10+</sup>](#selectedtextstyle10)相比，style参数新增了对undefined类型的支持 245 246**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 247 248**系统能力：** SystemCapability.ArkUI.ArkUI.Full 249 250**设备行为差异：** 该属性在Wearable设备上使用无效果，在其他设备中可正常生效。 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 256| 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时，使用默认值。 | 257 258### loop<sup>11+</sup> 259 260loop(value: boolean) 261 262设置是否启用循环模式。 263 264**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.ArkUI.ArkUI.Full 267 268**参数：** 269 270| 参数名 | 类型 | 必填 | 说明 | 271| ------ | ------- | ---- | ------------------------------------------------------------ | 272| value | boolean | 是 | 是否启用循环模式。<br/>- true：启用循环模式。<br/>- false：不启用循环模式。<br/>默认值：true | 273 274### loop<sup>18+</sup> 275 276loop(isLoop: Optional\<boolean>) 277 278设置是否启用循环模式。与[loop<sup>11+</sup>](#loop11)相比，isLoop参数新增了对undefined类型的支持。 279 280**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 281 282**系统能力：** SystemCapability.ArkUI.ArkUI.Full 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| ------ | ------- | ---- | ------------------------------------------------------------ | 288| isLoop | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 是否启用循环模式。<br/>- true：启用循环模式。<br/>- false：不启用循环模式。<br/>默认值：true<br/>当isLoop的值为undefined时，使用默认值。 | 289 290### dateTimeOptions<sup>12+</sup> 291 292dateTimeOptions(value: DateTimeOptions) 293 294设置时分秒是否显示前导0。 295 296**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 297 298**系统能力：** SystemCapability.ArkUI.ArkUI.Full 299 300**参数：** 301 302| 参数名 | 类型 | 必填 | 说明 | 303| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 304| value | [DateTimeOptions](#datetimeoptions12对象说明) | 是 | 设置时分秒是否显示前导0。<br/>默认值：<br/>hour: 24小时制默认为"2-digit"，设置hour是否按照2位数字显示，如果实际数值小于10，则会补充前导0并显示，即为"0X"；12小时制默认为"numeric"，即没有前导0。<br/>minute: 默认为"2-digit"，设置minute是否按照2位数字显示，如果实际数值小于10，则会补充前导0并显示，即为"0X"。<br/>second: 默认为"2-digit"，设置second是否按照2位数字显示，如果实际数值小于10，则会补充前导0并显示，即为"0X"。<br/> 当hour、minute、second的值设置为undefined时，显示效果与其默认值规则一致。| 305 306### dateTimeOptions<sup>18+</sup> 307 308dateTimeOptions(timeFormat: Optional\<DateTimeOptions>) 309 310设置时分秒是否显示前导0。与[dateTimeOptions<sup>12+</sup>](#datetimeoptions12)相比，timeFormat参数新增了对undefined类型的支持。 311 312**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 313 314**系统能力：** SystemCapability.ArkUI.ArkUI.Full 315 316**参数：** 317 318| 参数名 | 类型 | 必填 | 说明 | 319| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 320| timeFormat | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[DateTimeOptions](#datetimeoptions12对象说明)> | 是 | 设置时分秒是否显示前导0，目前只支持设置hour、minute和second参数。<br/>默认值：<br/>hour: 24小时制默认为"2-digit"，设置hour是否按照2位数字显示，如果实际数值小于10，则会补充前导0并显示，即为"0X"；12小时制默认为"numeric"，即没有前导0。<br/>minute: 默认为"2-digit"，设置minute是否按照2位数字显示，如果实际数值小于10，则会补充前导0并显示，即为"0X"。<br/>second: 默认为"2-digit"，设置second是否按照2位数字显示，如果实际数值小于10，则会补充前导0并显示，即为"0X"。<br/> 当hour、minute、second的值设置为undefined时，显示效果与其默认值规则一致。| 321 322### enableHapticFeedback<sup>12+</sup> 323 324enableHapticFeedback(enable: boolean) 325 326设置是否支持触控反馈。 327 328**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 329 330**系统能力：** SystemCapability.ArkUI.ArkUI.Full 331 332**参数：** 333 334| 参数名 | 类型 | 必填 | 说明 | 335| ------ | --------------------------------------------- | ----- |-------------------------------------------------------------------------------------| 336| enable | boolean | 是 | 设置是否开启触控反馈。<br/>- true：开启触控反馈。<br/>- false：不开启触控反馈。<br/>默认值：true<br/>设置为true后，其生效情况取决于系统的硬件是否支持。 | 337 338> **说明：** 339> 340> 开启触控反馈时，需要在工程的src/main/module.json5文件的"module"内配置requestPermissions字段开启振动权限，配置如下： 341> ```json 342> "requestPermissions": [ 343> { 344> "name": "ohos.permission.VIBRATE", 345> } 346> ] 347> ``` 348 349### enableHapticFeedback<sup>18+</sup> 350 351enableHapticFeedback(enable: Optional\<boolean>) 352 353设置是否支持触控反馈。与[enableHapticFeedback<sup>12+</sup>](#enablehapticfeedback12)相比，enable参数新增了对undefined类型的支持。 354 355**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 356 357**系统能力：** SystemCapability.ArkUI.ArkUI.Full 358 359**参数：** 360 361| 参数名 | 类型 | 必填 | 说明 | 362| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------| 363| enable | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<boolean> | 是 | 设置是否开启触控反馈。<br/>- true：开启触控反馈。<br/>- false：不开启触控反馈。<br/>默认值：true<br/>当enable的值为undefined时，使用默认值。<br/>设置为true后，其生效情况取决于系统的硬件是否支持。 | 364 365> **说明：** 366> 367> 开启触控反馈时，需要在工程的src/main/module.json5文件的"module"内配置requestPermissions字段开启振动权限，配置如下： 368> ```json 369> "requestPermissions": [ 370> { 371> "name": "ohos.permission.VIBRATE", 372> } 373> ] 374> ``` 375 376### enableCascade<sup>18+</sup> 377 378enableCascade(enabled: boolean) 379 380设置上午和下午的标识是否根据小时数自动切换，仅在useMilitaryTime设置为false时生效。 381 382**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 383 384**系统能力：** SystemCapability.ArkUI.ArkUI.Full 385 386**参数：** 387 388| 参数名 | 类型 | 必填 | 说明 | 389| ------ | --------------------------------------------- |-----|-------------------------------------------------------------------------------------| 390| enabled | boolean | 是 | 上午和下午的标识是否根据小时数自动切换，仅在useMilitaryTime设置为false时生效。<br/>- true：自动切换。<br/>- false：不自动切换。<br/>默认值：false<br/>当enabled设置为true时，仅在loop参数同时为true时生效。 | 391 392### digitalCrownSensitivity<sup>18+</sup> 393digitalCrownSensitivity(sensitivity: Optional\<CrownSensitivity>) 394 395设置表冠灵敏度。 396 397**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 398 399**系统能力：** SystemCapability.ArkUI.ArkUI.Full 400 401**参数：** 402 403| 参数名 | 类型 | 必填 | 说明 | 404| ----- | ---------------------------------------- | ---- | ------------------------- | 405| sensitivity | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[CrownSensitivity](ts-appendix-enums.md#crownsensitivity18)> | 是 | 表冠响应灵敏度。<br/>默认值：CrownSensitivity.MEDIUM，表示响应速度适中。 | 406 407> **说明：** 408> 409> 用于圆形屏幕的穿戴设备。组件响应[表冠事件](ts-universal-events-crown.md)，需要先获取焦点。 410 411## 事件 412 413除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 414 415### onChange 416 417onChange(callback: (value: TimePickerResult ) => void) 418 419滑动TimePicker后，时间选项归位至选中项位置时，触发该回调。不能通过双向绑定的状态变量触发。 420 421回调会在滑动动画结束后触发，如果需要快速获取索引值变化，建议使用[onEnterSelectedArea](#onenterselectedarea18)接口。 422 423**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 424 425**系统能力：** SystemCapability.ArkUI.ArkUI.Full 426 427**参数：** 428 429| 参数名 | 类型 | 必填 | 说明 | 430| ------ | --------------------------------------------- | ---- | -------------- | 431| value | [TimePickerResult](#timepickerresult对象说明) | 是 | 24小时制时间。 | 432 433### onChange<sup>18+</sup> 434 435onChange(callback: Optional\<OnTimePickerChangeCallback>) 436 437滑动TimePicker后，时间选项归位至选中项位置时，触发该回调。不能通过双向绑定的状态变量触发。与[onChange](#onchange)相比，callback参数新增了对undefined类型的支持。 438 439回调会在滑动动画结束后触发，如果需要快速获取索引值变化，建议使用[onEnterSelectedArea](#onenterselectedarea18)接口。 440 441**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 442 443**系统能力：** SystemCapability.ArkUI.ArkUI.Full 444 445**参数：** 446 447| 参数名 | 类型 | 必填 | 说明 | 448| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 449| callback | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[OnTimePickerChangeCallback](#ontimepickerchangecallback18)> | 是 | 选择时间时触发该回调。<br/>当callback的值为undefined时，不使用回调函数。 | 450 451### onEnterSelectedArea<sup>18+</sup> 452 453onEnterSelectedArea(callback: Callback\<TimePickerResult>) 454 455滑动TimePicker过程中，选项进入分割线区域内，触发该回调。 456 457与[onChange](#onchange)事件的差别在于，该事件的触发时机早于[onChange](#onchange)事件，当当前滑动列滑动距离超过选中项高度的一半时，选项此时已经进入分割线区域内，会触发该事件。当[enableCascade](#enablecascade18)设置为true时，由于上午/下午列与小时列存在联动关系，不建议使用该回调。该回调标识的是滑动过程中选项进入分割线区域内的节点，而联动变化的选项并不涉及滑动，因此，回调的返回值中，仅当前滑动列的值会正常变化，其余未滑动列的值保持不变。 458 459**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 460 461**系统能力：** SystemCapability.ArkUI.ArkUI.Full 462 463**参数：** 464 465| 参数名 | 类型 | 必填 | 说明 | 466| -------- | -------------------------- | ---- | ------------------------------------------ | 467| callback | Callback\<[TimePickerResult](#timepickerresult对象说明)> | 是 | 滑动TimePicker过程中，选项进入分割线区域时触发的回调。 | 468 469## DateTimeOptions<sup>12+</sup>对象说明 470 471type DateTimeOptions = DateTimeOptions 472 473时间、日期格式化时可设置的配置项。 474 475**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 476 477**系统能力：** SystemCapability.ArkUI.ArkUI.Full 478 479| 类型 | 说明 | 480| ------------------------------------------------------------ | ------------------------------------------ | 481| [DateTimeOptions](../../apis-localization-kit/js-apis-intl.md#datetimeoptionsdeprecated) | 创建时间、日期格式化对象时可设置的配置项。 | 482 483## OnTimePickerChangeCallback<sup>18+</sup> 484 485type OnTimePickerChangeCallback = (result: TimePickerResult) => void 486 487选择时间时触发该事件。 488 489**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 490 491**系统能力：** SystemCapability.ArkUI.ArkUI.Full 492 493**参数：** 494 495| 参数名 | 类型 | 必填 | 说明 | 496| ------ | --------------------------------------------- | ---- | -------------- | 497| result | [TimePickerResult](#timepickerresult对象说明) | 是 | 24小时制时间。 | 498 499## TimePickerResult对象说明 500 501返回24小时制时间。 502 503**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 504 505**系统能力：** SystemCapability.ArkUI.ArkUI.Full 506 507| 名称 | 类型 | 只读 | 可选 | 说明 | 508| -------------------- | ------ | ---- | ---- | ----------------------------------- | 509| hour | number | 否 | 否 | 选中时间的时。<br/>取值范围：[0-23] | 510| minute | number | 否 | 否 | 选中时间的分。<br/>取值范围：[0-59] | 511| second<sup>11+</sup> | number | 否 | 否 | 选中时间的秒。<br/>取值范围：[0-59] | 512 513## 示例 514 515### 示例1（设置文本样式） 516 517该示例通过配置[disappearTextStyle](#disappeartextstyle10)、[textStyle](#textstyle10)和[selectedTextStyle](#selectedtextstyle10)实现文本选择器中的文本样式。 518 519```ts 520// xxx.ets 521@Entry 522@Component 523struct TimePickerExample { 524 private selectedTime: Date = new Date('2022-07-22T08:00:00'); 525 526 build() { 527 TimePicker({ 528 selected: this.selectedTime 529 }) 530 .disappearTextStyle({ color: '#004aaf', font: { size: 24, weight: FontWeight.Lighter } }) 531 .textStyle({ color: Color.Black, font: { size: 26, weight: FontWeight.Normal } }) 532 .selectedTextStyle({ color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } }) 533 .onChange((value: TimePickerResult) => { 534 if (value.hour >= 0) { 535 this.selectedTime.setHours(value.hour, value.minute); 536 console.info('select current date is: ' + JSON.stringify(value)); 537 } 538 }) 539 } 540} 541``` 542 543 544 545### 示例2（切换小时制） 546 547该示例通过配置useMilitaryTime实现12小时制、24小时制的切换。 548 549```ts 550// xxx.ets 551@Entry 552@Component 553struct TimePickerExample { 554 @State isMilitaryTime: boolean = false; 555 private selectedTime: Date = new Date('2022-07-22T08:00:00'); 556 557 build() { 558 Column() { 559 Button('切换12小时制/24小时制') 560 .margin(30) 561 .onClick(() => { 562 this.isMilitaryTime = !this.isMilitaryTime; 563 }) 564 565 TimePicker({ 566 selected: this.selectedTime 567 }) 568 .useMilitaryTime(this.isMilitaryTime) 569 .onChange((value: TimePickerResult) => { 570 if (value.hour >= 0) { 571 this.selectedTime.setHours(value.hour, value.minute); 572 console.info('select current time is: ' + JSON.stringify(value)); 573 } 574 }) 575 .onEnterSelectedArea((value: TimePickerResult) => { 576 console.info('item enter selected area, time is: ' + JSON.stringify(value)); 577 }) 578 }.width('100%') 579 } 580} 581``` 582 583 584 585### 示例3（设置时间格式） 586 587该示例使用format和dateTimeOptions设置TimePicker时间格式。 588 589```ts 590// xxx.ets 591@Entry 592@Component 593struct TimePickerExample { 594 private selectedTime: Date = new Date('2022-07-22T08:00:00'); 595 596 build() { 597 Column() { 598 TimePicker({ 599 selected: this.selectedTime, 600 format: TimePickerFormat.HOUR_MINUTE_SECOND 601 }) 602 .dateTimeOptions({ hour: "numeric", minute: "2-digit", second: "2-digit" }) 603 .onChange((value: TimePickerResult) => { 604 if (value.hour >= 0) { 605 this.selectedTime.setHours(value.hour, value.minute); 606 console.info('select current date is: ' + JSON.stringify(value)); 607 } 608 }) 609 }.width('100%') 610 } 611} 612``` 613 614 615 616### 示例4（设置循环滚动） 617 618该示例通过配置[loop](#loop11)设置TimePicker是否循环滚动。 619 620```ts 621// xxx.ets 622@Entry 623@Component 624struct TimePickerExample { 625 @State isLoop: boolean = true; 626 @State selectedTime: Date = new Date('2022-07-22T12:00:00'); 627 628 build() { 629 Column() { 630 TimePicker({ 631 selected: this.selectedTime 632 }) 633 .loop(this.isLoop) 634 .onChange((value: TimePickerResult) => { 635 if (value.hour >= 0) { 636 this.selectedTime.setHours(value.hour, value.minute); 637 console.info('select current date is: ' + JSON.stringify(value)); 638 } 639 }) 640 641 Row() { 642 Text('循环滚动').fontSize(20) 643 644 Toggle({ type: ToggleType.Switch, isOn: true }) 645 .onChange((isOn: boolean) => { 646 this.isLoop = isOn; 647 }) 648 }.position({ x: '60%', y: '40%' }) 649 650 }.width('100%') 651 } 652} 653``` 654 655 656 657### 示例5（设置时间选择组件的起始时间） 658 659该示例设置TimePicker的起始时间。 660 661```ts 662// xxx.ets 663@Entry 664@Component 665struct TimePickerExample { 666 private selectedTime: Date = new Date('2022-07-22T08:50:00'); 667 668 build() { 669 Column() { 670 TimePicker({ 671 selected: this.selectedTime, 672 format: TimePickerFormat.HOUR_MINUTE_SECOND, 673 start: new Date('2022-07-22T08:30:00') 674 }) 675 .dateTimeOptions({ hour: "numeric", minute: "2-digit", second: "2-digit" }) 676 .onChange((value: TimePickerResult) => { 677 if (value.hour >= 0) { 678 this.selectedTime.setHours(value.hour, value.minute); 679 console.info('select current date is: ' + JSON.stringify(value)); 680 } 681 }) 682 }.width('100%') 683 } 684} 685``` 686 687 688### 示例6（设置时间选择组件的结束时间） 689 690该示例设置TimePicker的结束时间。 691 692```ts 693// xxx.ets 694@Entry 695@Component 696struct TimePickerExample { 697 private selectedTime: Date = new Date('2022-07-22T08:50:00'); 698 699 build() { 700 Column() { 701 TimePicker({ 702 selected: this.selectedTime, 703 format: TimePickerFormat.HOUR_MINUTE_SECOND, 704 end: new Date('2022-07-22T15:20:00'), 705 }) 706 .dateTimeOptions({ hour: "numeric", minute: "2-digit", second: "2-digit" }) 707 .onChange((value: TimePickerResult) => { 708 if (value.hour >= 0) { 709 this.selectedTime.setHours(value.hour, value.minute); 710 console.info('select current date is: ' + JSON.stringify(value)); 711 } 712 }) 713 }.width('100%') 714 } 715} 716``` 717 718 719 720### 示例7（设置上午下午跟随时间联动） 721 722该示例通过配置[enableCascade](#enablecascade18)、[loop](#loop11)实现12小时制时上午下午跟随时间联动。 723 724```ts 725// xxx.ets 726@Entry 727@Component 728struct TimePickerExample { 729 private selectedTime: Date = new Date('2022-07-22T08:00:00'); 730 731 build() { 732 Column() { 733 TimePicker({ 734 selected: this.selectedTime, 735 }) 736 .enableCascade(true) 737 .loop(true) 738 .onChange((value: TimePickerResult) => { 739 if (value.hour >= 0) { 740 this.selectedTime.setHours(value.hour, value.minute); 741 console.info('select current date is: ' + JSON.stringify(value)); 742 } 743 }) 744 }.width('100%') 745 } 746} 747``` 748 749 750
