特定の EventTarget
に Event
をディスパッチし、影響する EventListener
を適切な順序で呼び出します。通常のイベント処理ルール(capturing フェーズと任意的な bubbling フェーズを含む)は dispatchEvent()
で手動でディスパッチされたイベントにも適用されます。
構文
cancelled = !target.dispatchEvent(event)
event
は、ディスパッチされるEvent
オブジェクトです。target
はEvent.target
を初期化し、どのイベントリスナーを呼び出すかを決定するのに使われます。- このイベントを処理した少なくともひとつのイベントハンドラが
Event.preventDefault()
を呼び出した場合、戻り値はfalse
となります。そうでなければtrue
となります。
もしメソッド呼び出しの前にイベントが初期化されず、イベントのタイプが指定されなかった場合、あるいはイベントのタイプが null
または空文字列だった場合、dispatchEvent
は UNSPECIFIED_EVENT_TYPE_ERR
を投げます。イベントハンドラから投げられた例外は、キャッチされなかった例外として報告されます。イベントハンドラは入れ子のコールスタック上で実行され、実行が完了するまで呼び出し元をブロックしますが、例外は呼び出し元まで伝播しません。
注
dispatchEvent
は 作成-初期化-ディスパッチ プロセスの最後のステップであり、イベントを実装系のイベントモデルにディスパッチするのに使われます。イベントは document.createEvent メソッドを使って作成され、initEvent メソッド、またはその他の、initMouseEvent や initUIEvent といったより具体的な初期化メソッドを使って初期化されます。
Event オブジェクトのリファレンスも参照してください。
例
Creating and triggering events を参照。