找物源码导读Cocos Creator 3.8 · assets/scripts
0%
已读 0 / 424
目录— 个文件
目录加载中…
…/core/ui/UIManager.ts
1import { instantiate, Node, Prefab } from 'cc';
2import { FrameworkEntry } from "../../FrameworkEntry";
3import { Framework } from "../../Framework";
4import { reportPanelShow, reportPanelStop } from "../../module/sdk/SdkPanelReport";
5import { frameworkManager } from '../base/FrameworkClassRegistry';
6import { IFrameworkManager } from '../base/IFrameworkManager';
7import { Singleton } from '../base/Singleton';
8import { UIBasePanel } from "./UIBasePanel";
9import { UIPanelDate } from "./UIDefine";
10import { UIGroupEnum } from "./UIGroupEnum";
11import { SdkManager } from '../../module/sdk/SdkManager';
12
13/**
14 * UI管理器
15 */
16@frameworkManager()
17export class UIManager extends Singleton<UIManager> implements IFrameworkManager {
18
19 Name: string = "UIManager";
20
21 // 项目面板埋点配置由入口注入,仅持有原引用,不创建框架默认表。
22 private panelReportScenes: Readonly<Record<string, string>> | null = null;
23
24 public get PanelReportScenes(): Readonly<Record<string, string>> {
25 if (!this.panelReportScenes) {
26 throw new Error("[UIManager] 请在初始化前设置面板埋点配置");
27 }
28 return this.panelReportScenes;
29 }
30
31 public SetPanelReportScenes(config: Readonly<Record<string, string>>): void {
32 this.panelReportScenes = config;
33 }
34
35 //UI组对应的节点
36 private uiGroupNodes: Map<UIGroupEnum, Node> = new Map<UIGroupEnum, Node>();
37 //所有的面板 包含cache下面的
38 private allPanels: Map<string, Node> = new Map<string, Node>();
39 // 正在创建中的界面,防止在高延迟下重复创建多个同名面板
40 private creatingPanels: Map<string, Promise<void>> = new Map<string, Promise<void>>();
41 // 正在预热中的界面,防止重复静默创建
42 private warmingPanels: Map<string, Promise<void>> = new Map<string, Promise<void>>();
43
44 //按顺序展示的面板队列
45 private readyPanelQueue: UIPanelDate[] = [];
46
47 public async Init(): Promise<void> {
48 Framework.Log.Log(this.Name, "Init", "初始化UI管理器");
49
50 let uiRoot: Node = FrameworkEntry.Instance?.UIRoot!;
51 this.uiGroupNodes.set(UIGroupEnum.Cached, uiRoot.getChildByName(UIGroupEnum[UIGroupEnum.Cached])!);
52 this.uiGroupNodes.set(UIGroupEnum.Bottom, uiRoot.getChildByName(UIGroupEnum[UIGroupEnum.Bottom])!);
53 this.uiGroupNodes.set(UIGroupEnum.Middle, uiRoot.getChildByName(UIGroupEnum[UIGroupEnum.Middle])!);
54 this.uiGroupNodes.set(UIGroupEnum.Top, uiRoot.getChildByName(UIGroupEnum[UIGroupEnum.Top])!);
55 }
56
57 public DeInit(): void {
58 }
59
60 public Update(deltaTime: number): void {
61 }
62
63 /**
64 * 打开界面
65 * @param panelName 界面路径
66 * @param param 界面参数
67 * @constructor
68 */
69 public async OpenPanel(panel: string | typeof UIBasePanel, param: any = null) {
70 let panelName: string;
71 if (typeof panel === 'string') {
72 // 处理字符串类型的面板名称
73 panelName = panel;
74 } else {
75 // 处理面板类型,提取类名作为面板名称
76 panelName = panel.name;
77 }
78 if (!panelName) {
79 Framework.Log.Error(this.Name, "OpenPanel", "panelName is Null");
80 return;
81 }
82
83 // 若该面板正在创建中,则等待创建完成后直接返回,避免重复创建多个实例
84 const creating = this.creatingPanels.get(panelName);
85 if (creating) {
86 await creating;
87 return;
88 }
89 const warming = this.warmingPanels.get(panelName);
90 if (warming) {
91 await warming;
92 }
93 //如果存在这个界面 那么关闭它
94 let panelNode = this.allPanels.get(panelName);
95 if (panelNode && panelNode.active) {
96 this.ClosePanel(panelNode.name);
97 }
98
99 let cache = this.SearchInCache(panelName);
100 if (cache) {
101 this.allPanels.set(panelName, cache);
102 this.ResumePanel(cache, param);
103 } else {
104 const createPromise = this.CreatePanel(panelName, param);
105 this.creatingPanels.set(panelName, createPromise);
106 await createPromise;
107 this.creatingPanels.delete(panelName);
108 }
109 }
110
111 /**
112 * 预热界面:预加载 prefab 并静默实例化到缓存组,不触发 OnOpen。
113 * 用于大厅常用界面首开卡顿优化。
114 */
115 public async WarmupPanel(panel: string | typeof UIBasePanel): Promise<void> {
116 const panelName = typeof panel === 'string' ? panel : panel.name;
117 if (!panelName) {
118 Framework.Log.Error(this.Name, "WarmupPanel", "panelName is Null");
119 return;
120 }
121
122 const existing = this.allPanels.get(panelName);
123 if (existing) {
124 return;
125 }
126 const cache = this.SearchInCache(panelName);
127 if (cache) {
128 this.allPanels.set(panelName, cache);
129 return;
130 }
131
132 const creating = this.creatingPanels.get(panelName);
133 if (creating) {
134 await creating;
135 return;
136 }
137
138 const warming = this.warmingPanels.get(panelName);
139 if (warming) {
140 await warming;
141 return;
142 }
143
144 const warmPromise = this.CreatePanelToCache(panelName);
145 this.warmingPanels.set(panelName, warmPromise);
146 try {
147 await warmPromise;
148 } finally {
149 this.warmingPanels.delete(panelName);
150 }
151 }
152
153 /**
154 * 关闭界面
155 * @param panelPath 界面路径
156 * @param param 界面参数
157 */
158 public ClosePanel(panel: string | typeof UIBasePanel, param: any = null) {
159 let panelName: string;
160 if (typeof panel === 'string') {
161 // 处理字符串类型的面板名称
162 panelName = panel;
163 } else {
164 // 处理面板类型,提取类名作为面板名称
165 panelName = panel.name;
166 }
167 if (!panelName) {
168 Framework.Log.Error(this.Name, "ClosePanel", "panelName is Null");
169 return;
170 }
171 let panelNode = this.allPanels.get(panelName);
172 if (panelNode) {
173 if (!panelNode.isValid) {
174 // 节点已被外部销毁(如场景切换),清理残留记录
175 this.allPanels.delete(panelName);
176 } else {
177 let panelScr = panelNode.getComponent(UIBasePanel)!;
178 panelScr.OnClose(param);
179 reportPanelStop(panelName);
180 panelScr.OnCache();
181
182 // 临时验证动态合图问题:微信渠道关闭动态合图后不再需要面板级强制隐藏。
183 // if (SdkConfig.Channel === SdkChannel.Wechat) {
184 // panelNode.active = false;
185 // }
186 panelNode.setParent(this.GetUIGroupNode(UIGroupEnum.Cached)!);
187 }
188 }
189
190 this.CheckReadyPanel();
191 }
192
193
194 /**
195 * 打开一组面板
196 * @param panels 面板信息
197 * @param isInstane 是否立刻弹出第一个面板
198 * @constructor
199 */
200 public AddPanelQueue(panels: UIPanelDate[], isInstane = true) {
201 if (!panels || panels.length == 0) {
202 return;
203 }
204
205 for (let panel of panels) {
206 this.readyPanelQueue.push(panel);
207 }
208
209 if (isInstane) {
210 this.CheckReadyPanel();
211 }
212 }
213
214 /**
215 * 清空面板队列
216 * @constructor
217 */
218 public ClearPanelQueue() {
219 this.readyPanelQueue = [];
220 }
221
222 /**
223 * 检查是否有面板需要打开
224 * @private
225 */
226 private CheckReadyPanel() {
227 if (this.readyPanelQueue.length <= 0)
228 return;
229
230 let panel = this.readyPanelQueue.shift()!;
231 this.OpenPanel(panel.path, panel.param);
232 }
233
234 /**
235 * 创建界面
236 * @param panelName 界面路径
237 * @param params 界面参数
238 * @private
239 */
240 private async CreatePanel(panelName: string, params: any): Promise<void> {
241 let panelAssest: Prefab | null = await Framework.Res.LoadAssetAsync(panelName, Prefab);
242
243 if (panelAssest == null) {
244 Framework.Log.Error(this.Name, "CreatePanel", `资源不存在: ${panelName}`);
245 return;
246 }
247
248 const cache = this.SearchInCache(panelName);
249 if (cache) {
250 this.allPanels.set(panelName, cache);
251 this.ResumePanel(cache, params);
252 return;
253 }
254 const existing = this.allPanels.get(panelName);
255 if (existing?.isValid) {
256 if (existing.active) {
257 return;
258 }
259 this.ResumePanel(existing, params);
260 return;
261 }
262
263 let panelNode = instantiate(panelAssest);
264 let panelScr = panelNode.getComponent(UIBasePanel)!;
265 let group = panelScr.Layer;
266
267 this.allPanels.set(panelName, panelNode);
268
269 panelNode.active = false;
270 this.AttachGroup(panelNode, group);
271 panelScr.OnInit(params);
272 panelScr.OnOpen(params);
273 reportPanelShow(panelName);
274 }
275
276 private async CreatePanelToCache(panelName: string): Promise<void> {
277 await Framework.Res.PreLoadAssetAsync(panelName, Prefab);
278 const cache = this.SearchInCache(panelName);
279 if (cache) {
280 this.allPanels.set(panelName, cache);
281 return;
282 }
283 const existing = this.allPanels.get(panelName);
284 if (existing?.isValid) {
285 return;
286 }
287 const panelAsset: Prefab | null = await Framework.Res.LoadAssetAsync(panelName, Prefab);
288 if (panelAsset == null) {
289 Framework.Log.Error(this.Name, "CreatePanelToCache", `资源不存在: ${panelName}`);
290 return;
291 }
292
293 const panelNode = instantiate(panelAsset);
294 const panelScr = panelNode.getComponent(UIBasePanel)!;
295 this.allPanels.set(panelName, panelNode);
296
297 panelNode.active = false;
298 this.AttachGroup(panelNode, UIGroupEnum.Cached);
299 panelScr.OnInit(null);
300 }
301
302 /**
303 * 获取界面
304 * @param panelName 界面名称
305 * @returns
306 */
307 public GetPanel(panelName: string): UIBasePanel | null {
308 let node = this.allPanels.get(panelName);
309 if (node && node.isValid && node.active) {
310 return node.getComponent(UIBasePanel)!;
311 }
312 if (node && !node.isValid) {
313 // 节点已被外部销毁,清理残留记录
314 this.allPanels.delete(panelName);
315 }
316 return null;
317 }
318
319 /**
320 * 销毁界面
321 * @constructor
322 * @private
323 */
324 public DestoryPanel(panel: UIBasePanel) {
325 try {
326 if (!panel || !panel.node || !panel.node.isValid) {
327 // 节点已被外部销毁(如场景切换),直接从 allPanels 移除
328 if (panel) {
329 this.allPanels.delete(panel.name);
330 }
331 return;
332 }
333 panel.OnClose(null);
334 reportPanelStop(panel.node.name);
335 panel.OnDeInit(null);
336 this.allPanels.delete(panel.name);
337
338 panel.node.destroy();
339 }
340 catch (error) {
341 Framework.Log.Error("UIManager", "DestoryPanel", "销毁界面时出错: " + error);
342 }
343 }
344
345 /**
346 * 销毁所有界面
347 * @constructor
348 * @private
349 */
350 public DestoryAllPanels() {
351 try {
352 this.ClearPanelQueue();
353 this.creatingPanels.clear();
354 for (let panel of this.allPanels.values()) {
355 if (!panel || !panel.isValid) continue;
356 const comp = panel.getComponent(UIBasePanel);
357 if (comp) {
358 this.DestoryPanel(comp);
359 }
360 }
361 }
362 catch (error) {
363 Framework.Log.Error("UIManager", "DestoryAllPanels", "销毁所有界面时出错: " + error);
364 }
365 this.allPanels.clear();
366 }
367
368 /**
369 * 复用界面
370 * @param panelNode 界面节点
371 * @param params 界面参数
372 * @private
373 */
374 private ResumePanel(panelNode: Node, params: any) {
375 let panelScr = panelNode.getComponent(UIBasePanel)!;
376 panelScr.OnResume();
377 this.AttachGroup(panelNode, panelScr.Layer);
378 panelScr.OnOpen(params);
379 reportPanelShow(panelNode.name);
380 }
381
382
383 /**
384 * 搜索界面缓存
385 * @param panelName 界面名称
386 * @private
387 */
388 private SearchInCache(panelName: string) {
389 let node = this.GetUIGroupNode(UIGroupEnum.Cached);
390 if (node) {
391 let child = node.getChildByName(panelName);
392 return child;
393 }
394 return null;
395 }
396
397
398 /**
399 * 界面节点添加到界面组
400 * @param panelNode
401 * @param group
402 */
403 private AttachGroup(panelNode: Node, group: UIGroupEnum) {
404 let node = this.GetUIGroupNode(group);
405 if (node) {
406 panelNode.setParent(node);
407 }
408 }
409
410
411 /**
412 * 获取界面组节点
413 * @param group 界面组
414 * @private
415 */
416 private GetUIGroupNode(group: UIGroupEnum) {
417 let node = this.uiGroupNodes.get(group);
418 if (node) {
419 return node;
420 } else {
421 Framework.Log.Error("UIManager", "GetUIGroupNode", "界面组节点" + group + "不存在");
422 }
423 }
424
425
426}
讲解427 行
UI 管理器人工通读

