[102] DOMイベントの通知処理の実行のことを、 ディスパッチdispatchといいます。

仕様書

EventTarget インターフェイス dispatchEvent メソッド

[23] EventTarget インターフェイスの dispatchEvent メソッド >>3 は、イベントをdispatchするものです。

[24] このメソッドは、次のようにしなければなりません >>3。

  1. [25] イベントを、必須の第1引数を Event と解釈したものに設定します。
  2. [26] イベントのディスパッチフラグが設定されているか、 イベントの初期化フラグが設定されていないなら、
    1. [27] InvalidStateError 例外を投げて停止します。
  3. [28] イベントの isTrusted を、 偽に設定します。
  4. [29] イベントについてディスパッチを実行し、 その結果を返します。
    • [30] このメソッドの返す値は、 boolean です。

[4] 発火とは isTrusted 属性の扱いが違っています。

ディスパッチ

[31] ディスパッチdispatchは、 引数イベントevent、対象target、 遺物対象上書きフラグlegacy target override flagについて、 次のようにしなければなりません >>22。

  1. [58] legacyOutputDidListenersThrowFlag を、偽に設定します。
  2. [32] イベントのディスパッチフラグを設定します。
  3. [33] (イベント経路、活性化対象) を、イベント、対象、遺物対象上書きフラグについてイベント経路を構築した結果に設定します。
  4. [107] イベント経路が空なら、
    1. [108] 結果を返し、ここで停止します。
      返し値
      真
      legacyOutputDidListenersThrowFlag
      legacyOutputDidListenersThrowFlag
  5. [109] イベントの経路イベント経路を、イベント経路に設定します。
  6. [35] イベントの相を、CAPTURING_PHASE に設定します。
  7. [111] 活性化対象が null 以外で、 活性化対象の遺物活性化前動作が null 以外なら、
    1. [112] 活性化対象の遺物活性化前動作を実行します。
  8. [36] イベント経路上の各項目について、最後から順に、
    1. [45] 項目の対象と現在対象が異なるなら、
      1. [34] イベントの項目についての処理 (>>37) を legacyOutputDidListenersThrowFlag について実行します。
  9. [42] イベント経路上の各項目について、最初から順に、
    1. [39] 項目の対象と現在対象が異なるなら、
      1. [41] イベントの bubbles が真なら、
        1. [43] イベントの相を、 BUBBLING_PHASE に設定します。
        2. [40] イベントの項目についての処理 (>>37) を legacyOutputDidListenersThrowFlag について実行します。
    2. [46] それ以外なら、
      1. [69] イベントの相を、 AT_TARGET に設定します。
      2. [70] イベントの項目についての処理 (>>37) を legacyOutputDidListenersThrowFlag について実行します。
  10. [44] イベントの欄を次の通り設定します。
    ディスパッチフラグ
    偽
    伝播停止フラグ
    偽
    即時伝播停止フラグ
    偽
    現在対象
    null
    相
    NONEeventPhase
    経路イベント経路
    空
  11. [128] イベントの対象イベント対象の根が影根の場合、
    1. [129] イベントの対象イベント対象を、 null に設定します。
    2. [130] イベントの関連対象を、 null に設定します。
  12. [113] 活性化対象が null 以外なら、
    1. [114] イベントの取り消しフラグが偽なら、
      1. [115] 活性化対象の活性化動作をイベントについて実行します。
    2. [116] それ以外で、活性化対象の遺物被取消活性化動作が null 以外なら、
      1. [117] 活性化対象の遺物被取消活性化動作を実行します。
  13. [47] 結果を返します。
    返し値
    イベントの取り消しフラグの否定
    legacyOutputDidListenersThrowFlag
    legacyOutputDidListenersThrowFlag

[71] つまり、まずイベントの対象から祖先に向けた木上のオブジェクトのリストを取得してから、 その各オブジェクトについてイベントリスナーを実行します。 イベントリスナーの実行は、祖先から対象に向かう捕獲と、 対象から祖先に向かう bubbles の2段階に分かれます。 イベントリスナー内で親子関係が操作されても、 イベントの処理には影響を与えません。

イベント親、相も参照。

[37] ここで、イベントの項目についての処理とは、 legacyOutputDidListenersThrowFlag について次のようにすることをいいます (呼び出しinvoke) >>22。

  1. [73] イベントの対象イベント対象を、 項目の対象イベント経路に設定します。
  2. [38] イベントの伝播停止フラグが設定されていれば、ここで停止します。
  3. [50] イベントの現在対象を、項目の現在対象イベント経路に設定します。
  4. [98] イベントの関連対象を、項目の関連対象に設定します。
  5. [100] retargeting steps
  6. [49] リスナー群を、項目の対象イベント対象のイベントリスナー群の複製とします。
  7. [78] 発見を、 リスナー群とイベントに関して inner invoke を実行した結果に設定します。
  8. [81] 発見が偽なら、
    1. [82] 元のイベント型を、イベントのtype に設定します。
    2. [85] 元のイベント型の遺物イベント型があれば、
      1. [84] イベントの type を、 元のイベント型の遺物イベント型に設定します。
      2. [86] リスナー群とイベントと legacyOutputDidListenersThrowFlag に関して inner invoke を実行します。
      3. [83] イベントの type を、 元のイベント型に設定します。

