HarmonyOS6 ArkTS TimePicker 组件使用文档

文章目录核心亮点完整代码核心参数与方法1 组件构造参数2 关键属性方法链式调用1小时制切换useMilitaryTime2循环滚动控制loop3样式自定义系列4数字格式控制dateTimeOptions5时间变化回调onChange核心变量运行效果总结TimePicker 是 HarmonyOS6 ArkTS 提供的基础时间选择组件支持时分/时分秒两种时间格式、12/24小时制切换可自定义滚动项样式、控制循环滚动适用于手机、平板、车机等多端HarmonyOS应用的时间选择场景最低适配API 11建议使用API 18以获得完整功能。核心亮点支持12小时制带上午/下午标识和24小时制一键切换可配置时分HOUR_MINUTE/时分秒HOUR_MINUTE_SECOND两种时间展示格式支持循环滚动开关关闭后滚动至边界将无法继续滑动精细化样式自定义未选中项、边缘淡化项、选中高亮项分别配置样式时间数字格式控制支持numeric不补0/2-digit补0为两位适配不同UI设计需求实时回调选中时间可快速绑定页面数据实现双向联动。完整代码// 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 组件构造参数参数名类型说明示例selectedDate必选组件默认选中的时间new Date(2025-01-01T10:30:45)formatTimePickerFormat必选时间展示格式TimePickerFormat.HOUR_MINUTE_SECOND时分秒/TimePickerFormat.HOUR_MINUTE时分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样式自定义系列方法名说明配置项textStyle未选中的滚动项基础样式color文字颜色、fontsize/weight/家族disappearTextStyle滚动时边缘淡化的项样式同textStyle建议配置浅色系颜色和较小字号selectedTextStyle选中项的高亮样式同textStyle建议配置醒目颜色和较大字号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)); })核心变量变量名类型初始值作用isMilitaryTimebooleantrue绑定小时制切换按钮控制useMilitaryTime属性isLoopbooleantrue绑定循环滚动开关控制loop属性timeFormatTimePickerFormatTimePickerFormat.HOUR_MINUTE_SECOND绑定时间格式切换按钮控制组件构造参数formatselectedTimeDatenew Date(‘2025-01-01T10:30:45’)存储组件当前选中的时间联动页面展示和组件默认值运行效果页面初始化时TimePicker默认显示24小时制、时分秒格式默认选中时间为10:30:45开启循环滚动点击“切换为12小时制”按钮组件将显示为10:30:45 AM上午/02:30:45 PM下午格式点击“切换为时分格式”按钮组件将隐藏秒数仅展示时和分关闭“循环滚动”开关后滚动至0时/23时、0分/59分、0秒/59秒时无法继续向边界外滑动滚动选择时间时下方的“当前时间”文本会实时更新控制台同时打印选中的时间对象时间数字展示效果小时为不补0如10时、9时分和秒为补0两位如05分、45秒、09秒。总结秒属性兼容性当format设为TimePickerFormat.HOUR_MINUTE时分格式时TimePickerResult无second属性回调中需用value.second ?? 0做空值处理避免报错Date对象更新更新选中时间时建议使用setHours(hour, minute, second)方法直接修改Date对象的时/分/秒保证数据实时联动样式适配disappearTextStyle建议配置比textStyle更浅的颜色和更小的字号符合用户视觉滚动体验API版本若使用API 11~17部分样式属性可能存在兼容性建议升级至API 18及以上版本多端适配组件默认支持多端自适应可通过width/margin等属性调整适配不同设备的屏幕尺寸。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力