找物源码导读Cocos Creator 3.8 · assets/scripts
0%
已读 0 / 424
目录— 个文件
目录加载中…
…/core/timer/TimerManager.ts
1import { Framework } from "../../Framework";
2import { frameworkManager } from "../base/FrameworkClassRegistry";
3import { IFrameworkManager } from "../base/IFrameworkManager";
4import { Singleton } from "../base/Singleton";
5import { ITimer, TimerType } from "./TimerDefine";
6
7/**
8 * 定时器管理器
9 * 支持:延迟执行、固定时长内间隔执行,并处理异常与内存泄漏
10 */
11@frameworkManager()
12export class TimerManager extends Singleton<TimerManager> implements IFrameworkManager {
13 Name: string = "TimerManager";
14
15 /** 活跃定时器Map(ID -> 定时器实例) */
16 private timers: Map<number, ITimer> = new Map();
17 /** 下一个定时器ID(自增确保唯一) */
18 private nextTimerId: number = 1;
19 /** 是否正在更新定时器(防止Update中修改Map导致迭代异常) */
20 private isUpdating: boolean = false;
21 /** 待移除的定时器ID列表(Update中标记,更新后统一移除) */
22 private pendingRemoveIds: number[] = [];
23 public async Init(): Promise<void> {
24 // 记录管理器初始化入口,便于排查启动顺序。
25 Framework.Log.Log(this.Name, "Init", "初始化定时器管理器");
26
27 this.timers = new Map();
28 this.nextTimerId = 1;
29 this.pendingRemoveIds = [];
30 }
31
32 public DeInit(): void {
33 // 取消所有活跃定时器
34 this.timers.forEach(timer => {
35 timer.isCancelled = true;
36 timer.isActive = false;
37 });
38 this.timers.clear();
39 this.pendingRemoveIds = [];
40 }
41
42 /**
43 * 更新定时器(每帧调用)
44 * @param deltaTime 自上次调用的时间间隔(秒)
45 */
46 public Update(deltaTime: number): void {
47 if (this.timers.size === 0) return;
48
49 this.isUpdating = true;
50 this.pendingRemoveIds = [];
51
52 // 遍历所有定时器
53 this.timers.forEach(timer => {
54 if (timer.isCancelled || !timer.isActive) {
55 this.pendingRemoveIds.push(timer.id);
56 return;
57 }
58
59 try {
60 if (timer.type === TimerType.Delay) {
61 this.ProcessDelayTimer(timer, deltaTime);
62 } else {
63 this.ProcessIntervalTimer(timer, deltaTime);
64 }
65 } catch (error) {
66 Framework.Log.Error(`${this.Name} 定时器(${timer.id})执行异常:`, error);
67 this.pendingRemoveIds.push(timer.id); // 异常定时器直接移除
68 }
69 });
70
71 // 移除标记为待删除的定时器
72 this.pendingRemoveIds.forEach(id => this.timers.delete(id));
73 this.isUpdating = false;
74 }
75
76 /**
77 * 延迟执行回调
78 * @param delayTime 延迟时间(秒)
79 * @param callback 延迟后执行的回调
80 * @param context 回调上下文
81 * @returns 定时器ID(用于取消)
82 */
83 public Delay(delayTime: number, callback: () => void, context: any): number {
84 // 参数校验
85 if (delayTime <= 0 || typeof callback !== "function") {
86 Framework.Log.Error(`${this.Name} delay参数异常: delayTime=${delayTime}, callback=${typeof callback}`);
87 return -1;
88 }
89
90 // 绑定上下文
91 callback = callback.bind(context);
92
93 // 创建延迟定时器
94 const timerId = this.nextTimerId++;
95 const timer: ITimer = {
96 id: timerId,
97 type: TimerType.Delay,
98 isActive: true,
99 isCancelled: false,
100 delayTime,
101 remainingTime: delayTime,
102 onComplete: callback
103 };
104
105 this.timers.set(timerId, timer);
106 return timerId;
107 }
108
109 /**
110 * 固定时长内间隔执行逻辑
111 * @param intervalTime 间隔执行时间(秒)
112 * @param totalDuration 总执行时长(秒)
113 * @param onInterval 间隔回调(每次间隔后执行)
114 * @param onComplete 完成回调(总时长结束后执行)
115 * @param context 回调上下文
116 * @returns 定时器ID(用于取消)
117 */
118 public Interval(
119 intervalTime: number,
120 totalDuration: number,
121 onInterval: () => void,
122 onComplete: () => void,
123 context: any
124 ): number {
125 // 参数校验
126 if (intervalTime <= 0 || totalDuration <= 0 ||
127 typeof onInterval !== "function" || typeof onComplete !== "function") {
128 Framework.Log.Error(`${this.Name} interval参数异常: intervalTime=${intervalTime}, totalDuration=${totalDuration}`);
129 return -1;
130 }
131 // 绑定上下文
132 onInterval = onInterval.bind(context);
133 onComplete = onComplete.bind(context);
134
135 // 创建间隔定时器
136 const timerId = this.nextTimerId++;
137 const timer: ITimer = {
138 id: timerId,
139 type: TimerType.Interval,
140 isActive: true,
141 isCancelled: false,
142 intervalTime,
143 totalDuration,
144 remainingTime: totalDuration, // 剩余总时长
145 lastIntervalTime: 0, // 初始上次间隔时间为0
146 onInterval,
147 onComplete
148 };
149
150 this.timers.set(timerId, timer);
151 return timerId;
152 }
153
154 /**
155 * 取消定时器
156 * @param timerId 定时器ID(delay/interval返回的ID)
157 */
158 public CancelTimer(timerId: number): void {
159 if (timerId <= 0) return;
160
161 const timer = this.timers.get(timerId);
162 if (!timer) {
163 // Framework.Log.Warn(`${this.Name} 取消不存在的定时器: ${timerId}`);
164 return;
165 }
166
167 timer.isCancelled = true;
168 timer.isActive = false;
169
170 // 如果正在更新,加入待移除列表;否则立即移除
171 if (this.isUpdating) {
172 if (!this.pendingRemoveIds.includes(timerId)) {
173 this.pendingRemoveIds.push(timerId);
174 }
175 } else {
176 this.timers.delete(timerId);
177 }
178 }
179
180 /**
181 * 取消所有定时器
182 */
183 public CancelAllTimers(): void {
184 this.timers.forEach(timer => {
185 timer.isCancelled = true;
186 timer.isActive = false;
187 });
188
189 if (this.isUpdating) {
190 this.pendingRemoveIds = Array.from(this.timers.keys());
191 } else {
192 this.timers.clear();
193 }
194 }
195
196 /** 处理延迟定时器 */
197 private ProcessDelayTimer(timer: ITimer, deltaTime: number): void {
198 if (!timer.remainingTime) return;
199
200 timer.remainingTime -= deltaTime;
201 if (timer.remainingTime <= 0) {
202 // 执行回调并标记为完成
203 timer.onComplete();
204 timer.isActive = false;
205 this.pendingRemoveIds.push(timer.id);
206 }
207 }
208
209 /** 处理间隔定时器 */
210 private ProcessIntervalTimer(timer: ITimer, deltaTime: number): void {
211 if (!timer.remainingTime || !timer.intervalTime) return;
212
213 // 更新剩余总时长
214 timer.remainingTime -= deltaTime;
215 if (timer.remainingTime <= 0) {
216 // 总时长结束,执行完成回调
217 timer.onComplete();
218 timer.isActive = false;
219 this.pendingRemoveIds.push(timer.id);
220 return;
221 }
222
223 // 累计间隔时间(总时长 - 剩余时长 = 已执行时长)
224 const elapsed = timer.totalDuration! - timer.remainingTime;
225 // 检查是否达到间隔时间
226 if (elapsed - timer.lastIntervalTime! >= timer.intervalTime) {
227 // 执行间隔回调并更新上次间隔时间
228 timer.onInterval!();
229 timer.lastIntervalTime = elapsed;
230 }
231 }
232
233 /** 业务直接使用设备毫秒时间,不应用服务器校时。 */
234 public DateNow(): number {
235 return Date.now();
236 }
237}
讲解238 行
定时器管理器人工通读

