HarmonyOS《柚兔学伴》项目实战11-倒计时组件封装与控制器模式

第11篇倒计时组件封装与控制器模式在柚兔学伴中番茄钟倒计时是核心功能之一。倒计时组件需要满足外部可设置时间、可远程重置、可监听状态变化。这就引出了一个经典的组件设计问题——如何让父组件从外部控制子组件的行为本篇从TimerComponent.ets的 202 行源码出发详解控制器模式Controller Pattern在 ArkUI 中的实现。一、控制器模式的核心思想ArkUI 的Component是一个封闭的作用域State、Prop等状态装饰器只能在组件内部修改。如果父组件想要主动触发子组件的某个行为如重置倒计时单纯通过属性传递是做不到的。控制器模式的解法是子组件在初始化时将自身的方法注册到控制器对象上父组件持有控制器通过调用控制器方法间接驱动子组件。父组件 ──调用── Controller.reset() ──回调── 子组件.onResetFromController()二、TimerComponentController 实现exportclassTimerComponentController{privateresetCallback:(()void)|nullnull;setResetCallback(callback:()void){this.resetCallbackcallback;}reset(){if(this.resetCallback){this.resetCallback();}}}控制器非常简洁只做两件事setResetCallback注册回调函数由子组件调用reset执行回调函数由父组件调用这种注册-执行的模式本质是将子组件的方法引用提升到了控制器中打破了组件边界对方法调用的限制。三、TimerComponent 组件详解3.1 属性定义Componentexportstruct TimerComponent{controller:TimerComponentController|nullnull;PropWatch(onTotalTimeChange)totalTime:number60;onTotalTimeChange(){this.resetTimer();this.currentTimethis.totalTime;}onTimeUp?:()void;onTimeChange?:(currentTime:number)void;StatecurrentTime:number60;StateisRunning:booleanfalse;privatetimer:number-1;privategradientColor:LinearGradientnewLinearGradient([{color:$r(app.color.color_color_1),offset:0.5},{color:$r(app.color.color_color_2),offset:1.0}])}关键设计点属性装饰器说明totalTimeProp Watch从父组件单向传入变化时自动重置计时器currentTimeState当前剩余时间驱动 UI 刷新isRunningState运行状态控制按钮文字和颜色onTimeUp普通属性回调函数时间归零时通知父组件onTimeChange普通属性回调函数每秒通知父组件时间变化controller普通属性控制器实例父组件通过它远程控制Prop保证totalTime从父组件单向流入Watch则监听其变化当外部重新设置时间时自动重置。3.2 控制器绑定aboutToAppear(){this.currentTimethis.totalTime;if(this.controller){this.controller.setResetCallback(this.onResetFromController.bind(this));}}onResetFromController(){this.resetTimer();this.currentTimethis.totalTime;}aboutToAppear是组件的生命周期回调在组件首次创建时执行。此时将onResetFromController方法通过bind(this)绑定正确的this指向后注册到控制器。为什么需要.bind(this)因为setResetCallback存储的是函数引用当控制器调用resetCallback()时this可能丢失。bind确保无论谁调用这个函数this都指向组件实例。3.3 倒计时核心逻辑toggleTimer(){if(this.isRunning){clearInterval(this.timer);this.isRunningfalse;}else{this.isRunningtrue;this.timersetInterval((){if(this.currentTime0){this.currentTime--;if(this.onTimeChange){this.onTimeChange(this.currentTime);}}else{this.isRunningfalse;clearInterval(this.timer);if(this.onTimeUp){this.onTimeUp();}}},1000);}}每 1000ms1秒执行一次剩余时间 0递减currentTime触发onTimeChange回调剩余时间 0停止定时器标记为未运行触发onTimeUp回调toggleTimer是一个切换函数——运行时暂停暂停时开始。clearInterval确保不会产生多个定时器叠加。3.4 重置逻辑resetTimer(){clearInterval(this.timer);this.isRunningfalse;this.currentTimethis.totalTime;}重置操作包含三个步骤清除定时器 → 停止运行状态 → 恢复初始时间。无论是本地重置还是通过控制器远程重置最终都调用此方法。四、时间格式化formatTime(seconds:number):string{consthoursMath.floor(seconds/3600);constminutesMath.floor((seconds%3600)/60);constsecsseconds%60;return${hours.toString().padStart(2,0)}:${minutes.toString().padStart(2,0)}:${secs.toString().padStart(2,0)};}将总秒数转换为HH:MM:SS格式。padStart(2, 0)确保个位数补零如5显示为05。五、UI 构建5.1 圆形进度条Stack(){Progress({value:this.getProgress(),total:this.totalTime,type:ProgressType.ScaleRing}).width(100%).height(100%).style({strokeWidth:10,}).color($r(app.color.app_primary))Column(){Text(this.formatTime(this.currentTime)).fontSize(20).fontWeight(FontWeight.Bolder).textAlign(TextAlign.Center)Text(剩余时间).fontSize(14).fontColor(Color.Gray).margin({top:10})}}ProgressType.ScaleRing是圆环进度条value为已用时间totalTime - currentTimetotal为总时间。Stack 布局将时间文字叠加在进度环中心。5.2 控制按钮Row({space:12}){Button(重置).fontSize(12).height(30).backgroundColor(#F0F0F0).fontColor(Color.Black).borderRadius(25).onClick((){this.resetTimer();})Button(this.isRunning?暂停:开始).fontSize(12).height(30).backgroundColor(this.isRunning?$r(app.color.app_alert):$r(app.color.app_primary)).fontColor(Color.White).borderRadius(25).onClick((){this.toggleTimer();})}按钮文字和颜色根据isRunning状态动态切换实现了开始/暂停一体化按钮。六、生命周期清理aboutToDisappear(){if(this.timer!-1){clearInterval(this.timer);}}组件销毁时必须清除定时器否则会持续消耗资源并可能导致对已销毁组件的状态修改。timer初始值为-1仅在有活跃定时器时清理。七、父组件中的使用在TodoView中倒计时组件的完整使用方式timerController:TimerComponentControllernewTimerComponentController()StatesettingTime:number25*60;onTimerFinishedasync(){this.alarmVisibletrue// 播放提醒音}onTimeChanged(currentTime:number){console.log(剩余时间:${currentTime}秒);}// 在 build 中使用TimerComponent({totalTime:this.settingTime,onTimeUp:this.onTimerFinished,onTimeChange:this.onTimeChanged,controller:this.timerController})当用户在弹窗中确认关闭闹钟时通过控制器重置IBestDialog({visible:$alarmVisible,defaultBuilder:():voidthis.alarmBuild(),onConfirm:((){this.alarmVisiblefalsethis.timerController.reset()// 远程重置倒计时})})八、控制器模式的适用场景场景说明需要远程重置弹窗确认后重置计时器需要远程暂停/恢复页面切换时暂停返回时恢复需要跨组件通信兄弟组件间通过共享控制器协调行为控制器模式的扩展方向添加更多回调setPauseCallback、setResumeCallback支持多实例每个控制器绑定一个组件实例结合Watch控制器修改某个State子组件通过Prop Watch响应九、小结控制器模式在 ArkUI 中解决了父组件主动驱动子组件行为的需求其核心三步定义 Controller 类声明回调属性和注册/执行方法子组件注册回调在aboutToAppear中controller.setResetCallback(this.method.bind(this))父组件调用方法controller.reset()间接触发子组件行为相比Link双向绑定控制器模式更语义化——它表达的是命令而非数据同步适合倒计时重置、播放器控制、动画触发等命令式交互场景。