(js)dispatchEvent()

EventTarget.dispatchEvent()

於此 EventTarget 物件上觸發特定的 Event 物件實體，相當於依照註冊的順序呼叫它的 EventListener。一般事件處理規則（包含 capturing 和可選的 bubbling 階段）適用於用 dispatchEvent() 手動觸發事件。

語法

cancelled = !target.dispatchEvent(event)

參數

• event 是要被觸發的事件（ Event object ）。
• target is used to initialize the Event.target and determine which event listeners to invoke.

回傳值

• 會在事件完成傳遞（捕捉、命中、冒泡三階段）之後才回傳其值。
• 若事件在傳遞過程當中，曾於一個或一個以上的事件監聽器裡被執行了該事件的 Event.preventDefault() 方法（且事件須確實已被取消了預設行為），即回傳 false。否則回傳 true 值。

若遇到以下 3 種情況，dispatchEvent 會給錯誤資訊－－  UNSPECIFIED_EVENT_TYPE_ERR ：

1. 執行 dispatchEvent 前並未藉由初始化事件指定事件類型
2. 事件類型為 null 。
3. 事件類型是個空白字串。

這些異常，處理器會報告「異常未捕獲（uncaught exceptions）」；

事件處理器（event handlers）會在一群呼叫堆（nested callstack）上執行：事件的呼叫方（caller）會先由處理器會阻擋暫停執行，直到事件完成才繼續執行，但是要注意的是，事件若發生異常並不會傳回給呼叫方。

注意

dispatchEvent 是「建立→初始化→觸發」的最後一步驟。這些步驟是用來觸發事件，讓事件完成。事件有多種建立方式，例如用 ​document.createEvent 並用 initEvent 或其他特殊 methods ，像是 initMouseEvent 或 initUIEvent 來初始化。

詳請可參考《Event》。

範例

請參閱《建立或觸發事件》。