鸿蒙新特性：TextTimer 计时器组件详解——从番茄钟到验证码倒计时的通用方案

时间显示是移动应用中最基础的需求之一。HarmonyOS NEXT ArkUI 提供了 TextClock文本时钟和 TextTimer文本计时器两个组件分别覆盖看时间和计时两大场景。上一篇文章我们深入探讨了 TextClock 的用法本文聚焦 TextTimer——一个专为倒计时和正计时设计的文本计时组件。我们将通过一个完整的专注计时器番茄钟实战案例展示 TextTimer 在倒计时场景中的完整用法包括控制器操作、格式切换、预设选择和状态管理。关键词HarmonyOS、ArkUI、TextTimer、计时器、倒计时、番茄钟一、TextTimer 组件概览TextTimer 是 ArkUI 中专门用于计时显示的基础组件。它与 TextClock 的核心区别在于特性TextClockTextTimer数据来源系统时间应用层控制主要用途显示当前时间倒计时 / 正计时控制方式被动更新TextTimerController 主动控制典型场景时钟展示番茄钟、验证码、运动计时TextTimer 通过TextTimerController提供三个核心操作start()开始计时、pause()暂停计时、reset()重置计时。配合isCountDown参数可灵活切换正计时和倒计时两种模式。二、TextTimer 核心 API2.1 构造函数TextTimer({isCountDown:boolean,// true倒计时, false正计时count:number,// 计时总时长单位毫秒controller:TextTimerController// 计时器控制器})其中isCountDown和count决定了 TextTimer 的核心行为当isCountDown true时TextTimer 从count表示的时长开始倒数直到 0当isCountDown false时TextTimer 从 0 开始递增2.2 TextTimerControllerTextTimerController是控制计时器行为的核心对象提供三个方法classTextTimerController{start():void;// 开始计时从当前值继续pause():void;// 暂停计时保留当前值reset():void;// 重置计时回到 count 值}这三个方法的语义非常直观start在空闲或暂停状态下启动计时。如果之前已暂停调用 start 会从暂停时的剩余时间继续pause在运行状态下暂停。暂停后当前剩余时间被保留reset在任何状态下将计时器重置到初始的count值2.3 format 属性format属性控制 TextTimer 的文本显示格式支持以下模式格式字符串显示效果适用场景mm:ss25:00分钟级倒计时推荐mm:ss.SS25:00.00需要显示百分秒HH:mm:ss00:25:00小时级计时选择合适的格式很重要。对于番茄钟这类 25-60 分钟的场景mm:ss最为清晰对于超过 60 分钟的长时间计时HH:mm:ss能更好地表达总时长。三、实战专注计时器番茄钟番茄工作法是一种经典的时间管理技术设定 25 分钟专注时间期间不受干扰地工作完成后休息 5 分钟。我们将实现一个完整的番茄钟计时器包含以下功能点预设时长选择25 分钟、45 分钟、60 分钟三档开始 / 暂停 / 重置完整的计时器操作格式切换mm:ss 与 HH:mm:ss 之间切换完成计数记录今日完成的番茄数3.1 状态设计计时器页面涉及多个维度的状态需要清晰的状态设计StatetimerStatus:number0;// 0 idle就绪等待开始// 1 running专注中// 2 paused已暂停// 3 finished完成StatetotalSeconds:number25*60;// 倒计时总秒数StateshowHours:booleanfalse;// 是否显示小时位StatesessionCount:number0;// 完成的番茄数StatecurrentPreset:number25;// 当前预设分钟privatetimerCtrl:TextTimerControllernewTextTimerController();计时器状态机包含 4 个状态转换逻辑如下idle → running点击开始调用timerCtrl.start()running → paused点击暂停调用timerCtrl.pause()paused → running点击继续调用timerCtrl.start()running → finished计时结束或手动点击完成调用timerCtrl.reset()finished → idle点击中心按钮重新开始选择新预设并重置3.2 预设选择预设选择器使用 ForEach 渲染三个时长选项通过视觉高亮标识当前选中项Row(){Text(时长).fontSize(14).fontColor(#1a1a2e).fontWeight(FontWeight.Medium).margin({right:12})ForEach(this.presets,(min:number){Row(){Text(min.toString()).fontSize(14).fontColor(this.currentPresetminthis.timerStatus0?#FFFFFF:#1a1a2e).fontWeight(this.currentPresetminthis.timerStatus0?FontWeight.Bold:FontWeight.Normal)Text( min).fontSize(11).fontColor(this.currentPresetminthis.timerStatus0?#FFFFFFCC:#9999AA)}.padding({top:8,bottom:8,left:16,right:16}).borderRadius(20).backgroundColor(this.currentPresetminthis.timerStatus0?#1677FF:#F2F3F5).margin({left:8}).onClick((){if(this.timerStatus0||this.timerStatus3){this.selectPreset(min);}})},(min:number)min.toString())}.width(100%).padding({left:Spacing.LG,right:Spacing.LG,top:10,bottom:16})关键设计细节预设切换仅在空闲idle或已完成finished状态下允许——计时器运行中或暂停时不允许切换时长避免意外中断选中项使用蓝色填充#1677FF 白色文字未选中项使用灰色背景#F2F3F5 深色文字通过selectPreset()方法统一处理选中逻辑重建 TextTimerController 并重置状态selectPreset(minutes:number):void{this.currentPresetminutes;this.totalSecondsminutes*60;this.timerStatus0;this.timerKey;this.timerCtrlnewTextTimerController();}每次切换预设时我们创建一个新的TextTimerController并递增timerKey。这样做可以确保 TextTimer 组件在新参数下完全重建避免旧控制器状态残留。3.3 控制按钮控制区域由三个圆形按钮组成左侧重置、中央开始/暂停、右侧完成。Row(){// 重置按钮Button(){Text(重置).fontSize(15).fontColor(#666677).fontWeight(FontWeight.Medium)}.width(64).height(64).borderRadius(32).backgroundColor(#F2F3F5).onClick((){this.selectPreset(this.currentPreset);})// 开始 / 暂停中央主按钮Button(){Text(this.timerStatus1?暂停:this.timerStatus2?继续:开始).fontSize(18).fontColor(#FFFFFF).fontWeight(FontWeight.Bold)}.width(100).height(100).borderRadius(50).backgroundColor(this.timerStatus1?#FF9800:#1677FF).margin({left:40,right:40}).onClick((){if(this.timerStatus0){this.timerStatus1;this.timerCtrl.start();}elseif(this.timerStatus1){this.timerStatus2;this.timerCtrl.pause();}elseif(this.timerStatus2){this.timerStatus1;this.timerCtrl.start();}elseif(this.timerStatus3){this.selectPreset(this.currentPreset);}})// 完成按钮Button(){Text(完成).fontSize(15).fontColor(#666677).fontWeight(FontWeight.Medium)}.width(64).height(64).borderRadius(32).backgroundColor(#F2F3F5).onClick((){this.timerCtrl.reset();this.timerStatus3;this.sessionCount1;})}交互逻辑开始从空闲状态timerStatus 0启动调用timerCtrl.start()主按钮变橙色并显示暂停暂停运行中timerStatus 1点击调用timerCtrl.pause()主按钮变蓝色并显示继续继续暂停后timerStatus 2点击调用timerCtrl.start()从剩余时间继续重置左侧按钮重建控制器回到初始时长完成右侧按钮提前结束计时并计数主按钮使用了不同的背景色来区分运行和暂停状态——运行中为橙色#FF9800即暂停的暗示色空闲和暂停后重新开始时为蓝色#1677FF即行动的暗示色。这种颜色变化让用户一眼就能理解当前状态。3.4 TextTimer 集成核心倒计时显示区域使用真实的 TextTimer 组件TextTimer({isCountDown:true,count:this.totalSeconds*1000,// 转换为毫秒controller:this.timerCtrl}).format(this.showHours?HH:mm:ss:mm:ss).fontSize(56).fontColor(this.timerStatus3?#52C41A:#1a1a2e).fontWeight(FontWeight.Bold).fontFamily(monospace)这里有几个值得注意的实现细节毫秒转换TextTimer 的count参数以毫秒为单位而我们的totalSeconds以秒为单位需要乘以 1000动态 format通过showHours状态动态切换格式true时显示HH:mm:ssfalse时显示mm:ss等宽字体使用monospace字体系列避免数字跳动导致布局抖动。不同的数字宽度可能略有不同如1比0窄等宽字体确保每个数字占据相同宽度完成状态着色计时结束时文字变为绿色#52C41A给用户正向反馈3.5 格式切换格式切换使用 Toggle 开关组件让用户在 mm:ss 和 HH:mm:ss 之间选择Row(){Text(显示格式).fontSize(15).fontColor(#1a1a2e)Blank()Text(this.showHours?HH:mm:ss:mm:ss).fontSize(13).fontColor(#1677FF).fontWeight(FontWeight.Medium).margin({right:10})Toggle({type:ToggleType.Switch,isOn:this.showHours}).onChange((on:boolean){if(this.timerStatus0||this.timerStatus3){this.showHourson;this.timerKey;}})}格式切换同样只在空闲或已完成状态下允许——这是为了避免计时过程中格式变化带来的视觉困惑。四、进阶话题4.1 TextTimerController 的延迟初始化模式在 ArkUI 开发中某些组件需要在aboutToAppear或用户交互后重新创建。TextTimerController 是一个典型的例子当用户切换预设时长时旧的控制器可能持有上次计时的残留状态直接reset()后start()有时行为不如预期。最佳实践是销毁并重建——创建一个新的 TextTimerController 实例分配给this.timerCtrlselectPreset(minutes:number):void{this.totalSecondsminutes*60;this.timerStatus0;this.timerCtrlnewTextTimerController();}配合State计数器的递增可以强制 ArkUI 框架触发 TextTimer 组件的完全重建确保新参数和新控制器完美匹配。4.2 正计时模式虽然本文的 Demo 聚焦于倒计时番茄钟TextTimer 同样支持正计时场景——例如运动计时、通勤计时等。只需将isCountDown设置为falseTextTimer({isCountDown:false,count:0,// 正计时从 0 开始controller:this.timerCtrl}).format(HH:mm:ss)正计时会从 00:00:00 开始递增非常适合需要记录耗时的场景。4.3 计时器生命周期管理当页面销毁aboutToDisappear时运行中的计时器不会自动停止。如果你的应用需要在后台持续计时这会很有用但如果需要在离开页面时暂停应该在aboutToDisappear中调用timerCtrl.pause()。五、完整 Demo 交互流程梳理一下专注计时器的完整交互流程进入页面显示 25 分钟计时器状态为就绪计时器圆环显示 25:00选择预设点击45 min按钮计时器显示变为 45:00预设高亮切换开始专注点击蓝色开始按钮计时器开始倒计时主按钮变为橙色暂停状态文字变为蓝色专注中 · 保持专注中途暂停点击橙色暂停按钮倒计时停止按钮变为蓝色继续状态文字变为已暂停 · 继续努力恢复计时点击蓝色继续按钮计时器从剩余时间继续倒数完成计时倒计时归零或点击完成按钮计时器变绿状态显示太棒了一个番茄完成今日完成计数 1格式切换打开显示格式开关计时器显示从 mm:ss 切换到 HH:mm:ss仅在空闲/完成状态下可切换开始新计时选择新的预设或点击中心按钮重新开始六、设计要点总结回顾整个计时器 Demo 的设计有几个值得提炼的要点状态驱动的 UI计时器的 4 个状态idle / running / paused / finished决定了所有 UI 元素的呈现——按钮文字、颜色、操作逻辑全部由状态驱动。这种模式让代码逻辑清晰可预测。控制器的生命周期TextTimerController 与 TextTimer 组件是紧密耦合的。当 TextTimer 的参数count、format发生变化时最简单可靠的做法是重建控制器而非在旧控制器上修复状态。操作安全性预设切换和格式切换仅在 idle 或 finished 状态下允许。这种操作守卫避免了计时器运行中修改参数导致的行为混乱是用户体验中的细节但很重要。等宽字体的价值在计时器场景中等宽字体不仅关乎美观更关乎可用性——非等宽字体会在数字变化时导致文本区域轻微抖动分散用户注意力。七、总结TextTimer 是 ArkUI 中一个小而精的组件。它的 API 只有三个方法start / pause / reset和一个属性format但配合状态管理和控制器生命周期设计可以构建出完整且专业的计时器应用。本文通过专注计时器这个完整 Demo覆盖了TextTimer 的构造函数、控制器和 format 属性4 状态机驱动的 UI 交互设计控制器的销毁并重建模式预设选择、格式切换的操作守卫设计正计时模式的扩展方向TextTimer 和 TextClock 是 ArkUI 时间相关组件的双子星。TextClock 告诉你现在几点TextTimer 告诉你过了多久或还剩多久。将两者灵活运用就能覆盖应用中所有时间显示场景——从时钟展示到番茄钟从验证码倒计时到运动计时器应有尽有。