[102] [[DOMイベント]]の通知処理の実行のことを、 [DFN[[RUBYB[ディスパッチ]@en[dispatch]]]]といいます。 * 仕様書 [REFS[ - [1] [CITE@en-US[DOM Standard]] ([TIME[2013-04-26 20:00:45 +09:00]] 版) -- [3] [CITE@en-US[DOM Standard]] ([TIME[2013-04-26 20:00:45 +09:00]] 版) - [22] '''[CITE@en[DOM Standard]] ([TIME[2015-11-20 19:44:48 +09:00]] 版) ''' ]REFS] * [CODE(DOMi)@en[EventTarget]] インターフェイス [CODE(DOMm)@en[dispatchEvent]] メソッド [23] [CODE(DOMi)@en[[[EventTarget]]]] [[インターフェイス]]の [DFN[[CODE(DOMm)@en[[[dispatchEvent]]]]]] [[メソッド]] [SRC[>>3]] は、[[イベント]]を[[dispatch]]するものです。 [24] この[[メソッド]]は、次のようにしなければ[['''なりません''']] [SRC[>>3]]。 [FIG(steps)[ = [25] [VAR[イベント]]を、必須の第1[[引数]]を [CODE(DOMi)@en[[[Event]]]] と解釈したものに設定します。 = [26] [VAR[イベント]]の[F[[[ディスパッチフラグ]]]]が設定されているか、 [VAR[イベント]]の[F[[[初期化フラグ]]]]が設定されていないなら、 == [27] [CODE(DOMe)@en[[[InvalidStateError]]]] [[例外]]を[[投げ]]て停止します。 = [28] [VAR[イベント]]の [F[[CODE(DOMa)@en[[[isTrusted]]]]]] を、 [[偽]]に設定します。 = [29] [VAR[イベント]]について[[ディスパッチ]]を実行し、 その結果を返します。 =- [30] この[[メソッド]]の返す値は、 [CODE(IDL)@en[[[boolean]]]] です。 ]FIG] ;; [4] [[発火]]とは [CODE(DOMm)@en[[[isTrusted]]]] [[属性]]の扱いが違っています。 * ディスパッチ [31] [DFN[[RUBYB[ディスパッチ]@en[dispatch]]]]は、 [[引数]][VAR[[RUBYB[[[イベント]]]@en[event]]]]、[VAR[[RUBYB[[[対象]]]@en[target]]]]、 [VAR[[RUBYB[遺物[[対象上書き]]フラグ]@en[legacy target override]] flag]]について、 次のようにしなければ[['''なりません''']] [SRC[>>22]]。 [FIG(steps)[ = [58] [DFN[[VAR[legacyOutputDidListenersThrowFlag]]]] を、[[偽]]に設定します。 = [32] [VAR[イベント]]の[F[[[ディスパッチフラグ]]]]を設定します。 = [33] ([VAR[イベント経路]]、[VAR[活性化対象]]) を、[VAR[イベント]]、[VAR[対象]]、[VAR[遺物対象上書きフラグ]]について[[イベント経路]]を構築した結果に設定します。 = [107] [VAR[イベント経路]]が[[空]]なら、 == [108] 結果を返し、ここで停止します。 [FIG(list members)[ : [[返し値]] : [[真]] : [VAR[legacyOutputDidListenersThrowFlag]] : [VAR[legacyOutputDidListenersThrowFlag]] ]FIG] = [109] [VAR[イベント]]の[F[経路][イベント経路]]を、[VAR[イベント経路]]に設定します。 = [35] [VAR[イベント]]の[F[相]]を、[CODE[[[CAPTURING_PHASE]]]] に設定します。 = [111] [VAR[活性化対象]]が [CODE[null]] 以外で、 [VAR[活性化対象]]の[F[遺物活性化前動作]]が [CODE[null]] 以外なら、 == [112] [VAR[活性化対象]]の[F[遺物活性化前動作]]を実行します。 = [36] [VAR[イベント経路]]上の各[VAR[項目]]について、最後から順に、 == [45] [VAR[項目]]の[F[対象]]と[F[現在対象]]が異なるなら、 === [34] [VAR[イベント]]の[VAR[項目]]についての処理 (>>37) を [VAR[legacyOutputDidListenersThrowFlag]] について実行します。 = [42] [VAR[イベント経路]]上の各[VAR[項目]]について、最初から順に、 == [39] [VAR[項目]]の[F[対象]]と[F[現在対象]]が異なるなら、 === [41] [VAR[イベント]]の [F[[CODE(DOMa)@en[[[bubbles]]]]]] が[[真]]なら、 ==== [43] [VAR[イベント]]の[F[相]]を、 [CODE[BUBBLING_PHASE]] に設定します。 ==== [40] [VAR[イベント]]の[VAR[項目]]についての処理 (>>37) を [VAR[legacyOutputDidListenersThrowFlag]] について実行します。 == [46] それ以外なら、 === [69] [VAR[イベント]]の[F[相]]を、 [CODE[AT_TARGET]] に設定します。 === [70] [VAR[イベント]]の[VAR[項目]]についての処理 (>>37) を [VAR[legacyOutputDidListenersThrowFlag]] について実行します。 = [44] [VAR[イベント]]の欄を次の通り設定します。 [FIG(list members middle)[ : [F[ディスパッチフラグ]] : [[偽]] : [F[伝播停止フラグ]] : [[偽]] : [F[即時伝播停止フラグ]] : [[偽]] : [F[現在対象]] : [CODE[null]] : [F[相]] : [CODE[NONE][eventPhase]] : [F[経路][イベント経路]] : [[空]] ]FIG] = [128] [VAR[イベント]]の[F[対象][イベント対象]]の[F[根]]が[[影根]]の場合、 == [129] [VAR[イベント]]の[F[対象][イベント対象]]を、 [CODE[null]] に設定します。 == [130] [VAR[イベント]]の[F[関連対象]]を、 [CODE[null]] に設定します。 = [113] [VAR[活性化対象]]が [CODE[null]] 以外なら、 == [114] [VAR[イベント]]の[F[取り消しフラグ]]が[[偽]]なら、 === [115] [VAR[活性化対象]]の[F[活性化動作]]を[VAR[イベント]]について実行します。 == [116] それ以外で、[VAR[活性化対象]]の[F[遺物被取消活性化動作]]が [CODE[null]] 以外なら、 === [117] [VAR[活性化対象]]の[F[遺物被取消活性化動作]]を実行します。 = [47] 結果を返します。 [FIG(list members)[ : [[返し値]] : [VAR[イベント]]の[F[取り消しフラグ]]の[[否定]] : [VAR[legacyOutputDidListenersThrowFlag]] : [VAR[legacyOutputDidListenersThrowFlag]] ]FIG] ]FIG] [71] つまり、まず[[イベント]]の[[対象]]から[[祖先]]に向けた[[木]]上の[[オブジェクト]]のリストを取得してから、 その各[[オブジェクト]]について[[イベントリスナー]]を実行します。 [[イベントリスナー]]の実行は、[[祖先]]から[[対象]]に向かう[[捕獲]]と、 [[対象]]から[[祖先]]に向かう [[bubbles]] の2段階に分かれます。 [[イベントリスナー]]内で[[親子]]関係が操作されても、 [[イベント]]の処理には影響を与えません。 ;; [[イベント親]]、[[相]]も参照。 [37] ここで、[VAR[イベント]]の[VAR[項目]]についての処理とは、 [VAR[legacyOutputDidListenersThrowFlag]] について次のようにすることをいいます ([DFN[[RUBYB[呼び出し]@en[invoke]]]]) [SRC[>>22]]。 [FIG(steps)[ = [73] [VAR[イベント]]の[F[対象][イベント対象]]を、 [VAR[項目]]の[F[対象][イベント経路]]に設定します。 = [38] [VAR[イベント]]の[F[伝播停止フラグ]]が設定されていれば、ここで停止します。 = [50] [VAR[イベント]]の[F[現在対象]]を、[VAR[項目]]の[F[現在対象][イベント経路]]に設定します。 = [98] [VAR[イベント]]の[F[関連対象]]を、[VAR[項目]]の[F[関連対象]]に設定します。 = [100] @@ [[retargeting steps]] = [49] [VAR[リスナー群]]を、[VAR[項目]]の[F[対象][イベント対象]]の[F[イベントリスナー群]]の複製とします。 = [78] [VAR[発見]]を、 [VAR[リスナー群]]と[VAR[イベント]]に関して [[inner invoke]] を実行した結果に設定します。 = [81] [VAR[発見]]が[[偽]]なら、 == [82] [VAR[元のイベント型]]を、[VAR[イベント]]の[F[[CODE(DOMa)@en[[[type]]]]]] に設定します。 == [85] [VAR[元のイベント型]]の[[遺物イベント型]]があれば、 === [84] [VAR[イベント]]の [F[[CODE(DOMa)@en[[[type]]]]]] を、 [VAR[元のイベント型]]の[[遺物イベント型]]に設定します。 === [86] [VAR[リスナー群]]と[VAR[イベント]]と [VAR[legacyOutputDidListenersThrowFlag]] に関して [[inner invoke]] を実行します。 === [83] [VAR[イベント]]の [F[[CODE(DOMa)@en[[[type]]]]]] を、 [VAR[元のイベント型]]に設定します。 ]FIG] [79] [VAR[リスナー群]]と[VAR[イベント]]と [VAR[legacyOutputDidListenersThrowFlag]] に関する [DFN[[[inner invoke]]]] は、次のようにします [SRC[>>22]]。 [FIG(steps)[ = [77] [VAR[発見]]を、[[偽]]に設定します。 = [51] [VAR[リスナー群]]の[[イベントリスナー]][VAR[リスナー]]について順に、 == [54] [FIG(list)[ - [52] [VAR[リスナー]]の[F[[[削除済みフラグ]]]]が設定されておらず、かつ - [59] [VAR[イベント]]の [F[[CODE(DOMa)@en[[[type]]]]]]と[VAR[リスナー]]の[F[[[型]]]]が等しい ]FIG] ... なら、 === [76] [VAR[発見]]を、[[真]]に設定します。 === [60] [FIG(list)[ - [56] [VAR[イベント]]の [F[[CODE(DOMa)@en[[[eventPhase]]]]]] が [CODE[[[CAPTURING_PHASE]]]] で[VAR[リスナー]]の[F[[[捕獲]]]]フラグが[[偽]]、または - [55] [VAR[イベント]]の [F[[CODE(DOMa)@en[[[eventPhase]]]]]] が [CODE[[[BUBBLING_PHASE]]]] で[VAR[リスナー]]の[F[[[捕獲]]]]フラグが[[真]] ]FIG] ... なら、 ==== [93] [VAR[リスナー]]の[F[一度のみ]]フラグが設定されていれば、 ===== [95] [VAR[リスナー]]を、 [VAR[イベント]]の [F[[CODE(DOMa)@en[currentTarget]]]] の[F[イベントリスナー群]]から削除します。 ==== [140] [VAR[大域]]を、 [VAR[リスナー]]の[F[コールバック]]の[F[関連付けられたRealm]]の[F[大域オブジェクト]]に設定します。 ==== [141] [VAR[現在イベント]]を、 [[未定義]]に設定します。 ==== [142] [VAR[大域]]が [CODE[Window]] の場合、 ===== [143] [VAR[現在イベント]]を、 [VAR[大域]]の[F[現在イベント]]に設定します。 ===== [144] [VAR[組]]の [F[item-in-shadow-tree]] が[[偽]]の場合、 ====== [145] [VAR[大域]]の[F[現在イベント]]を、 [VAR[イベント]]に設定します。 ==== [65] [VAR[リスナー]]の[F[[[受動的]]]]フラグが設定されていれば、 ===== [92] [VAR[イベント]]の[F[[[受動的リスナー内フラグ]]]]を設定します。 ==== [57] [VAR[リスナー]]の[F[[[コールバック]]]]の [F[[CODE(DOMm)@en[[[handleEvent]]]] [[メソッド]]]]を実行します。 [FIG(list members)[ : [[引数]] : ([VAR[イベント]]) : [[コールバック[CODE(JS)[this]]値]] : [VAR[イベント]]の [F[[CODE(DOMa)@en[[[currentTarget]]]]]] ]FIG] 前項で[[例外]]が[[投げ]]られたなら、 [VAR[legacyOutputDidListenersThrowFlag]] を[[真]]に設定し、[[例外を報告]]します。 ==== [66] [VAR[イベント]]の[F[受動的リスナー内フラグ]]を消去します。 ==== [146] [VAR[大域]]が [CODE[Window]] の場合、 ===== [147] [VAR[大域]]の[F[現在イベント]]を、 [VAR[現在イベント]]に設定します。 ==== [53] [VAR[イベント]]の[F[即時伝播停止フラグ]]が設定されていれば、 ===== [89] [VAR[発見]]を返し、ここで停止します。 = [80] [VAR[発見]]を返します。 ]FIG] [61] この手続きより、 [CODE(DOMm)@en[[[addEventListener]]]] によって新たに[[イベントリスナー]]を追加しても、 その[[イベント]]の同じ [CODE(DOMa)@en[[[currentTarget]]]] の実行中は、 実行されません。 逆に [CODE(DOMm)@en[[[removeEventListener]]]] による[[イベントリスナー]]の削除は、 即時反映されます。 [62] [CODE(DOMm)@en[[[stopPropagation]]]] も、 その[[イベント]]の同じ [CODE(DOMa)@en[[[currentTarget]]]] の実行中は反映されません。 [CODE(DOMm)@en[[[stopImmediatePropagation]]]] は即時反映されます。 [125] [CITE[DOM Standard]] では明確に記述されていませんが、 [[走っているスクリプトの実行中断]]があった場合、 そこで [[dispatch]] も中断して、中断を表す[[例外]]を [[dispatch]] の[[例外]]として[[再び投げ]]ることが期待されていると思われます。 ;; [126] [[handle fetch]] や [[Install]] では、中断された場合に[[タスク]]の[VAR[捨てる処理]]を実行することになります。 -*-*- [118] [[ディスパッチ]]は、[[発火]]や [CODE(DOMm)@en[dispatchEvent]] の他、 いろいろな場所から呼び出されます。 [122] [VAR[legacyOutputDidListenersThrowFlag]] は、 [[Indexed DB]] で使われています。[[イベントリスナー]]が[[例外]]を[[投げ]]ると、 [[トランザクション]]は取り消されます。 * 結果 [9] [[ディスパッチ]]した[[イベント]]が[[キャンセル]]されるかどうかで、その後の動作が変わることがあります。 [10] [[ディスパッチ]]によって[[イベントリスナー]]が実行されたかどうかで、その後の動作が変わることがあります。 [EG[ [12] [[prompt to unload a document]] は、 [CODE(DOMe)@en[[[beforeunload]]]] の[[イベントリスナー]]が実行されたかどうかで動作が変わります。 ]EG] [EG[ [13] [[unload a document]] は、 [CODE(DOMe)@en[[[unload]]]] の[[イベントリスナー]]が実行されたかどうかで動作が変わります。 ]EG] * 関連 [5] [[イベント親]]も参照。 * 歴史 ** IE4 DOM [19] [[IE事象モデル]]には [CODE(DOMm)@en[[[dispatchEvent]]]] と似たものとして [CODE(DOMm)@en[[[fireEvent]]]] がありました。 ;; [CODE(DOMm)@en[[[fireEvent]]]] の項を参照。 ** W3C DOM [20] [[DOM3]] までは[[ディスパッチ]]と[[発火]]は同義としていました。 ;; 現在の [[DOM Standard]] では区別されています。 [21] [CITE[XML Events 2]] ( ([TIME[2010-12-18 05:25:20 +09:00]] 版)) ** DOM Standard [2] [CITE@en[Re: '''['''dom-events''']''' dispatchEvent()ing a UA-dispatched event]] ([[Stewart Brodie]] 著, [TIME[2010-05-06 18:18:38 +09:00]] 版) [18] [CITE@en[Bug 12230 – Some synthetic events cause actions]] ( ([TIME[2014-05-24 06:34:51 +09:00]] 版)) [6] [CITE[Allow passing a target override to the dispatch algorithm. · d0f2c0b · whatwg/dom]] ( ([TIME[2013-11-13 11:39:36 +09:00]] 版)) [7] [CITE@en[Web Applications 1.0 r8271 Use DOM's hooks for defining the magic 'load' event in The End]] ( ([TIME[2013-11-13 06:44:00 +09:00]] 版)) [8] [CITE[Allow passing a target override to the dispatch algorithm. · d0f2c0b · whatwg/dom]] ( ([TIME[2013-12-27 06:48:21 +09:00]] 版)) [11] [CITE@en[Check dispatch flag before initializing https://www.w3.org/Bugs/Public/s... · ccacdec · whatwg/dom]] ( ([TIME[2014-10-22 02:06:34 +09:00]] 版)) [14] [CITE@en[Clean up the event dispatch algorithms · whatwg/dom@d8cb495]] ([TIME[2015-11-23 17:49:13 +09:00]] 版) [15] [CITE@en[Fix the incorrect side effects of dispatch' target override · whatwg/dom@b8a8eb2]] ([TIME[2015-11-23 17:49:21 +09:00]] 版) [16] [CITE@en[Fix #84: event listeners can be removed but not added during invocation · whatwg/dom@02710dd]] ([TIME[2015-11-23 17:49:26 +09:00]] 版) * メモ [17] [CITE@en-us[element.dispatchEvent - MDC Doc Center]] ( ([TIME[2010-12-30 21:50:11 +09:00]] 版)) [63] [CITE@en[Check for "stop immediate propagation flag" earlier in invoke (no nor… · whatwg/dom@1cce4fd]] ([TIME[2016-02-15 00:21:28 +09:00]] 版) [64] [CITE@en[Add EventListenerOptions and passive event listener feature · whatwg/dom@253a21b]] ([TIME[2016-02-15 00:21:40 +09:00]] 版) [67] [CITE@en[Integrate HTML's monkey patch to the event path · whatwg/dom@2d7b637]] ([TIME[2016-02-19 18:38:19 +09:00]] 版) [68] [CITE@en[Remove event path monkey patch · whatwg/html@dad854e]] ([TIME[2016-02-19 18:38:25 +09:00]] 版) [72] [CITE@en[Fix #169: do not invoke target while iterating eventPath · whatwg/dom@26f7947]] ([TIME[2016-02-21 12:09:22 +09:00]] 版) [74] [CITE@en[Check for "stop immediate propagation flag" earlier in invoke (no nor… · whatwg/dom@1cce4fd]] ([TIME[2016-02-12 14:47:29 +09:00]] 版) [75] [CITE@en[Fix #156: add legacy event type check to invoke algorithm · whatwg/dom@a026ccf]] ([TIME[2016-02-21 15:49:41 +09:00]] 版) [87] [CITE@en[Clarify EventTarget.dispatchEvent() · whatwg/dom@59d283a]] ([TIME[2016-02-27 11:44:45 +09:00]] 版) [88] [CITE@en[Properly check event's stop immediate propagation flag in "inner invoke" · whatwg/dom@b7a94a2]] ([TIME[2016-03-02 16:27:36 +09:00]] 版) [90] [CITE@en[Editorial: check stop propagation flag at start of invoke · whatwg/dom@a768d8e]] ([TIME[2016-04-22 18:28:03 +09:00]] 版) [91] [CITE@en[Enable an event listener to be invoked just once · whatwg/dom@e002d78]] ([TIME[2016-04-25 18:36:19 +09:00]] 版) [96] [CITE@en[Address reentrancy issue with "once" listeners]] ([[annevk]]著, [TIME[2016-06-08 01:51:48 +09:00]]) [48] [CITE@en[Shadow: define event retargeting for shadow trees]] ([[annevk]]著, [TIME[2016-04-29 21:04:07 +09:00]]) [94] [CITE@en[Rename scoped to composed and invert its meaning]] ([[annevk]]著, [TIME[2016-05-10 16:14:09 +09:00]]) [97] [CITE@en[Shadow: define event's relatedTarget handling]] ([[hayatoito]]著, [TIME[2016-07-22 16:39:19 +09:00]]) [99] [CITE@en[Shadow: add "retargeting steps" to the dispatch algorithm]] ([[hayatoito]]著, [TIME[2016-08-04 18:36:08 +09:00]]) [101] [CITE@en[Unset stop propagation flags after dispatch]] ([[annevk]]著, [TIME[2016-08-15 19:31:21 +09:00]]) [103] [CITE@en[Shadow: adjust composedPath() when currentTarget is a Window object]] ([[hayatoito]]著, [TIME[2016-09-14 13:43:55 +09:00]]) [104] [CITE@en[Redesign fire an event and target override]] ([[annevk]]著, [TIME[2016-10-15 00:32:41 +09:00]]) [105] [CITE@en[Editorial: major cleanup around firing and dispatching events]] ([[annevk]]著, [TIME[2016-10-19 01:00:43 +09:00]]) [106] [CITE@en[Shadow: do not dispatch an event when target is reletedTarget]] ([[hayatoito]]著, [TIME[2016-10-18 15:15:38 +09:00]]) [110] [CITE@en[Define special dispatch behavior for click events]] ([[annevk]]著, [TIME[2016-10-18 01:55:28 +09:00]]) [119] [CITE@en[Pass listeners to inner invoke]] ([[annevk]]著, [TIME[2017-01-04 03:33:59 +09:00]]) [120] [CITE@en[Fallback to legacy type only when event is trusted]] ([[upsuper]]著, [TIME[2017-02-08 17:29:16 +09:00]]) [121] [CITE@en[Add legacyOutputDidListenersThrowFlag to event dispatch for IDB]] ([[annevk]]著, [TIME[2017-02-14 19:08:45 +09:00]]) [123] [CITE@en[Use "legacyOutputDidListenersThrowFlag" DOM hook]] ([[inexorabletash]]著, [TIME[2017-03-08 02:13:40 +09:00]]) [124] [CITE@en[Editorial: use Infra's return and continue concepts]] ([[annevk]]著, [TIME[2017-03-18 00:56:48 +09:00]]) [127] [CITE@en[Clear event's target and relatedTarget when dispatch ends at a shadow…]] ([[TakayoshiKochi]]著, [TIME[2017-10-05 17:18:37 +09:00]]) [131] [CITE@en[Event.target should return null after dispatch is complete, when stopped at ShadowRoot · Issue #511 · whatwg/dom]] ([TIME[2017-10-10 22:27:23 +09:00]]) [132] [CITE@en[Set event.target to null when dispatching finishes at ShadowRoot by TakayoshiKochi · Pull Request #513 · whatwg/dom]] ([TIME[2017-10-10 22:30:40 +09:00]]) [133] [CITE@en[Editorial: add "add an event listener" hook]] ([[annevk]]著, [TIME[2018-03-14 17:40:36 +09:00]]) [134] [CITE@en[Editorial: remove object argument from inner invoke]] ([[annevk]]著, [TIME[2018-03-27 21:06:56 +09:00]]) [135] [CITE@en[Editorial: remove object argument from inner invoke]] ([[annevk]]著, [TIME[2018-03-27 21:06:56 +09:00]]) [136] [CITE@en["inner invoke" does not need to take object · Issue #618 · whatwg/dom]] ([TIME[2018-03-29 14:44:55 +09:00]]) [137] [CITE@en[Editorial: remove object argument from inner invoke by annevk · Pull Request #619 · whatwg/dom]] ([TIME[2018-03-29 14:45:09 +09:00]]) [138] [CITE@en[Editorial: create a concept for event's target]] ([[annevk]]著, [TIME[2018-03-30 13:24:45 +09:00]]) [139] [CITE@en[Standardize window.event]] ([[miketaylr]]著, [TIME[2018-06-07 17:15:23 +09:00]]) [148] [CITE@en[Standardize srcElement, returnValue, and window.event · Issue #334 · whatwg/dom]] ([TIME[2018-06-11 23:38:42 +09:00]]) [149] [CITE@en[Avoid setting target to the Window object]] ([[annevk]]著, [TIME[2018-09-17 18:30:53 +09:00]]) [150] [CITE@en[Dispatch event always set the event.target to the global object after dispatch · Issue #697 · whatwg/dom]] ([TIME[2018-10-22 01:13:37 +09:00]]) [151] [CITE@en[Avoid setting target to the Window object by annevk · Pull Request #698 · whatwg/dom]] ([TIME[2018-10-22 01:13:57 +09:00]])