鸿蒙新特性：TimePicker 时间选择器详解——打造一个完整的闹钟模拟器

时间选择是移动应用中继日期选择之后的第二高频时间交互。HarmonyOS NEXT ArkUI 提供了 TimePicker 组件以经典的两列滚轮时/分交互模式让用户快速选定时间。与 DatePicker 的年月日三级滚轮不同TimePicker 专注于时和分的选择交互更加简洁直接。本文将深入讲解 TimePicker 的 API 设计和使用方法并通过一个完整的闹钟模拟器实战案例展示 12/24 小时制切换、剩余时间倒计时、标签命名和快捷时间预设等功能。关键词HarmonyOS、ArkUI、TimePicker、时间选择、闹钟、倒计时一、TimePicker 组件概览TimePicker 采用两列滚轮式交互——左列是小时0-23右列是分钟0-59。与 DatePicker 相比TimePicker 少了天的维度使用户能更快速地选择精确到分钟的时间点。它的典型应用场景包括闹钟设置选择提醒时间预约时段选择开始时间提醒设定选择通知触发时间倒计时起始时间选择结合 DatePicker 和 TextClock这三个组件构成了 ArkUI 时间相关组件体系的完整拼图。二、TimePicker 核心 API2.1 构造函数TimePicker({selected:Date// 初始选中的时间})TimePicker 的构造函数只有一个参数selected接受一个 JavaScript Date 对象。组件会自动从 Date 对象中提取时和分忽略年、月、日部分。// 默认选中早上 7:00TimePicker({selected:newDate(2026,0,1,7,0)})2.2 onChange 回调与 TimePickerResult当用户滑动滚轮改变选中时间时onChange被触发返回TimePickerResult对象interfaceTimePickerResult{hour:number;// 0-23始终为 24 小时制minute:number;// 0-59}值得注意的重要设计hour始终是 24 小时制0-23无论页面上是否启用了 12 小时制显示。这意味着 TimePicker 的内部数据模型是纯粹的 24 小时制12 小时制的 AM/PM 显示完全由应用层负责转换。这种设计让数据与显示分离避免了上午 7 点和下午 7 点19 点在数据层上的歧义。TimePicker({selected:newDate(2026,0,1,7,0)}).onChange((value:TimePickerResult){this.alarmHourvalue.hour!;// 724h 制this.alarmMinutevalue.minute!;})2.3 关键属性属性类型说明.useMilitaryTime()-强制 24 小时制显示.loop()boolean是否循环滚动.disappearTextStyle()PickerTextStyle非选中项文字样式.selectedTextStyle()PickerTextStyle选中项文字样式!三、12/24 小时制转换TimePicker 内部使用 24 小时制存储小时值但很多场景需要展示 12 小时制带 AM/PM。我们需要在应用层实现转换逻辑// 24h → 12h 数字fmt12h(h:number):string{consth12h%12;if(h120)return12;// 0点→12点, 12点→12点returnh12.toString();}// 判断上午/下午ampm(h:number):string{returnh12?上午:下午;}// 格式化完整时间字符串fmtTimeString():string{if(this.use24h){returnthis.alarmHour.toString().padStart(2,0).concat(:,this.alarmMinute.toString().padStart(2,0));}returnthis.ampm(this.alarmHour).concat( ,this.fmt12h(this.alarmHour),:,this.alarmMinute.toString().padStart(2,0));}三个关键转换规则0 点在 12 小时制中显示为12:00午夜12 点在 12 小时制中显示为12:00正午13-23 点对 12 取模得到 1-11且标注为下午四、实战闹钟模拟器我们实现一个完整的闹钟模拟器核心功能包括TimePicker 时间选择两列滚轮选择时和分12/24 时制切换Toggle 开关控制显示格式闹钟标签命名TextInput 自定义闹钟名称剩余时间倒计时设定后实时显示距闹钟响铃还有多久快捷时间预设8 个常用时间一键设定4.1 核心状态StatealarmHour:number7;// 0-23StatealarmMinute:number0;Stateuse24h:booleantrue;// 时制开关StatealarmLabel:string起床闹钟;StatealarmActive:booleanfalse;// 闹钟是否已设定StateremainText:string;// 剩余时间文字4.2 剩余时间计算设定闹钟后需要计算当前时间与闹钟时间的差值。核心逻辑是如果闹钟时间已过则自动推到明天同一时间。updateRemain():void{if(!this.alarmActive){this.remainText未设置;return;}constnownewDate();letalarmnewDate(now.getFullYear(),now.getMonth(),now.getDate(),this.alarmHour,this.alarmMinute,0);// 如果闹钟时间已过推到明天if(alarm.getTime()now.getTime()){alarmnewDate(alarm.getTime()24*60*60*1000);}// 计算小时和分钟差constdiffalarm.getTime()-now.getTime();consthMath.floor(diff/(1000*60*60));constmMath.floor((diff%(1000*60*60))/(1000*60));this.remainText还有 .concat(h.toString(), 小时 ,m.toString(), 分钟);}为了保持剩余时间更新设定闹钟后开启一个定时器每分钟刷新setAlarm():void{this.alarmActivetrue;this.updateRemain();if(this.intervalId!-1){clearInterval(this.intervalId);}// 每 30 秒刷新剩余时间this.intervalIdsetInterval((){this.updateRemain();},30000);}页面销毁时记得清理定时器aboutToDisappear():void{if(this.intervalId!-1){clearInterval(this.intervalId);}}4.3 快捷时间预设提供 8 个常用闹钟时间的快捷按钮覆盖从早到晚的典型场景Row(){this.QuickBtn(06:30,6,30)this.QuickBtn(07:00,7,0)this.QuickBtn(07:30,7,30)this.QuickBtn(08:00,8,0)}Row(){this.QuickBtn(12:00,12,0)this.QuickBtn(14:00,14,0)this.QuickBtn(18:30,18,30)this.QuickBtn(22:00,22,0)}QuickBtn使用Builder提取为独立方法BuilderQuickBtn(label:string,h:number,m:number){Text(label).fontSize(13).fontColor(#1677FF).fontWeight(FontWeight.Medium).padding({top:8,bottom:8,left:14,right:14}).borderRadius(10).backgroundColor(#EEF3FF).margin({right:8}).onClick((){this.alarmHourh;this.alarmMinutem;if(this.alarmActive){this.updateRemain();}})}4.4 时间显示区域一个醒目的时间展示卡片使用大号等宽字体显示当前设定的闹钟时间Row(){Text(⏰).fontSize(36).margin({right:14})Column(){Text(this.fmtTimeString()).fontSize(40).fontColor(#1a1a2e).fontWeight(FontWeight.Bold).fontFamily(monospace).margin({bottom:6})Text(this.alarmActive?闹钟已开启:闹钟未开启).fontSize(12).fontColor(this.alarmActive?#52C41A:#9999AA)}}如果闹钟已设定额外显示一个橙色的剩余时间标签让用户一目了然地知道距离闹钟触发还有多久。4.5 设定/取消按钮按钮在不同状态下有完全不同的外观和行为未设定状态蓝色按钮文字设定闹钟已设定状态红色按钮文字取消闹钟if(!this.alarmActive){Button(设定闹钟).fontSize(16).fontColor(#FFFFFF).fontWeight(FontWeight.Bold).width(100%).height(48).borderRadius(24).backgroundColor(#1677FF).onClick((){this.setAlarm();})}else{Button(取消闹钟).fontSize(16).fontColor(#FFFFFF).fontWeight(FontWeight.Bold).width(100%).height(48).borderRadius(24).backgroundColor(#FF4D4F).onClick((){this.cancelAlarm();})}五、与其他时间组件的配合TimePicker 很少单独使用它通常与 DatePicker、TextClock、TextTimer 配合构成完整的时间交互方案组合场景说明DatePicker TimePicker预约/日程先选日期再选时间TimePicker TextClock闹钟设置时间 显示当前时间TimePicker TextTimer倒计时选定截止时间 倒计时显示例如一个完整的预约提醒功能可能需要DatePicker 选日期 → TimePicker 选时间 → TextTimer 显示剩余时间。这三个组件的组合能覆盖绝大部分时间相关的交互需求。六、完整交互流程初始状态TimePicker 显示 07:00时间卡片显示07:00闹钟未设定选择时间滑动时和分滚轮时间卡片实时同步更新显示的时间切换时制关闭24 小时制开关显示变为上午 7:00命名标签在输入框中输入晨会提醒快捷设定点击08:00快捷按钮时间跳转到 8:00设定闹钟点击蓝色设定闹钟按钮剩余时间开始计算并显示取消闹钟点击红色取消闹钟按钮回到未设定状态七、总结TimePicker 是 ArkUI 时间组件家族中小而精的一员。它的 API 极简——只有一个selected参数和一个onChange回调——但配合应用层的 12/24 时制转换和时间计算逻辑可以构建出功能完备的闹钟应用。本文通过闹钟模拟器这个实战案例覆盖了TimePicker 的基本用法和 TimePickerResult 接口12/24 小时制的应用层转换逻辑三个关键规则剩余时间的跨天计算已过时间自动推到明天快捷时间预设的 Builder 复用定时器的生命周期管理aboutToDisappear 清理TimePicker 配合 DatePicker 和 TextTimer三者共同构成了鸿蒙应用中时间选择与管理的完整能力矩阵。掌握了 TimePicker你就补全了时间交互的最后一块拼图。