1. 項目概述為什么事件優先級是Cocos交互的“交通規則”在Cocos Creator里做UI或者游戲交互你肯定遇到過這種頭疼事一個按鈕明明在最上層點擊卻沒反應或者滑動一個列表結果底下的某個元素也跟著被觸發了。這感覺就像十字路口沒有紅綠燈所有車輛和行人亂成一團誰也不知道誰先走。問題的根源往往就出在事件優先級這個核心機制上沒理清楚。事件系統是Cocos交互的基石它決定了當用戶點擊、觸摸屏幕時哪個節點Node能“聽到”并響應這個操作。如果優先級設置不當就會導致事件響應混亂、UI邏輯錯亂甚至出現難以調試的Bug。很多開發者尤其是剛接觸Cocos不久的朋友往往只停留在node.on注冊事件的層面對事件如何在節點樹中“流動”、如何被“攔截”、以及Canvas之間如何“競爭”這些深層機制一知半解。結果就是項目稍微復雜一點交互邏輯就開始“打架”。這篇文章我們就來徹底搞懂Cocos Creator的事件優先級機制。我會結合官方文檔的核心原理和多年踩坑經驗用最直白的方式帶你從事件的生命周期捕獲、目標、冒泡開始一步步拆解事件在節點樹中的傳遞路徑分析Canvas的priority屬性如何成為跨層級的“裁判”并深入探討useCapture、propagationStopped、preventSwallow這些關鍵API的實戰用法。目標是讓你在5分鐘內不僅知道“是什么”更明白“為什么”和“怎么用”從此告別交互混亂實現精準的響應控制。2. 事件系統的核心生命周期與傳遞路徑要控制事件首先得知道它從哪來、到哪去。Cocos Creator的事件系統借鑒了Web標準一個事件的完整生命周期分為三個階段捕獲階段、目標階段和冒泡階段。理解這三個階段是掌握優先級控制的前提。2.1 事件的三個階段捕獲、目標與冒泡想象一下你用手指點擊屏幕上的一個按鈕節點C。這個點擊事件并不是直接發給C的它有一個完整的旅程。1. 捕獲階段 (Capture Phase):事件從場景的根節點通常是Scene出發像雷達波一樣沿著節點樹自上而下地向目標節點傳播。這個階段的目標是讓父節點有機會在事件到達具體目標之前就攔截或處理它。在Cocos中默認情況下我們監聽事件都是在目標或冒泡階段要監聽捕獲階段的事件需要在on方法中傳入第四個參數useCapture為true。2. 目標階段 (Target Phase):事件到達了它的直接目標——你點擊的那個節點C。在這里所有注冊在節點C上的、針對該事件的監聽器無論是否使用捕獲都會被觸發。3. 冒泡階段 (Bubble Phase):事件處理完目標節點后并不會立刻消失而是會沿著節點樹自下而上地“冒泡”回去從節點C傳遞給它的父節點B再傳遞給B的父節點A以此類推直到根節點。這是我們最常使用的事件監聽階段因為它符合直覺先處理具體目標再讓父容器知曉。2.2 事件傳遞路徑與節點樹關系事件傳遞路徑嚴格遵循節點Node的層級關系。我們用一個簡單的節點樹來演示A - B - C其中C是B的子節點B是A的子節點。當你點擊C節點區域時捕獲階段事件從根節點假設為Scene開始向下傳遞。路徑可能是Scene - A - B。如果這些節點上注冊了捕獲階段的監聽器useCapture: true它們會按此順序被調用。目標階段事件到達C。在C上注冊的所有監聽器被調用。冒泡階段事件從C開始向上冒泡。路徑是C - B - A - Scene。在B和A上注冊的非捕獲監聽器會按此順序被調用。關鍵理解事件的“流動”路徑是固定的由節點層級決定。我們所說的“優先級控制”本質上是在這個固定的流動路徑上決定哪個監聽器先執行以及是否讓事件繼續流動。2.3 同級節點的事件歸屬誰在上層誰先響應當兩個節點例如B和C是兄弟關系擁有同一個父節點A且它們的渲染區域有重疊時事件會優先歸屬于哪個節點答案是渲染層級更高的節點。在Cocos Creator中節點在層級管理器中的排列順序從上到下決定了它們的渲染順序。排在下方的節點渲染在上層。當發生點擊時系統會從最上層的節點開始進行碰撞檢測。假設B和C是兄弟節點C在層級管理器中排在B的下方因此C渲染在B的上層。當你點擊兩者重疊的區域時事件會首先嘗試命中C上層節點。如果C的UITransform組件尺寸覆蓋了該點那么C就是目標節點事件在C上觸發目標階段然后向父節點A冒泡。B節點根本不會接收到這個觸摸事件。只有當C不處理這個事件例如C沒有UITransform組件或者其enabled為false事件才會“穿透”C去檢測下層的B。這個機制是處理UI層疊時事件響應的基礎規則。很多時候按鈕“點不到”就是因為被一個透明的、或者沒有交互但渲染在上層的節點給“擋住”了。3. 跨層級的仲裁者Canvas的Priority屬性上面講的是單個Canvas畫布內部節點樹的事件傳遞。如果你的場景里有多個Canvas呢比如一個用于主UI一個用于彈出窗口一個用于新手引導遮罩。它們之間的點擊事件誰先響應這就輪到Canvas節點的priority屬性登場了它是決定跨Canvas事件響應順序的終極裁判。3.1 Priority屬性的定義與作用priority是Canvas組件或Camera組件因為Canvas依賴于Camera進行渲染排序上的一個整型屬性。它的值越大優先級越高。當觸摸點落在多個Canvas的渲染區域內時系統會優先將事件派發給priority值最大的Canvas下的節點樹進行處理。這個機制非常重要因為它允許我們構建復雜的UI層級。例如主界面Canvaspriority 0彈窗Canvaspriority 10新手引導/遮罩Canvaspriority 100這樣當引導層出現時無論它覆蓋在哪個UI上所有觸摸事件都會優先由引導層處理從而屏蔽下層UI的交互實現完美的引導鎖定效果。3.2 多Canvas場景下的事件派發邏輯讓我們理清多Canvas下的完整事件派發邏輯確定目標Canvas當觸摸發生時引擎會收集所有包含該觸摸點的Canvas然后按照它們的priority值從大到小排序。事件穿透與攔截引擎從priority最高的Canvas開始嘗試在其節點樹中尋找目標節點遵循2.3節的同級節點上層優先規則。如果在該Canvas的節點樹中事件被成功響應并且被攔截例如被一個Button組件處理它內部會調用event.propagationStopped true那么事件派發就此結束更低優先級的Canvas將完全收不到這個事件。如果該Canvas的節點樹中沒有節點處理這個事件或者處理了但沒有攔截propagationStopped為false那么事件會“穿透”到這個Canvas引擎繼續嘗試下一個priority更低的Canvas。同Priority的競爭如果兩個Canvas的priority值相同那么它們之間的順序將取決于它們在節點樹中的先后順序通常是創建順序或掛載順序但這具有不確定性在開發中應避免依賴此行為而是明確設置不同的priority。一個常見的誤區認為高priority的Canvas會“蓋住”低優先級的Canvas。從事件角度看確實如此。但從渲染角度看priority不直接影響渲染順序。渲染順序主要由節點在層級管理器中的順序和Canvas的Order值決定。一個priority很高的Canvas如引導層如果其節點在渲染順序上被排在了后面視覺上可能被其他東西擋住但它依然能優先接收事件。因此UI的視覺層和事件響應層需要通過priority和渲染順序共同管理。3.3 實戰利用Priority構建UI管理系統在實際項目中我通常會定義一個UI管理層來統一管理所有Canvas的優先級。這里分享一個簡單的模式// UIManager.ts export class UIManager { // 定義優先級常量 public static readonly PRIORITY { SCENE: 0, // 場景層 NORMAL_UI: 10, // 普通UI層 POPUP: 100, // 彈窗層 GUIDE: 1000, // 引導/遮罩層 ALERT: 2000, // 系統警告層最高 }; private static _canvasMap: Mapstring, Canvas new Map(); // 注冊Canvas static registerCanvas(name: string, canvas: Canvas, defaultPriority?: number) { this._canvasMap.set(name, canvas); if (defaultPriority ! undefined) { canvas.priority defaultPriority; } } // 動態修改Canvas優先級例如臨時提升某個彈窗的優先級 static setCanvasPriority(name: string, priority: number) { const canvas this._canvasMap.get(name); if (canvas) { canvas.priority priority; } } } // 在某個UI根節點腳本中 import { _decorator, Component, Canvas } from cc; const { ccclass, property } _decorator; ccclass(UIRoot) export class UIRoot extends Component { property(Canvas) canvas: Canvas null!; start() { UIManager.registerCanvas(MainMenu, this.canvas, UIManager.PRIORITY.NORMAL_UI); } }通過這種方式你可以清晰地規劃整個項目的UI層級避免優先級沖突。當需要彈出新窗口時只需確保其所在Canvas的priority高于當前所有UI即可。4. 精細控制攔截、穿透與捕獲監聽掌握了Canvas層級的仲裁后我們還需要在單個節點樹內部進行更精細的事件流控制。Cocos提供了幾個強大的API來實現這一點。4.1 停止事件傳播event.propagationStopped這是最常用的事件控制方法。在事件監聽回調函數中你可以調用event.propagationStopped true來立即停止事件的進一步傳播。在目標階段調用會阻止事件進入冒泡階段。父節點將收不到這個事件。在冒泡階段調用會阻止事件繼續向更上層的父節點冒泡。典型應用場景按鈕組件。內置的Button組件在響應點擊后會自動調用event.propagationStopped true防止點擊事件穿透到背景或其他UI元素上。我們在自定義組件中如果希望某個節點“獨占”某個事件也應該這樣做。this.node.on(Node.EventType.TOUCH_END, (event: EventTouch) { console.log(處理點擊邏輯例如播放音效、跳轉界面); // 處理完畢后停止事件冒泡防止觸發父容器的點擊事件 event.propagationStopped true; }, this);4.2 阻止事件吞噬event.preventSwallow (v3.4)在3.4版本之前如果一個上層節點如圖層C響應了事件根據2.3節的規則下層的兄弟節點如圖層B是根本收不到這個事件的這叫“事件吞噬”。從v3.4開始Cocos引入了event.preventSwallow屬性允許事件穿透到被覆蓋的同級節點。使用方法在希望穿透的事件監聽器中設置event.preventSwallow true。注意這個屬性通常需要在TOUCH_START事件中設置并且為了邏輯一致對應的TOUCH_END事件可能也需要設置。應用場景實現一些特殊的UI效果比如一個半透明的頂層面板你希望點擊它時它自身做出反應如變暗但同時點擊也能穿透到下層的一個特定按鈕上。這時就需要在下層按鈕的TOUCH_START監聽器中設置preventSwallow。// 下層按鈕的腳本 this.node.on(Node.EventType.TOUCH_START, (event: EventTouch) { // 允許事件穿透即使被上層節點覆蓋也能接收到TOUCH_START event.preventSwallow true; }, this); this.node.on(Node.EventType.TOUCH_END, (event: EventTouch) { // 通常END事件也需要對應設置但取決于具體業務邏輯 // event.preventSwallow true; console.log(下層按鈕被點擊了); }, this);重要提醒濫用preventSwallow會破壞事件處理的默認邏輯可能導致意想不到的交互問題并帶來一定的性能開銷因為需要檢測更多節點。請僅在明確需要穿透行為的場景下謹慎使用。4.3 捕獲階段監聽useCapture參數如前所述默認的node.on監聽的是目標或冒泡階段。如果你需要在事件到達目標節點之前就由父節點進行處理或攔截就需要使用捕獲階段監聽。使用方法在on方法中傳入第四個參數useCapture為true。// 在父節點A的腳本中 this.node.on(Node.EventType.TOUCH_START, this.onParentTouchStart, this, true); // 注意第四個參數 true private onParentTouchStart(event: EventTouch) { console.log(捕獲階段父節點A先于子節點接收到TOUCH_START); // 可以在這里進行一些預處理或者根據條件決定是否阻止事件傳遞到子節點 // if (someCondition) { // event.propagationStopped true; // 子節點將收不到這個事件 // } }執行順序對于同一個事件如TOUCH_START其監聽器的觸發順序為所有注冊了useCapture: true的監聽器按從根節點到目標節點的順序觸發捕獲階段。目標節點自身的監聽器觸發目標階段。所有注冊了useCapture: false默認的監聽器按從目標節點到根節點的順序觸發冒泡階段。經典應用ScrollView。ScrollView組件需要在子內容如Item響應拖動之前先判斷是否應該開始滾動。它就是在容器節點上使用捕獲階段監聽TOUCH_START以便優先處理滾動邏輯。如果判斷為滾動則可能阻止事件傳遞到子Item。5. 實戰避坑指南與高級技巧理論懂了但在實際編碼中還是容易踩坑。下面是我總結的幾個常見問題和進階技巧。5.1 常見問題排查清單當你發現事件不響應或響應錯亂時可以按以下清單排查節點是否激活且可交互檢查節點的active屬性是否為true。檢查節點或其父節點是否有Button、BlockInputEvents等組件且enabled為true。對于2D UI確保節點上有UITransform組件。事件是否被攔截檢查目標節點或其父節點的監聽器中是否調用了event.propagationStopped true過早地停止了事件傳播。檢查是否有更高priority的Canvas攔截了事件。節點層級與渲染順序在層級管理器中確認目標節點是否被其他節點完全覆蓋。被覆蓋的節點無法接收到觸摸事件除非使用preventSwallow。檢查節點的zIndex或Canvas的Order確保其在渲染層面是可見的。監聽器注冊與銷毀確認on監聽確實在start或onEnable中正確注冊。非常重要在組件銷毀onDestroy或節點失活onDisable時使用this.node.off或this.node.targetOff(this)取消注冊監聽防止內存泄漏和調用已銷毀組件的方法。多觸點多點觸控是否關閉如果你的項目不需要多點觸控但出現了奇怪的事件干擾檢查是否在項目設置或代碼中關閉了多點觸控macro.ENABLE_MULTI_TOUCH false;。5.2 性能優化建議減少不必要的監聽只在需要交互的節點上注冊事件監聽。避免在大量動態生成的Item上注冊監聽考慮使用事件委托在父容器注冊通過event.target判斷具體目標。及時銷毀監聽這是最容易被忽視的性能點。未銷毀的監聽器會導致節點無法被正確垃圾回收。慎用preventSwallow和捕獲階段這兩種機制都需要引擎進行額外的計算和判斷在復雜UI中大量使用可能影響性能。合理劃分Canvas不要將所有UI都塞進一個Canvas。將功能模塊劃分到不同的Canvas并設置合理的priority有助于引擎優化事件檢測范圍。5.3 自定義事件與系統事件暫停自定義事件除了系統觸摸事件你可以通過dispatchEvent派發自定義事件并利用相同的冒泡/捕獲機制傳遞。import { Event, Node } from cc; // 1. 定義自定義事件類可選用于攜帶數據 class CustomEvent extends Event { constructor(name: string, public customData: any) { super(name, true); // 第二個參數true表示允許冒泡 } } // 2. 在某個節點派發 this.node.dispatchEvent(new CustomEvent(my-event, { value: 123 })); // 3. 在其他節點監聽 parentNode.on(my-event, (event: CustomEvent) { console.log(收到自定義事件:, event.customData.value); }, this);暫停與恢復系統事件你可以使用node.pauseSystemEvents(true)來暫停該節點及其所有子節點上的所有系統輸入事件觸摸、鼠標。這在播放全屏動畫或進行某些模態操作時非常有用。操作完成后記得用node.resumeSystemEvents(true)恢復。5.4 一個綜合案例實現可穿透的模態對話框需求一個模態對話框背景半透明黑色點擊背景關閉對話框但點擊對話框上的按鈕則執行按鈕功能不關閉。// ModalDialog.ts ccclass(ModalDialog) export class ModalDialog extends Component { property(Node) background: Node null!; // 背景遮罩節點 property(Node) content: Node null!; // 對話框內容節點 start() { // 1. 背景遮罩監聽點擊用于關閉 this.background.on(Node.EventType.TOUCH_END, this.closeDialog, this); // 2. 內容區域阻止事件冒泡到背景防止點擊內容也觸發關閉 this.content.on(Node.EventType.TOUCH_END, (event) { event.propagationStopped true; }, this); // 3. 確保對話框所在Canvas的priority足夠高覆蓋其他UI const canvas this.getComponent(Canvas); if (canvas) { canvas.priority UIManager.PRIORITY.POPUP; // 使用之前定義的優先級常量 } } private closeDialog() { this.node.destroy(); // 簡單示例直接銷毀 } }在這個例子中我們利用了事件冒泡機制。點擊背景事件冒泡到背景節點觸發closeDialog。點擊內容區域或內容里的按鈕我們在內容節點的TOUCH_END中調用了event.propagationStopped true阻止了事件繼續向父節點背景冒泡因此不會觸發關閉。同時通過設置高priority確保對話框能屏蔽下層UI的交互。 Cocos Creator事件優先級機制詳解：從捕獲冒泡到Canvas仲裁
1. 項目概述為什么事件優先級是Cocos交互的“交通規則”在Cocos Creator里做UI或者游戲交互你肯定遇到過這種頭疼事一個按鈕明明在最上層點擊卻沒反應或者滑動一個列表結果底下的某個元素也跟著被觸發了。這感覺就像十字路口沒有紅綠燈所有車輛和行人亂成一團誰也不知道誰先走。問題的根源往往就出在事件優先級這個核心機制上沒理清楚。事件系統是Cocos交互的基石它決定了當用戶點擊、觸摸屏幕時哪個節點Node能“聽到”并響應這個操作。如果優先級設置不當就會導致事件響應混亂、UI邏輯錯亂甚至出現難以調試的Bug。很多開發者尤其是剛接觸Cocos不久的朋友往往只停留在node.on注冊事件的層面對事件如何在節點樹中“流動”、如何被“攔截”、以及Canvas之間如何“競爭”這些深層機制一知半解。結果就是項目稍微復雜一點交互邏輯就開始“打架”。這篇文章我們就來徹底搞懂Cocos Creator的事件優先級機制。我會結合官方文檔的核心原理和多年踩坑經驗用最直白的方式帶你從事件的生命周期捕獲、目標、冒泡開始一步步拆解事件在節點樹中的傳遞路徑分析Canvas的priority屬性如何成為跨層級的“裁判”并深入探討useCapture、propagationStopped、preventSwallow這些關鍵API的實戰用法。目標是讓你在5分鐘內不僅知道“是什么”更明白“為什么”和“怎么用”從此告別交互混亂實現精準的響應控制。2. 事件系統的核心生命周期與傳遞路徑要控制事件首先得知道它從哪來、到哪去。Cocos Creator的事件系統借鑒了Web標準一個事件的完整生命周期分為三個階段捕獲階段、目標階段和冒泡階段。理解這三個階段是掌握優先級控制的前提。2.1 事件的三個階段捕獲、目標與冒泡想象一下你用手指點擊屏幕上的一個按鈕節點C。這個點擊事件并不是直接發給C的它有一個完整的旅程。1. 捕獲階段 (Capture Phase):事件從場景的根節點通常是Scene出發像雷達波一樣沿著節點樹自上而下地向目標節點傳播。這個階段的目標是讓父節點有機會在事件到達具體目標之前就攔截或處理它。在Cocos中默認情況下我們監聽事件都是在目標或冒泡階段要監聽捕獲階段的事件需要在on方法中傳入第四個參數useCapture為true。2. 目標階段 (Target Phase):事件到達了它的直接目標——你點擊的那個節點C。在這里所有注冊在節點C上的、針對該事件的監聽器無論是否使用捕獲都會被觸發。3. 冒泡階段 (Bubble Phase):事件處理完目標節點后并不會立刻消失而是會沿著節點樹自下而上地“冒泡”回去從節點C傳遞給它的父節點B再傳遞給B的父節點A以此類推直到根節點。這是我們最常使用的事件監聽階段因為它符合直覺先處理具體目標再讓父容器知曉。2.2 事件傳遞路徑與節點樹關系事件傳遞路徑嚴格遵循節點Node的層級關系。我們用一個簡單的節點樹來演示A - B - C其中C是B的子節點B是A的子節點。當你點擊C節點區域時捕獲階段事件從根節點假設為Scene開始向下傳遞。路徑可能是Scene - A - B。如果這些節點上注冊了捕獲階段的監聽器useCapture: true它們會按此順序被調用。目標階段事件到達C。在C上注冊的所有監聽器被調用。冒泡階段事件從C開始向上冒泡。路徑是C - B - A - Scene。在B和A上注冊的非捕獲監聽器會按此順序被調用。關鍵理解事件的“流動”路徑是固定的由節點層級決定。我們所說的“優先級控制”本質上是在這個固定的流動路徑上決定哪個監聽器先執行以及是否讓事件繼續流動。2.3 同級節點的事件歸屬誰在上層誰先響應當兩個節點例如B和C是兄弟關系擁有同一個父節點A且它們的渲染區域有重疊時事件會優先歸屬于哪個節點答案是渲染層級更高的節點。在Cocos Creator中節點在層級管理器中的排列順序從上到下決定了它們的渲染順序。排在下方的節點渲染在上層。當發生點擊時系統會從最上層的節點開始進行碰撞檢測。假設B和C是兄弟節點C在層級管理器中排在B的下方因此C渲染在B的上層。當你點擊兩者重疊的區域時事件會首先嘗試命中C上層節點。如果C的UITransform組件尺寸覆蓋了該點那么C就是目標節點事件在C上觸發目標階段然后向父節點A冒泡。B節點根本不會接收到這個觸摸事件。只有當C不處理這個事件例如C沒有UITransform組件或者其enabled為false事件才會“穿透”C去檢測下層的B。這個機制是處理UI層疊時事件響應的基礎規則。很多時候按鈕“點不到”就是因為被一個透明的、或者沒有交互但渲染在上層的節點給“擋住”了。3. 跨層級的仲裁者Canvas的Priority屬性上面講的是單個Canvas畫布內部節點樹的事件傳遞。如果你的場景里有多個Canvas呢比如一個用于主UI一個用于彈出窗口一個用于新手引導遮罩。它們之間的點擊事件誰先響應這就輪到Canvas節點的priority屬性登場了它是決定跨Canvas事件響應順序的終極裁判。3.1 Priority屬性的定義與作用priority是Canvas組件或Camera組件因為Canvas依賴于Camera進行渲染排序上的一個整型屬性。它的值越大優先級越高。當觸摸點落在多個Canvas的渲染區域內時系統會優先將事件派發給priority值最大的Canvas下的節點樹進行處理。這個機制非常重要因為它允許我們構建復雜的UI層級。例如主界面Canvaspriority 0彈窗Canvaspriority 10新手引導/遮罩Canvaspriority 100這樣當引導層出現時無論它覆蓋在哪個UI上所有觸摸事件都會優先由引導層處理從而屏蔽下層UI的交互實現完美的引導鎖定效果。3.2 多Canvas場景下的事件派發邏輯讓我們理清多Canvas下的完整事件派發邏輯確定目標Canvas當觸摸發生時引擎會收集所有包含該觸摸點的Canvas然后按照它們的priority值從大到小排序。事件穿透與攔截引擎從priority最高的Canvas開始嘗試在其節點樹中尋找目標節點遵循2.3節的同級節點上層優先規則。如果在該Canvas的節點樹中事件被成功響應并且被攔截例如被一個Button組件處理它內部會調用event.propagationStopped true那么事件派發就此結束更低優先級的Canvas將完全收不到這個事件。如果該Canvas的節點樹中沒有節點處理這個事件或者處理了但沒有攔截propagationStopped為false那么事件會“穿透”到這個Canvas引擎繼續嘗試下一個priority更低的Canvas。同Priority的競爭如果兩個Canvas的priority值相同那么它們之間的順序將取決于它們在節點樹中的先后順序通常是創建順序或掛載順序但這具有不確定性在開發中應避免依賴此行為而是明確設置不同的priority。一個常見的誤區認為高priority的Canvas會“蓋住”低優先級的Canvas。從事件角度看確實如此。但從渲染角度看priority不直接影響渲染順序。渲染順序主要由節點在層級管理器中的順序和Canvas的Order值決定。一個priority很高的Canvas如引導層如果其節點在渲染順序上被排在了后面視覺上可能被其他東西擋住但它依然能優先接收事件。因此UI的視覺層和事件響應層需要通過priority和渲染順序共同管理。3.3 實戰利用Priority構建UI管理系統在實際項目中我通常會定義一個UI管理層來統一管理所有Canvas的優先級。這里分享一個簡單的模式// UIManager.ts export class UIManager { // 定義優先級常量 public static readonly PRIORITY { SCENE: 0, // 場景層 NORMAL_UI: 10, // 普通UI層 POPUP: 100, // 彈窗層 GUIDE: 1000, // 引導/遮罩層 ALERT: 2000, // 系統警告層最高 }; private static _canvasMap: Mapstring, Canvas new Map(); // 注冊Canvas static registerCanvas(name: string, canvas: Canvas, defaultPriority?: number) { this._canvasMap.set(name, canvas); if (defaultPriority ! undefined) { canvas.priority defaultPriority; } } // 動態修改Canvas優先級例如臨時提升某個彈窗的優先級 static setCanvasPriority(name: string, priority: number) { const canvas this._canvasMap.get(name); if (canvas) { canvas.priority priority; } } } // 在某個UI根節點腳本中 import { _decorator, Component, Canvas } from cc; const { ccclass, property } _decorator; ccclass(UIRoot) export class UIRoot extends Component { property(Canvas) canvas: Canvas null!; start() { UIManager.registerCanvas(MainMenu, this.canvas, UIManager.PRIORITY.NORMAL_UI); } }通過這種方式你可以清晰地規劃整個項目的UI層級避免優先級沖突。當需要彈出新窗口時只需確保其所在Canvas的priority高于當前所有UI即可。4. 精細控制攔截、穿透與捕獲監聽掌握了Canvas層級的仲裁后我們還需要在單個節點樹內部進行更精細的事件流控制。Cocos提供了幾個強大的API來實現這一點。4.1 停止事件傳播event.propagationStopped這是最常用的事件控制方法。在事件監聽回調函數中你可以調用event.propagationStopped true來立即停止事件的進一步傳播。在目標階段調用會阻止事件進入冒泡階段。父節點將收不到這個事件。在冒泡階段調用會阻止事件繼續向更上層的父節點冒泡。典型應用場景按鈕組件。內置的Button組件在響應點擊后會自動調用event.propagationStopped true防止點擊事件穿透到背景或其他UI元素上。我們在自定義組件中如果希望某個節點“獨占”某個事件也應該這樣做。this.node.on(Node.EventType.TOUCH_END, (event: EventTouch) { console.log(處理點擊邏輯例如播放音效、跳轉界面); // 處理完畢后停止事件冒泡防止觸發父容器的點擊事件 event.propagationStopped true; }, this);4.2 阻止事件吞噬event.preventSwallow (v3.4)在3.4版本之前如果一個上層節點如圖層C響應了事件根據2.3節的規則下層的兄弟節點如圖層B是根本收不到這個事件的這叫“事件吞噬”。從v3.4開始Cocos引入了event.preventSwallow屬性允許事件穿透到被覆蓋的同級節點。使用方法在希望穿透的事件監聽器中設置event.preventSwallow true。注意這個屬性通常需要在TOUCH_START事件中設置并且為了邏輯一致對應的TOUCH_END事件可能也需要設置。應用場景實現一些特殊的UI效果比如一個半透明的頂層面板你希望點擊它時它自身做出反應如變暗但同時點擊也能穿透到下層的一個特定按鈕上。這時就需要在下層按鈕的TOUCH_START監聽器中設置preventSwallow。// 下層按鈕的腳本 this.node.on(Node.EventType.TOUCH_START, (event: EventTouch) { // 允許事件穿透即使被上層節點覆蓋也能接收到TOUCH_START event.preventSwallow true; }, this); this.node.on(Node.EventType.TOUCH_END, (event: EventTouch) { // 通常END事件也需要對應設置但取決于具體業務邏輯 // event.preventSwallow true; console.log(下層按鈕被點擊了); }, this);重要提醒濫用preventSwallow會破壞事件處理的默認邏輯可能導致意想不到的交互問題并帶來一定的性能開銷因為需要檢測更多節點。請僅在明確需要穿透行為的場景下謹慎使用。4.3 捕獲階段監聽useCapture參數如前所述默認的node.on監聽的是目標或冒泡階段。如果你需要在事件到達目標節點之前就由父節點進行處理或攔截就需要使用捕獲階段監聽。使用方法在on方法中傳入第四個參數useCapture為true。// 在父節點A的腳本中 this.node.on(Node.EventType.TOUCH_START, this.onParentTouchStart, this, true); // 注意第四個參數 true private onParentTouchStart(event: EventTouch) { console.log(捕獲階段父節點A先于子節點接收到TOUCH_START); // 可以在這里進行一些預處理或者根據條件決定是否阻止事件傳遞到子節點 // if (someCondition) { // event.propagationStopped true; // 子節點將收不到這個事件 // } }執行順序對于同一個事件如TOUCH_START其監聽器的觸發順序為所有注冊了useCapture: true的監聽器按從根節點到目標節點的順序觸發捕獲階段。目標節點自身的監聽器觸發目標階段。所有注冊了useCapture: false默認的監聽器按從目標節點到根節點的順序觸發冒泡階段。經典應用ScrollView。ScrollView組件需要在子內容如Item響應拖動之前先判斷是否應該開始滾動。它就是在容器節點上使用捕獲階段監聽TOUCH_START以便優先處理滾動邏輯。如果判斷為滾動則可能阻止事件傳遞到子Item。5. 實戰避坑指南與高級技巧理論懂了但在實際編碼中還是容易踩坑。下面是我總結的幾個常見問題和進階技巧。5.1 常見問題排查清單當你發現事件不響應或響應錯亂時可以按以下清單排查節點是否激活且可交互檢查節點的active屬性是否為true。檢查節點或其父節點是否有Button、BlockInputEvents等組件且enabled為true。對于2D UI確保節點上有UITransform組件。事件是否被攔截檢查目標節點或其父節點的監聽器中是否調用了event.propagationStopped true過早地停止了事件傳播。檢查是否有更高priority的Canvas攔截了事件。節點層級與渲染順序在層級管理器中確認目標節點是否被其他節點完全覆蓋。被覆蓋的節點無法接收到觸摸事件除非使用preventSwallow。檢查節點的zIndex或Canvas的Order確保其在渲染層面是可見的。監聽器注冊與銷毀確認on監聽確實在start或onEnable中正確注冊。非常重要在組件銷毀onDestroy或節點失活onDisable時使用this.node.off或this.node.targetOff(this)取消注冊監聽防止內存泄漏和調用已銷毀組件的方法。多觸點多點觸控是否關閉如果你的項目不需要多點觸控但出現了奇怪的事件干擾檢查是否在項目設置或代碼中關閉了多點觸控macro.ENABLE_MULTI_TOUCH false;。5.2 性能優化建議減少不必要的監聽只在需要交互的節點上注冊事件監聽。避免在大量動態生成的Item上注冊監聽考慮使用事件委托在父容器注冊通過event.target判斷具體目標。及時銷毀監聽這是最容易被忽視的性能點。未銷毀的監聽器會導致節點無法被正確垃圾回收。慎用preventSwallow和捕獲階段這兩種機制都需要引擎進行額外的計算和判斷在復雜UI中大量使用可能影響性能。合理劃分Canvas不要將所有UI都塞進一個Canvas。將功能模塊劃分到不同的Canvas并設置合理的priority有助于引擎優化事件檢測范圍。5.3 自定義事件與系統事件暫停自定義事件除了系統觸摸事件你可以通過dispatchEvent派發自定義事件并利用相同的冒泡/捕獲機制傳遞。import { Event, Node } from cc; // 1. 定義自定義事件類可選用于攜帶數據 class CustomEvent extends Event { constructor(name: string, public customData: any) { super(name, true); // 第二個參數true表示允許冒泡 } } // 2. 在某個節點派發 this.node.dispatchEvent(new CustomEvent(my-event, { value: 123 })); // 3. 在其他節點監聽 parentNode.on(my-event, (event: CustomEvent) { console.log(收到自定義事件:, event.customData.value); }, this);暫停與恢復系統事件你可以使用node.pauseSystemEvents(true)來暫停該節點及其所有子節點上的所有系統輸入事件觸摸、鼠標。這在播放全屏動畫或進行某些模態操作時非常有用。操作完成后記得用node.resumeSystemEvents(true)恢復。5.4 一個綜合案例實現可穿透的模態對話框需求一個模態對話框背景半透明黑色點擊背景關閉對話框但點擊對話框上的按鈕則執行按鈕功能不關閉。// ModalDialog.ts ccclass(ModalDialog) export class ModalDialog extends Component { property(Node) background: Node null!; // 背景遮罩節點 property(Node) content: Node null!; // 對話框內容節點 start() { // 1. 背景遮罩監聽點擊用于關閉 this.background.on(Node.EventType.TOUCH_END, this.closeDialog, this); // 2. 內容區域阻止事件冒泡到背景防止點擊內容也觸發關閉 this.content.on(Node.EventType.TOUCH_END, (event) { event.propagationStopped true; }, this); // 3. 確保對話框所在Canvas的priority足夠高覆蓋其他UI const canvas this.getComponent(Canvas); if (canvas) { canvas.priority UIManager.PRIORITY.POPUP; // 使用之前定義的優先級常量 } } private closeDialog() { this.node.destroy(); // 簡單示例直接銷毀 } }在這個例子中我們利用了事件冒泡機制。點擊背景事件冒泡到背景節點觸發closeDialog。點擊內容區域或內容里的按鈕我們在內容節點的TOUCH_END中調用了event.propagationStopped true阻止了事件繼續向父節點背景冒泡因此不會觸發關閉。同時通過設置高priority確保對話框能屏蔽下層UI的交互。