[79] リスナー群とイベントと legacyOutputDidListenersThrowFlag に関する inner invoke は、次のようにします >>22。

  1. [77] 発見を、偽に設定します。
  2. [51] リスナー群のイベントリスナーリスナーについて順に、
    1. [54]
      • [52] リスナーの削除済みフラグが設定されておらず、かつ
      • [59] イベントの typeとリスナーの型が等しい
      ... なら、
      1. [76] 発見を、真に設定します。
      2. [60]
        • [56] イベントの eventPhase が CAPTURING_PHASE でリスナーの捕獲フラグが偽、または
        • [55] イベントの eventPhase が BUBBLING_PHASE でリスナーの捕獲フラグが真
        ... なら、
        1. [93] リスナーの一度のみフラグが設定されていれば、
          1. [95] リスナーを、 イベントの currentTarget のイベントリスナー群から削除します。
        2. [140] 大域を、 リスナーのコールバックの関連付けられたRealmの大域オブジェクトに設定します。
        3. [141] 現在イベントを、 未定義に設定します。
        4. [142] 大域が Window の場合、
          1. [143] 現在イベントを、 大域の現在イベントに設定します。
          2. [144] 組の item-in-shadow-tree が偽の場合、
            1. [145] 大域の現在イベントを、 イベントに設定します。
        5. [65] リスナーの受動的フラグが設定されていれば、
          1. [92] イベントの受動的リスナー内フラグを設定します。
        6. [57] リスナーのコールバックの handleEvent メソッドを実行します。
          引数
          (イベント)
          コールバックthis値
          イベントの currentTarget
          前項で例外が投げられたなら、 legacyOutputDidListenersThrowFlag を真に設定し、例外を報告します。
        7. [66] イベントの受動的リスナー内フラグを消去します。
        8. [146] 大域が Window の場合、
          1. [147] 大域の現在イベントを、 現在イベントに設定します。
        9. [53] イベントの即時伝播停止フラグが設定されていれば、
          1. [89] 発見を返し、ここで停止します。
  3. [80] 発見を返します。

[61] この手続きより、 addEventListener によって新たにイベントリスナーを追加しても、 そのイベントの同じ currentTarget の実行中は、 実行されません。 逆に removeEventListener によるイベントリスナーの削除は、 即時反映されます。

[62] stopPropagation も、 そのイベントの同じ currentTarget の実行中は反映されません。 stopImmediatePropagation は即時反映されます。

[125] DOM Standard では明確に記述されていませんが、 走っているスクリプトの実行中断があった場合、 そこで dispatch も中断して、中断を表す例外を dispatch の例外として再び投げることが期待されていると思われます。

[126] handle fetch や Install では、中断された場合にタスクの捨てる処理を実行することになります。

[118] ディスパッチは、発火や dispatchEvent の他、 いろいろな場所から呼び出されます。

[122] legacyOutputDidListenersThrowFlag は、 Indexed DB で使われています。イベントリスナーが例外を投げると、 トランザクションは取り消されます。

結果

[9] ディスパッチしたイベントがキャンセルされるかどうかで、その後の動作が変わることがあります。

[10] ディスパッチによってイベントリスナーが実行されたかどうかで、その後の動作が変わることがあります。

[12] prompt to unload a document は、 beforeunload のイベントリスナーが実行されたかどうかで動作が変わります。

[13] unload a document は、 unload のイベントリスナーが実行されたかどうかで動作が変わります。

関連

[5] イベント親も参照。

歴史

IE4 DOM

[19] IE事象モデルには dispatchEvent と似たものとして fireEvent がありました。

fireEvent の項を参照。

W3C DOM

[20] DOM3 まではディスパッチと発火は同義としていました。

現在の DOM Standard では区別されています。

[21] XML Events 2 ( ( 版)) http://www.w3.org/TR/xml-events2/#section-dispatchEvent-element

DOM Standard

[2] Re: [dom-events] dispatchEvent()ing a UA-dispatched event (Stewart Brodie 著, 版) http://lists.w3.org/Archives/Public/www-dom/2010AprJun/0042.html

[18] Bug 12230 – Some synthetic events cause actions ( ( 版)) https://www.w3.org/Bugs/Public/show_bug.cgi?id=12230