UIManager.ts

框架单例与界面总入口,按四个分组管理面板节点,提供打开、关闭、预热、排队打开与销毁接口。它通过创建中和预热中两张 Promise 表防止同名面板重复实例化,并在关闭时把面板回收到缓存组复用。

先看 Init 的分组节点查找,再读 OpenPanel 的防重与缓存复用分支,然后看 ClosePanel 与 DestoryAllPanels,最后看预热和队列方法。

特殊处理与易错点

16注释UI管理器
17注释UIManager:UI 管理器:Open/Close/Warmup/Destroy 面板,按 Cached/B
19属性名称(string):模块/组件名称,用于日志、缓存 Key 或资源查找。
22属性入口注入的面板埋点场景配置,未设置时读取即抛错。
24方法返回面板埋点场景配置,未设置时直接抛错,不做空表兜底。
31方法保存入口传入的埋点配置引用,不复制也不校验内容。
36属性分组枚举到组节点容器的映射,Init 按枚举名在 UI 根节点下查找并写入。
38属性面板名到节点的主索引,创建、复用、关闭与销毁都会读写它。
40属性正在创建的面板名到创建 Promise,用于并发打开去重。
42属性正在预热的面板名到预热 Promise,用于静默创建去重。
45属性待依次打开的面板队列,AddPanelQueue 追加,CheckReadyPanel 逐个取出。
47方法从 UI 根节点按四个分组枚举名查找同名子节点,写入分组表供后续挂载。
57方法空实现,重启时不清理分组节点引用。
60方法空实现,界面管理不参与每帧更新。
69方法解析面板名,等待进行中的创建或预热,关闭同名已开面板,再优先复用缓存否则创建新实例。
73注释处理字符串类型的面板名称
76注释处理面板类型,提取类名作为面板名称
84注释若该面板正在创建中,则等待创建完成后直接返回,避免重复创建多个实例
94注释如果存在这个界面 那么关闭它
115方法解析面板名,已有实例或缓存直接返回,否则预加载并静默实例化到缓存组。
158方法解析面板名,节点有效则调用关闭钩子、上报并缓存,再挂到缓存组,最后尝试打开队列下一个。
162注释处理字符串类型的面板名称
165注释处理面板类型,提取类名作为面板名称
175注释节点已被外部销毁(如场景切换),清理残留记录
186注释临时验证动态合图问题:微信渠道关闭动态合图后不再需要面板级强制隐藏。 if (SdkConfig.Channel === SdkChannel.Wechat) { panelNode.active = false; }
200方法把面板列表追加到待打开队列,立即模式会马上触发一次队首打开。
218方法直接清空待打开面板队列,不影响已打开的面板。
226方法队列非空时取出队首,调用 OpenPanel 打开并透传参数。
240方法异步加载预制体,重新检查缓存与已有实例后实例化、挂组、调用初始化与打开并上报。
276方法先预加载再加载预制体,检查缓存后实例化并挂到缓存组,只调用初始化。
307方法取有效且激活的面板节点组件,节点失效时清理记录并返回空。
314注释节点已被外部销毁,清理残留记录
324方法节点失效只删记录,否则依次调用关闭、上报、销毁钩子,删除记录并销毁节点。
328注释节点已被外部销毁(如场景切换),直接从 allPanels 移除
350方法清空队列与创建记录,遍历所有面板逐个销毁,最后清空总表。
374方法调用缓存面板的复用钩子,按层级重新挂组,再执行打开与埋点上报。
388方法在缓存组节点下按节点名查找子节点,命中返回可复用节点。
403方法按分组取组节点并把面板节点设为它的子节点。
416方法从分组表取组节点,缺失时打错误日志并返回空。