| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
事件目標是 Flash® Player 和 Adobe AIR 事件模型中很重要的一部分，適合作為焦點位置，說明事件在顯示清單階層中的流程。 當發生如按下滑鼠或按下按鍵等事件時，事件物件便會從顯示清單的根傳送到事件流程。事件物件往返於事件目標的旅程，在概念上可分為三個階段：捕捉階段包含從根到事件目標節點之前最後一個節點的旅程；目標階段只包含事件目標節點；而反昇階段則包含在返回顯示清單的根的途中，所遇到的任何後續節點。
一般來說，使用者定義的類別要取得事件傳送功能的最簡便方式，就是擴充 EventDispatcher。 如果無法擴充 (也就是說，如果此類別已經擴充其它類別)，您可以改為實作 IEventDispatcher 介面、建立 EventDispatcher 成員，然後撰寫簡單的攔截程序將呼叫遞送到彙總的 EventDispatcher。
| 方法 | 定義自 | ||
|---|---|---|---|
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。 | IEventDispatcher | ||
會將事件傳送到事件流程。 | IEventDispatcher | ||
會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。 | IEventDispatcher | ||
會從 EventDispatcher 物件移除偵聽程式。 | IEventDispatcher | ||
檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。 | IEventDispatcher | ||
addEventListener | () | 方法 |
public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。您可以在顯示清單上的所有節點，為特定類型的事件、階段與優先順序註冊事件偵聽程式。
當您成功註冊事件偵聽程式後，就不可以透過對 addEventListener() 的額外呼叫來變更其優先順序。 若要變更偵聽程式的優先順序，您必須先呼叫 removeEventListener()。 然後，您就可以使用新的優先順序等級來重新註冊偵聽程式。
一旦您註冊了偵聽程式，對 addEventListener() 來進行後續呼叫，若使用不同的 type 或 useCapture 值，將會導致建立個別的偵聽程式註冊程序。 例如，如果您先將 useCapture 設為 true 來註冊偵聽程式，則只會在捕捉階段進行偵聽。 如果您使用相同的偵聽程式物件 (但將 useCapture 設為 false) 再次呼叫 addEventListener()，會得到兩個不同的偵聽程式： 一個會在捕捉階段進行偵聽，另一個則會在目標與反昇階段進行偵聽。
您無法單獨針對目標階段或反昇階段註冊事件偵聽程式。 由於反昇階段只適用於目標節點的祖系，因此這兩種階段必須一起進行註冊。
當您不再需要事件偵聽程式，可以呼叫 EventDispatcher.removeEventListener() 來移除它，否則可能產生記憶體問題。 含有已註冊之事件偵聽程式的物件不會自動從記憶體中移除，因為垃圾回收器不會將仍保有參照的物件移除。
複製 EventDispatcher 實體並不會將附加在該實體上的事件偵聽程式一併複製 (如果新建立的節點需要事件偵聽程式，則您必須在建立節點後再附加偵聽程式)。 然而，如果您移動了 EventDispatcher 實體，則附加的事件偵聽程式也會跟著移動。
若於此節點正在處理事件的同時將事件偵聽程式註冊到某個節點上，則事件偵聽程式不會在目前階段觸發，但會在事件流程的後續階段 (例如反昇階段) 中觸發。
如果您在節點正在處理事件的同時將事件偵聽程式從節點中移除，則事件偵聽程式還是會被目前的動作觸發。 一旦移除了事件偵聽程式，就無法再叫用它 (除非您為了日後的處理而再次註冊它)。
參數
type:String — 事件類型。
| |
listener:Function — 處理事件的偵聽程式函數。此函數必須接受事件物件當做唯一的參數，而且必須傳回空值，如下列範例所示：
| |
useCapture:Boolean (default = false)useCapture 設為 true，則偵聽程式只會在捕捉階段 (而不是在目標或反昇階段) 處理事件。如果 useCapture 為 false，則偵聽程式只會在目標或反昇階段處理事件。若要在全部三個階段中偵聽事件，請呼叫 addEventListener() 兩次，先將 useCapture 設為 true 後進行第一次呼叫，接著將 useCapture 設為 false 再進行第二次呼叫。
| |
priority:int (default = 0) | |
useWeakReference:Boolean (default = false)類別層級的成員函數不受記憶體回收限制，因此您可以將類別層級成員函數的 |
dispatchEvent | () | 方法 |
hasEventListener | () | 方法 |
public function hasEventListener(type:String):Boolean| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。 這可讓您判斷 EventDispatcher 物件是否已經改變事件流程階層中事件類型的處理方式。 若要判斷特定事件類型是否已經實際觸發事件偵聽程式，請使用 IEventDispatcher.willTrigger()。
hasEventListener() 與 willTrigger() 之間的差異在於 hasEventListener() 只檢查所屬的物件，而 willTrigger() 則會檢查整個事件流程中 type 參數所指定的事件。
參數
type:String — 事件類型。
|
Boolean — 如果註冊了特定類型的偵聽程式，則值為 true 值，否則為 false。
|
相關 API 元素
removeEventListener | () | 方法 |
public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
會從 EventDispatcher 物件移除偵聽程式。 如果沒有相符的偵聽程式以 EventDispatcher 物件來註冊，則呼叫此方法不會產生任何作用。
參數
type:String — 事件類型。
| |
listener:Function — 要移除的偵聽程式物件。
| |
useCapture:Boolean (default = false)removeEventListener() 的兩次呼叫才能移除這兩個階段：一次呼叫的 useCapture 是設為 true，而另一次呼叫的 useCapture 則是設定為 false。
|
willTrigger | () | 方法 |
public function willTrigger(type:String):Boolean| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0, Flash Player 9, Flash Lite 4 |
檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。當特定類型的事件傳送至此 EventDispatcher 物件或其任何後代時，如果事件偵聽程式在事件流程的任何階段觸發，此方法就會傳回 true。
hasEventListener() 與 willTrigger() 之間的差異在於 hasEventListener() 只檢查所屬的物件，而 willTrigger() 則會檢查整個事件流程中 type 參數所指定的事件。
參數
type:String — 事件類型。
|
Boolean — 如果即將觸發特定類型的偵聽程式，則為 true 值，否則為 false。
|
decorDispatcher ) 而 decorDispatcher 變數用於呼叫 addEventListener() (具有自訂事件 doSomething)該變數接著會列印一行文字的 didSomething() 處理 (使用 trace())。
package {
import flash.events.Event;
import flash.display.Sprite;
public class IEventDispatcherExample extends Sprite {
public function IEventDispatcherExample() {
var decorDispatcher:DecoratedDispatcher = new DecoratedDispatcher();
decorDispatcher.addEventListener("doSomething", didSomething);
decorDispatcher.dispatchEvent(new Event("doSomething"));
}
public function didSomething(evt:Event):void {
trace(">> didSomething");
}
}
}
import flash.events.IEventDispatcher;
import flash.events.EventDispatcher;
import flash.events.Event;
class DecoratedDispatcher implements IEventDispatcher {
private var dispatcher:EventDispatcher;
public function DecoratedDispatcher() {
dispatcher = new EventDispatcher(this);
}
public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void{
dispatcher.addEventListener(type, listener, useCapture, priority);
}
public function dispatchEvent(evt:Event):Boolean{
return dispatcher.dispatchEvent(evt);
}
public function hasEventListener(type:String):Boolean{
return dispatcher.hasEventListener(type);
}
public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void{
dispatcher.removeEventListener(type, listener, useCapture);
}
public function willTrigger(type:String):Boolean {
return dispatcher.willTrigger(type);
}
}
Tue Jun 12 2018, 03:47 PM Z