目录— 个文件
⌕
目录加载中…
…/core/ui/UIBasePanel.ts
1import { _decorator, Component, Node, Tween, tween, Button, UIOpacity, Vec3 } from 'cc';
2import { UIGroupEnum } from "./UIGroupEnum";
3import { UIPanelAniStyle } from "./UIPanelAniStyle";
4import { Framework } from "../../Framework";
5import { UtilityNodeHelper } from "../utility/UtilityNodeHelper";
6import { UIActionClass, UIBaseMoveAction } from './UIActionDefine';
7import { UtilityAction } from '../utility/UtilityAction/UtilityAction';
8const { ccclass, property } = _decorator;
9
10/**
11 * UI界面基类
12 */
13@ccclass
14export class UIBasePanel extends Component {
15
16 @property({ type: UIGroupEnum, group: "basePanel" })
17 private layer: UIGroupEnum = UIGroupEnum.Middle; //UI所属层级
18 @property({ type: Node, group: "basePanel" })
19 private grayMaskNode: Node = null!; //灰色背景节点
20 @property({ type: Node, group: "basePanel" })
21 private boxNode: Node = null!; //动画盒子节点
22 // 布尔默认值已提供属性类型。
23 @property({ group: "basePanel" })
24 private isAnimation = true; //是否开启动画
25 @property({ type: Node, group: "basePanel" })
26 protected closeBtn: Node = null!; //关闭按钮
27
28 @property
29 private _actionClass: UIActionClass = new UIActionClass(); // 动画类
30
31 @property({ type: UIActionClass, group: "basePanel", visible: function () { return (<UIBasePanel>this).isAnimation } })
32 private set actionClass(value: UIActionClass) {
33 this._actionClass = value;
34 }
35 public get actionClass(): UIActionClass {
36 return this._actionClass;
37 }
38
39 public get Layer(): UIGroupEnum {
40 return this.layer;
41 }
42
43 /*生命周期接口**********************************************************************************************************************/
44
45 /**
46 * 界面初始化
47 * @constructor
48 */
49 public OnInit(param: any): void {
50 this.RegisterBtn();
51 }
52
53 /**
54 * 界面每次打开
55 * @constructor
56 */
57 public OnOpen(param: any) {
58 this.RegisterEvent();
59
60 this.ExpandPanel();
61 }
62
63 /**
64 * 界面每次关闭
65 * @constructor
66 */
67 public OnClose(param: any) {
68 this.UnRegisterEvent();
69
70 this.ShrinkPanel();
71 }
72
73 /**
74 * 界面销毁
75 * @constructor
76 */
77 public OnDeInit(param: any): void {
78 }
79
80 /**
81 * 面板被缓存
82 */
83 public OnCache(): void {
84
85 }
86
87 /**
88 * 面板从缓存中被复用出来
89 */
90 public OnResume(): void {
91
92 }
93
94 /**
95 * 界面弹出(张开)动画结束时调用 无动画不会触发
96 */
97 protected OnExpandAniEnd() {
98
99 }
100
101 /**
102 * 界面关闭(收缩)动画结束时调用 无动画不会触发
103 * @constructor
104 */
105 protected OnShrinkAniEnd() {
106
107 }
108
109 /*界面逻辑关接口**********************************************************************************************************************/
110
111 /**
112 * 打开面板
113 */
114 private ExpandPanel() {
115 this.grayMaskNode && Tween.stopAllByTarget(this.grayMaskNode);
116 this.boxNode && Tween.stopAllByTarget(this.boxNode);
117
118 this.LoadPanelStyle();
119 if (this.isAnimation && this.grayMaskNode && this.boxNode) {
120 // this.DoExpandAni();
121 this.DoExpandAniByAction();
122 }
123 }
124
125 /**
126 * 关闭面板
127 */
128 private async ShrinkPanel() {
129 this.grayMaskNode && Tween.stopAllByTarget(this.grayMaskNode);
130 this.boxNode && Tween.stopAllByTarget(this.boxNode);
131
132 this.closeBtn && (this.closeBtn.getComponent(Button)!.interactable = false);
133 if (this.isAnimation && this.grayMaskNode && this.boxNode) {
134 // this.DoShrinkAni();
135 await this.DoShrinkAniByAction();
136 }
137 this.node.active = false;
138 }
139
140 /**
141 * 加载面板动画样式
142 * @constructor
143 * @private
144 */
145 private LoadPanelStyle() {
146 if (this.isAnimation) {
147 this.LoadAnimationStyle();
148 } else {
149 this.LoadNormalStyle();
150 }
151 // 确保节点可见
152 this.node.active = true;
153 this.closeBtn && (this.closeBtn.getComponent(Button)!.interactable = true);
154 }
155
156 /**
157 * 面板播放动画需要加载的样式
158 * @constructor
159 * @private
160 */
161 private LoadAnimationStyle() {
162 const aniType = this.actionClass.getAniType();
163
164 if (!this.boxNode) {
165 return;
166 }
167
168 // 先判断有没有uiopacity组件,没有则增加组件
169 if (!this.grayMaskNode.getComponent(UIOpacity)) {
170 this.grayMaskNode.addComponent(UIOpacity);
171 }
172 if (!this.boxNode.getComponent(UIOpacity)) {
173 this.boxNode.addComponent(UIOpacity);
174 }
175 this.grayMaskNode.getComponent(UIOpacity)!.opacity = UIPanelAniStyle.MaskAnimateOpacity;
176 this.boxNode.getComponent(UIOpacity)!.opacity = UIPanelAniStyle.BoxNormalOpacity;
177
178 if (!this.boxNode) {
179 return;
180 }
181
182 if (this.actionClass.actionType === "fade") {
183 this.boxNode.getComponent(UIOpacity)!.opacity = (aniType.CloseValue as number | undefined) ?? UIPanelAniStyle.BoxAnimateOpacity;
184 return;
185 }
186
187 if (this.actionClass.actionType === "scale") {
188 this.boxNode.scale = (aniType.CloseValue as Vec3 | undefined)?.clone() || new Vec3(UIPanelAniStyle.BoxAnimateScale, UIPanelAniStyle.BoxAnimateScale, 1);
189 return;
190 }
191
192 if (aniType instanceof UIBaseMoveAction) {
193 const movePositions = aniType.getMovePositions(this.boxNode);
194 movePositions && this.boxNode.setPosition(movePositions.hide);
195 }
196 }
197
198 /**
199 * 面板正常样式加载
200 * @private
201 */
202 private LoadNormalStyle() {
203 this.boxNode && (this.boxNode.getComponent(UIOpacity)!.opacity = UIPanelAniStyle.BoxNormalOpacity);
204 this.boxNode && (this.boxNode.scale = new Vec3(UIPanelAniStyle.BoxNormalScale, UIPanelAniStyle.BoxNormalScale, 1));
205 this.grayMaskNode && (this.grayMaskNode.getComponent(UIOpacity)!.opacity = UIPanelAniStyle.MaskNormalOpacity);
206 }
207
208
209 /**
210 * 执行展开动画
211 * @private
212 */
213 private DoExpandAni() {
214 let maskTween = tween(this.grayMaskNode.getComponent(UIOpacity)!).to(UIPanelAniStyle.ExpandInterval, {
215 opacity: UIPanelAniStyle.MaskNormalOpacity
216 });
217
218 let boxTween1 =
219 tween(this.boxNode.getComponent(UIOpacity)!)
220 .to(UIPanelAniStyle.ExpandInterval, { opacity: UIPanelAniStyle.BoxNormalOpacity }, { easing: "backOut" });
221 let boxTween2 =
222 tween(this.boxNode)
223 .to(UIPanelAniStyle.ExpandInterval, { scale: new Vec3(UIPanelAniStyle.BoxNormalScale, UIPanelAniStyle.BoxNormalScale, 1) }, { easing: "backOut" });
224
225 maskTween.start();
226 tween(this.boxNode).parallel(boxTween1, boxTween2).call(() => {
227 this.OnExpandAniEnd();
228 }).start();
229 }
230
231 /**
232 * 执行收缩动画
233 * @private
234 */
235 private DoShrinkAni() {
236 let maskTween = tween(this.grayMaskNode.getComponent(UIOpacity)!).to(UIPanelAniStyle.ShrinkInterval, {
237 opacity: 0
238 });
239
240 let boxTween1 =
241 tween(this.boxNode.getComponent(UIOpacity)!)
242 .to(UIPanelAniStyle.ShrinkInterval, { opacity: 0 });
243 let boxTween2 =
244 tween(this.boxNode)
245 .to(UIPanelAniStyle.ShrinkInterval, { scale: Vec3.ZERO }, { easing: "backIn" });
246
247 maskTween.start();
248 tween(this.boxNode).delay(UIPanelAniStyle.ShrinkDelay).parallel(boxTween1, boxTween2).call(() => {
249 this.OnShrinkAniEnd();
250 }).start();
251 }
252
253 /**
254 * 执行展开动画(使用动画类)-TODO:待review
255 */
256 public async DoExpandAniByAction() {
257 const param = this.actionClass;
258 const aniType = param.getAniType();
259 const movePositions = aniType instanceof UIBaseMoveAction ? aniType.getMovePositions(this.boxNode) : null;
260
261 try {
262 await Promise.all([
263 UtilityAction.show(this.grayMaskNode, {
264 duration: UIPanelAniStyle.ExpandInterval,
265 type: "fade",
266 useData: {
267 show: UIPanelAniStyle.MaskNormalOpacity,
268 hide: UIPanelAniStyle.MaskAnimateOpacity
269 }
270 }),
271 UtilityAction.show(this.boxNode, {
272 type: param.actionType,
273 duration: aniType.duration,
274 useData: {
275 show: (movePositions?.show || aniType.OpenValue) as any,
276 hide: (movePositions?.hide || aniType.CloseValue) as any,
277 easing: aniType.easing,
278 fromType: aniType instanceof UIBaseMoveAction ? aniType.formType : undefined
279 }
280 })
281 ]);
282 this.OnExpandAniEnd();
283 } catch (error) {
284 console.error(`[UIBasePanel.DoExpandAniByAction] ${this.node.name} expand animation failed`, error);
285 }
286 }
287
288 /**
289 * 执行收缩动画(使用动画类)-TODO:待review
290 */
291 public async DoShrinkAniByAction() {
292 const param = this.actionClass;
293 const aniType = param.getAniType();
294 const movePositions = aniType instanceof UIBaseMoveAction ? aniType.getMovePositions(this.boxNode) : null;
295 //如果没有隐藏动画需求,则默认都是渐隐藏动画
296 if (!param.hasHideAction) {
297 await this.DoHideAni_Action_NoHide(param);
298 this.OnShrinkAniEnd();
299 return;
300 }
301 try {
302 await Promise.all([
303 UtilityAction.hide(this.grayMaskNode, {
304 duration: UIPanelAniStyle.ShrinkInterval,
305 type: "fade",
306 }),
307 UtilityAction.hide(this.boxNode, {
308 type: param.actionType,
309 duration: aniType.duration,
310 useData: {
311 show: (movePositions?.show || aniType.OpenValue) as any,
312 hide: (movePositions?.hide || aniType.CloseValue) as any,
313 easing: aniType.easing,
314 fromType: aniType instanceof UIBaseMoveAction ? aniType.formType : undefined
315 }
316 })
317 ]);
318 this.OnShrinkAniEnd();
319 } catch (error) {
320 console.error(`[UIBasePanel.DoShrinkAniByAction] ${this.node.name} shrink animation failed`, error);
321 }
322 }
323
324 /**
325 * 执行隐藏动画(使用动画类)-TODO:待review
326 */
327 private async DoHideAni_Action_NoHide(param: any) {
328 await Promise.all([
329 UtilityAction.hide(this.grayMaskNode, {
330 duration: UIPanelAniStyle.ShrinkInterval,
331 type: "fade",
332 }),
333 UtilityAction.hide(this.boxNode, {
334 duration: UIPanelAniStyle.ShrinkInterval,
335 type: "fade",
336 })
337 ]);
338 }
339
340
341 /*注册事件相关**********************************************************************************************************************/
342
343 /**
344 * 按钮事件注册
345 * @protected
346 */
347 protected RegisterBtn() {
348 this.closeBtn && UtilityNodeHelper.AddClick(this.closeBtn, this.OnCloseClick, this);
349 }
350
351 protected OnCloseClick() {
352 Framework.UI.ClosePanel(this.node.name);
353 }
354
355 /**
356 * 事件注册
357 */
358 protected RegisterEvent() {
359
360 }
361
362 /**
363 * 事件注销
364 */
365 protected UnRegisterEvent() {
366
367 }
368}
讲解369 行
面板基类人工通读
UIBasePanel.ts
所有界面的脚本基类,规定初始化、打开、关闭、销毁与缓存复用的生命周期,并封装遮罩与盒子的开闭动画。UIManager 在实例化、打开、关闭、销毁时按固定顺序调用这些钩子,子类覆写后接入业务。
先看六个生命周期回调与 UIManager 的调用顺序,再看 ExpandPanel 与 ShrinkPanel 的动画分支,最后看两个 UtilityAction 版本。
特殊处理与易错点
- 面板生命周期OnInit 只在首次实例化时调用一次且仅注册按钮;OnOpen 每次打开都调用;OnClose 每次关闭调用,缓存复用不走 OnInit。L49
- 异步竞态OnClose 调用 ShrinkPanel 但不等待,面板会先被 UIManager 挂到缓存组,节点真正不可见要等收缩动画结束。L128
- 易错点关闭时若关闭按钮存在会先禁用其交互,只有再次打开进入 LoadPanelStyle 才恢复可点击。L132
- 易错点LoadNormalStyle 直接对 UIOpacity 组件取非空后赋值,关闭动画且节点上没有该组件时会抛错。L203
- 易错点LoadAnimationStyle 只判空盒子节点就访问遮罩节点的 UIOpacity,遮罩未配置时会空引用。L169
- 异常兜底展开与收缩动画异常只打印错误日志,不会调用对应的动画结束钩子。L283
13注释UI界面基类
14注释UIBasePanel:面板基类:定义 OnInit/OnOpen/OnClose/OnCache/OnResume
17属性面板所属分组,UIManager 创建与复用时据此挂到对应组节点。
19属性遮罩节点,开闭动画对它做透明度渐变。
21属性内容盒子节点,承载透明度、缩放或位移动画。
23注释布尔默认值已提供属性类型。
26属性关闭按钮节点,注册时绑定点击,关闭动画期间被禁用。
29属性面板动画配置集合,决定开闭使用淡入淡出、缩放还是移动。
31方法公开读取面板动画配置引用,并通过编辑器私有setter替换配置。
39方法读取编辑器配置的面板UI层级,供管理器选择挂载容器。
49方法首次实例化后调用一次,默认只注册关闭按钮点击,不注册事件也不播放动画。
57方法每次打开都会调用,先注册事件监听,再执行展开流程。
67方法每次关闭调用,先注销事件监听,再启动异步收缩,动画结束后隐藏节点。
77方法销毁前的钩子,默认空实现,供子类释放自身资源。
83方法面板关闭后被放入缓存组时调用,默认空实现。
90方法缓存面板被复用时调用,触发在 OnOpen 之前,默认空实现。
97方法展开动画正常结束时调用,无动画或动画异常不会触发。
105方法收缩动画正常结束时调用,无动画或动画异常不会触发。
114方法先停止遮罩与盒子上的旧 Tween,加载开闭初始样式,动画开启时执行展开动画。
128方法停止旧 Tween,禁用关闭按钮,动画开启时等待收缩动画,最后把节点设为不可见。
145方法按动画开关选择加载动画或常规样式,随后保证节点可见并恢复关闭按钮交互。
152注释确保节点可见
161方法取当前动画类型,补齐 UIOpacity 后按类型把盒子设到关闭态透明度、缩放或屏幕外坐标。
169注释先判断有没有uiopacity组件,没有则增加组件
202方法直接把盒子透明度与缩放设为常规值、遮罩设为常规透明度,要求节点已挂透明度组件。
213方法用 Tween 并行播放遮罩透明度与盒子透明度、缩放变化,结束后调用展开动画结束钩子。
235方法用 Tween 播放遮罩与盒子淡出并缩小,延迟后调用收缩动画结束钩子。
256方法用 UtilityAction 同时展示遮罩与盒子,两者都完成后调用展开动画结束钩子。
291方法未开启隐藏动画时走纯淡出,否则同时隐藏遮罩与盒子,完成后调用收缩结束钩子。
296注释如果没有隐藏动画需求,则默认都是渐隐藏动画
327方法用淡出同时隐藏遮罩与盒子,不播放盒子本身的位移或缩放退场。
347方法若配置了关闭按钮,为其绑定点击回调。
351方法以当前节点名调用 UI 管理器关闭本面板。
358方法默认空实现,供子类注册事件监听。
365方法默认空实现,供子类注销事件监听。