[6] Allow passing a target override to the dispatch algorithm. · d0f2c0b · whatwg/dom ( ( 版)) https://github.com/whatwg/dom/commit/d0f2c0bbc940061ac2a4623553de5c26409cce96

[7] Web Applications 1.0 r8271 Use DOM's hooks for defining the magic 'load' event in The End ( ( 版)) http://html5.org/tools/web-apps-tracker?from=8270&to=8271

[8] Allow passing a target override to the dispatch algorithm. · d0f2c0b · whatwg/dom ( ( 版)) https://github.com/whatwg/dom/commit/d0f2c0bbc940061ac2a4623553de5c26409cce96

[11] Check dispatch flag before initializing https://www.w3.org/Bugs/Public/s... · ccacdec · whatwg/dom ( ( 版)) https://github.com/whatwg/dom/commit/ccacdec1b3c99019677e8737c8f8550583984e67

[14] Clean up the event dispatch algorithms · whatwg/dom@d8cb495 ( 版) https://github.com/whatwg/dom/commit/d8cb49567c7018d4f9cfddf30fbc24f40693a9b0

[15] Fix the incorrect side effects of dispatch' target override · whatwg/dom@b8a8eb2 ( 版) https://github.com/whatwg/dom/commit/b8a8eb272d1ff3c654b3c5ae690c990f1d0cd700

[16] Fix #84: event listeners can be removed but not added during invocation · whatwg/dom@02710dd ( 版) https://github.com/whatwg/dom/commit/02710dd77e89586ad78b9bce0a3b6fe5f9b2ad19

メモ

[17] element.dispatchEvent - MDC Doc Center ( ( 版)) https://developer.mozilla.org/ja/DOM/element.dispatchEvent