TimerManager.ts

框架单例,用统一 Map 保存延迟与间隔定时器,每帧由框架调用 Update 推进时间并触发回调。Delay 与 Interval 返回 id,取消与重启时统一作废。

先看 Update 的遍历与待删除标记,再看 Delay、Interval 的参数校验,最后看两个 Process 方法的触发条件。

特殊处理与易错点

11注释定时器管理器 支持:延迟执行、固定时长内间隔执行,并处理异常与内存泄漏
12注释TimerManager:帧驱动定时器:Delay/Interval/Cancel,支持 Update 中安全增删与异
13属性名称(string):模块/组件名称,用于日志、缓存 Key 或资源查找。
16属性定时器 id 到实例的 Map,注册写入,完成、取消与异常时移除。
18属性自增 id 分配器,Init 与 DeInit 后重置为一。
20属性是否处于 Update 遍历中,控制取消操作是立即删表还是入队。
22属性本帧待移除的定时器 id 列表,遍历结束后统一删除。
23方法重建定时器 Map,把 id 分配器和待删除列表恢复初始状态。
25注释记录管理器初始化入口,便于排查启动顺序。
32方法把全部定时器标记取消和非激活后清空表与待删除列表。
34注释取消所有活跃定时器
46方法遍历所有定时器,跳过取消或非激活项,按类型推进时间,异常项与完成项在本帧末统一移除。
53注释遍历所有定时器
72注释移除标记为待删除的定时器
83方法校验延迟与回调后绑定上下文,分配 id 并创建延迟定时器写入表中。
85注释参数校验
91注释绑定上下文
94注释创建延迟定时器
118方法校验间隔、总时长与两个回调后绑定上下文,创建间隔定时器写入表中。
126注释参数校验
132注释绑定上下文
136注释创建间隔定时器
158方法标记指定定时器取消和非激活,更新中入待删列表,否则立即从表中删除。
164注释Framework.Log.Warn(`${this.Name} 取消不存在的定时器: ${timerId}`);
171注释如果正在更新,加入待移除列表;否则立即移除
183方法把所有定时器标记取消和非激活,更新中把全部 id 放入待删列表,否则清空表。
197方法扣减剩余延迟,归零或变负时执行完成回调,标记非激活并排队移除。
203注释执行回调并标记为完成
210方法先扣减剩余总时长并在耗尽时执行完成回调,再按已执行时长判断是否触发间隔回调。
214注释更新剩余总时长
217注释总时长结束,执行完成回调
224注释累计间隔时间(总时长 - 剩余时长 = 已执行时长)
226注释检查是否达到间隔时间
228注释执行间隔回调并更新上次间隔时间
234方法直接返回设备当前毫秒时间,不做服务器校时。