EventTarget: dispatchEvent() メソッド

dispatchEvent()EventTarget のメソッドで、 Event をそのオブジェクトへ送り、関連するイベントリスナーを(同期的に)適切に起動させます。通常のイベント処理ルール(キャプチャとオプションのバブリングフェーズを含む)は dispatchEvent() で手動で配信されたイベントにも適用されます。

dispatchEvent() の呼び出しは、イベントを発行させるための最後のステップです。イベントは既に Event() コンストラクターを使って作成され、初期化されているはずです。

メモ: このメソッドを呼び出すとき、 Event.target プロパティは現在の EventTarget に初期化されます。

「ネイティブ」イベントがブラウザーによって発生し、イベントループを介して非同期にイベントハンドラーを呼び出すのとは異なり、 dispatchEvent() はイベントハンドラーを同期的に呼び出します。適用可能なすべてのイベントハンドラが呼び出され、 dispatchEvent() から戻る前に返されます。

構文

js
dispatchEvent(event)

引数

event

配信する Event オブジェクトです。この Event.target プロパティは現在の EventTarget に設定されます。

返値

event がキャンセル可能で、かつ event を受け取ったイベントハンドラーの少なくとも 1 つが Event.preventDefault() を呼び出した場合は false となります。それ以外の場合は true です。

例外

InvalidStateError DomException

イベントの初期化時に、イベントの種類が指定されなかった場合に発生します。

警告: イベントハンドラーで発生した例外は、捕捉されない例外として報告されます。イベントハンドラーはネストされたコールスタック上で実行されます。イベントハンドラーが完了するまで呼び出し元はブロックされますが、例外は呼び出し元まで伝搬しません。

イベントの作成と起動 を参照してください。

仕様書

Specification
DOM Standard
# ref-for-dom-eventtarget-dispatchevent③

ブラウザーの互換性

BCD tables only load in the browser

関連情報