HarmonyOS6 ArkTS TimePicker 组件使用文档

TimePicker 是 HarmonyOS6 ArkTS 提供的基础时间选择组件，支持时分/时分秒两种时间格式、12/24小时制切换，可自定义滚动项样式、控制循环滚动，适用于手机、平板、车机等多端HarmonyOS应用的时间选择场景，最低适配API 11+（建议使用API 18以获得完整功能）。

核心亮点

1. 支持12小时制（带上午/下午标识）和24小时制一键切换；
2. 可配置时分（HOUR_MINUTE）/时分秒（HOUR_MINUTE_SECOND）两种时间展示格式；
3. 支持循环滚动开关，关闭后滚动至边界将无法继续滑动；
4. 精细化样式自定义：未选中项、边缘淡化项、选中高亮项分别配置样式；
5. 时间数字格式控制：支持numeric（不补0）/2-digit（补0为两位），适配不同UI设计需求；
6. 实时回调选中时间，可快速绑定页面数据实现双向联动。

完整代码

// TimePickerFullDemo.ets @Entry @Component struct TimePickerFullDemo { // 控制24小时制/12小时制 @State isMilitaryTime: boolean = true; // 控制是否循环滚动 @State isLoop: boolean = true; // 控制时间格式：0=时分 1=时分秒 @State timeFormat: TimePickerFormat = TimePickerFormat.HOUR_MINUTE_SECOND; // 默认选中时间 private selectedTime: Date = new Date('2025-01-01T10:30:45'); build() { Column({ space: 20 }) { // 标题 Text('TimePicker 完整示例') .fontSize(24) .fontWeight(FontWeight.Bold) .margin({ top: 20 }); // 切换12/24小时制按钮 Button(this.isMilitaryTime ? '切换为12小时制' : '切换为24小时制') .onClick(() => { this.isMilitaryTime = !this.isMilitaryTime; }) .width('80%'); // 切换时间格式按钮 Button(this.timeFormat === TimePickerFormat.HOUR_MINUTE ? '切换为时分秒格式' : '切换为时分格式') .onClick(() => { this.timeFormat = this.timeFormat === TimePickerFormat.HOUR_MINUTE ? TimePickerFormat.HOUR_MINUTE_SECOND : TimePickerFormat.HOUR_MINUTE; }) .width('80%'); // 循环滚动开关 Row({ space: 10 }) { Text('循环滚动：') .fontSize(18); Toggle({ type: ToggleType.Switch, isOn: this.isLoop }) .onChange((isOn) => { this.isLoop = isOn; }); } .margin({ top: 10 }); // 时间选择器核心组件 TimePicker({ selected: this.selectedTime, format: this.timeFormat, }) // 24/12小时制 .useMilitaryTime(this.isMilitaryTime) // 循环滚动 .loop(this.isLoop) // 未选中项样式 .textStyle({ color: '#333333', font: { size: 18, weight: FontWeight.Normal } }) // 边缘淡化项样式 .disappearTextStyle({ color: '#999999', font: { size: 16, weight: FontWeight.Lighter } }) // 选中项样式 .selectedTextStyle({ color: '#007DFF', font: { size: 24, weight: FontWeight.Bold } }) // 前导0设置：小时数字显示，分秒两位显示 .dateTimeOptions({ hour: 'numeric', minute: '2-digit', second: '2-digit' }) // 时间变化回调 .onChange((value: TimePickerResult) => { this.selectedTime.setHours(value.hour, value.minute, value.second ?? 0); console.info('当前选中时间：', JSON.stringify(value)); }) .width('90%') .margin({ top: 10 }); // 显示当前选中时间 Text(`当前时间：${this.selectedTime.toLocaleTimeString()}`) .fontSize(18) .fontColor('#666666') .margin({ top: 10 }); } .width('100%') .padding(10) } }

运行效果如图：

核心参数与方法

1 组件构造参数

2 关键属性方法（链式调用）

（1）小时制切换：useMilitaryTime

• 类型：boolean
• 说明：控制组件使用24小时制/12小时制，true为24小时制，false为12小时制（自动显示AM/PM标识）
• 示例：.useMilitaryTime(this.isMilitaryTime)

（2）循环滚动控制：loop

• 类型：boolean
• 说明：true表示滚动至时间边界（如0时/23时）可继续循环滑动，false表示边界不可继续滑动
• 示例：.loop(this.isLoop)

（3）样式自定义系列

（4）数字格式控制：dateTimeOptions

• 类型：DateTimeOptions
• 说明：控制小时、分钟、秒的数字展示格式，支持numeric（不补0，如9:5）和2-digit（补0为两位，如09:05）
• 配置项：hour/minute/second，分别对应时/分/秒的格式
• 示例：.dateTimeOptions({ hour: 'numeric', minute: '2-digit', second: '2-digit' })

（5）时间变化回调：onChange

• 回调参数：TimePickerResult（包含hour: number、minute: number、second?: number，秒为可选属性，时分格式下无此参数）
• 说明：滚动选择时间时实时触发，可在回调中更新页面绑定的时间数据，实现数据联动
• 示例：

.onChange((value: TimePickerResult) => { this.selectedTime.setHours(value.hour, value.minute, value.second ?? 0); console.info('当前选中时间：', JSON.stringify(value)); })

核心变量

运行效果

1. 页面初始化时，TimePicker默认显示24小时制、时分秒格式，默认选中时间为10:30:45，开启循环滚动；
2. 点击“切换为12小时制”按钮，组件将显示为10:30:45 AM（上午）/02:30:45 PM（下午）格式；
3. 点击“切换为时分格式”按钮，组件将隐藏秒数，仅展示时和分；
4. 关闭“循环滚动”开关后，滚动至0时/23时、0分/59分、0秒/59秒时，无法继续向边界外滑动；
5. 滚动选择时间时，下方的“当前时间”文本会实时更新，控制台同时打印选中的时间对象；
6. 时间数字展示效果：小时为不补0（如10时、9时），分和秒为补0两位（如05分、45秒、09秒）。

总结

1. 秒属性兼容性：当format设为TimePickerFormat.HOUR_MINUTE（时分格式）时，TimePickerResult无second属性，回调中需用value.second ?? 0做空值处理，避免报错；
2. Date对象更新：更新选中时间时，建议使用setHours(hour, minute, second)方法，直接修改Date对象的时/分/秒，保证数据实时联动；
3. 样式适配：disappearTextStyle建议配置比textStyle更浅的颜色和更小的字号，符合用户视觉滚动体验；
4. API版本：若使用API 11~17，部分样式属性可能存在兼容性，建议升级至API 18及以上版本；
5. 多端适配：组件默认支持多端自适应，可通过width/margin等属性调整适配不同设备的屏幕尺寸。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力