[63] Check for "stop immediate propagation flag" earlier in invoke (no nor… · whatwg/dom@1cce4fd ( 版) https://github.com/whatwg/dom/commit/1cce4fd5e39ac48c047d9de3d5efefc0a909db14

[64] Add EventListenerOptions and passive event listener feature · whatwg/dom@253a21b ( 版) https://github.com/whatwg/dom/commit/253a21b8e78e37447c47983916a7cf39c4f6a3c5

[67] Integrate HTML's monkey patch to the event path · whatwg/dom@2d7b637 ( 版) https://github.com/whatwg/dom/commit/2d7b637b31fc6bad8f6c4743fb61016392fac382

[68] Remove event path monkey patch · whatwg/html@dad854e ( 版) https://github.com/whatwg/html/commit/dad854e4c1f5f7098a1b1ec7f33e2218796f7442

[72] Fix #169: do not invoke target while iterating eventPath · whatwg/dom@26f7947 ( 版) https://github.com/whatwg/dom/commit/26f7947dce80934f75e0b399a40c444132e2ab9b

[74] Check for "stop immediate propagation flag" earlier in invoke (no nor… · whatwg/dom@1cce4fd ( 版) https://github.com/whatwg/dom/commit/1cce4fd5e39ac48c047d9de3d5efefc0a909db14

[75] Fix #156: add legacy event type check to invoke algorithm · whatwg/dom@a026ccf ( 版) https://github.com/whatwg/dom/commit/a026ccf3efa8d34fb0cac580928f61d18b1e9f76

[87] Clarify EventTarget.dispatchEvent() · whatwg/dom@59d283a ( 版) https://github.com/whatwg/dom/commit/59d283ab9c5d2e3dd823bca21eecaaaca402b181

[88] Properly check event's stop immediate propagation flag in "inner invoke" · whatwg/dom@b7a94a2 ( 版) https://github.com/whatwg/dom/commit/b7a94a2d90b37330ae9a5e5a125ce9047f867e42

[90] Editorial: check stop propagation flag at start of invoke · whatwg/dom@a768d8e ( 版) https://github.com/whatwg/dom/commit/a768d8eef0584ea8ee831895b5c9dc8bcf363afc

[91] Enable an event listener to be invoked just once · whatwg/dom@e002d78 ( 版) https://github.com/whatwg/dom/commit/e002d7811533e276c9927b237748c4e170f4cb10

[96] Address reentrancy issue with "once" listeners (annevk著, ) https://github.com/whatwg/dom/commit/5324200d70eb23276cb58b814416e19c436104f2

[48] Shadow: define event retargeting for shadow trees (annevk著, ) https://github.com/whatwg/dom/commit/ed94c9f2f1850b2e6a9b357c6870186859da4c2d

[94] Rename scoped to composed and invert its meaning (annevk著, ) https://github.com/whatwg/dom/commit/6e1b0386644301859c697ee2e868313963d2a602

[97] Shadow: define event's relatedTarget handling (hayatoito著, ) https://github.com/whatwg/dom/commit/ef69a247681532e6102ced9a78aabf7f7a536108

[99] Shadow: add "retargeting steps" to the dispatch algorithm (hayatoito著, ) https://github.com/whatwg/dom/commit/fbc0c312c3ead6940718e3d2d7511f2b014011e1

[101] Unset stop propagation flags after dispatch (annevk著, ) https://github.com/whatwg/dom/commit/806d4aab584f6fc38c21f8e088b51b8ba3e27e20

[103] Shadow: adjust composedPath() when currentTarget is a Window object (hayatoito著, ) https://github.com/whatwg/dom/commit/2153769e1ecf55f2d202fd5c6f996023b34545e5

[104] Redesign fire an event and target override (annevk著, ) https://github.com/whatwg/dom/commit/e19d7eef74fb83792415a4a78ed866d28f4cc543

[105] Editorial: major cleanup around firing and dispatching events (annevk著, ) https://github.com/whatwg/html/commit/8ffbd146d4709057e45dd6cfc81e7a70897050c5

[106] Shadow: do not dispatch an event when target is reletedTarget (hayatoito著, ) https://github.com/whatwg/dom/commit/afac5044c18fa871837b0a86d21f338b29f7a292

[110] Define special dispatch behavior for click events (annevk著, ) https://github.com/whatwg/dom/commit/cb12fd4e2db68a9d86841a13a73611e16f9f1fb4

[119] Pass listeners to inner invoke (annevk著, ) https://github.com/whatwg/dom/commit/627eeaac169fd8fdec851f1907e20a9b155898cb

[120] Fallback to legacy type only when event is trusted (upsuper著, ) https://github.com/whatwg/dom/commit/9d8e4ed93896c50b1cacfceca6f93c56337686d8

[121] Add legacyOutputDidListenersThrowFlag to event dispatch for IDB (annevk著, ) https://github.com/whatwg/dom/commit/56a4d6ba7a96af1331363f0780c3dac12ed6bfdb

[123] Use "legacyOutputDidListenersThrowFlag" DOM hook (inexorabletash著, ) https://github.com/w3c/IndexedDB/commit/214a1357f690640615ad5b395cf96ffc2de61da3

[124] Editorial: use Infra's return and continue concepts (annevk著, ) https://github.com/whatwg/dom/commit/16944b0faef3da894c825d7a154a7bf9a60ea8a4

[127] Clear event's target and relatedTarget when dispatch ends at a shadow… (TakayoshiKochi著, ) https://github.com/whatwg/dom/commit/9ada239e14fe7964577276ef9d8972069e665247

[131] Event.target should return null after dispatch is complete, when stopped at ShadowRoot · Issue #511 · whatwg/dom () https://github.com/whatwg/dom/issues/511

[132] Set event.target to null when dispatching finishes at ShadowRoot by TakayoshiKochi · Pull Request #513 · whatwg/dom () https://github.com/whatwg/dom/pull/513

[133] Editorial: add "add an event listener" hook (annevk著, ) https://github.com/whatwg/dom/commit/2bdabb15de8112d9783cf393a3d6c37911149f77

[134] Editorial: remove object argument from inner invoke (annevk著, ) https://github.com/whatwg/dom/commit/bf6ff4574b054ec7b3a1aae40cea99c09a1eec5f

[135] Editorial: remove object argument from inner invoke (annevk著, ) https://github.com/whatwg/dom/commit/bf6ff4574b054ec7b3a1aae40cea99c09a1eec5f

[136] "inner invoke" does not need to take object · Issue #618 · whatwg/dom () https://github.com/whatwg/dom/issues/618

[137] Editorial: remove object argument from inner invoke by annevk · Pull Request #619 · whatwg/dom () https://github.com/whatwg/dom/pull/619

[138] Editorial: create a concept for event's target (annevk著, ) https://github.com/whatwg/dom/commit/07c110c87b8e4b1f7ecae09727b859bb75b17a73

[139] Standardize window.event (miketaylr著, ) https://github.com/whatwg/dom/commit/c69d7c0fb8796de884652c517825122d12901ef5

[148] Standardize srcElement, returnValue, and window.event · Issue #334 · whatwg/dom () https://github.com/whatwg/dom/issues/334

[149] Avoid setting target to the Window object (annevk著, ) https://github.com/whatwg/dom/commit/0b04ae848b27f9eaf6f0bd17ecaff0bd7f833068

[150] Dispatch event always set the event.target to the global object after dispatch · Issue #697 · whatwg/dom () https://github.com/whatwg/dom/issues/697

[151] Avoid setting target to the Window object by annevk · Pull Request #698 · whatwg/dom () https://github.com/whatwg/dom/pull/698