適切な要素キューに要素を追加

カスタム要素反応 (DOM)

仕様書

意味

[8] カスタム要素反応 (custom element reaction) >>7 は、 カスタム要素に関する変化を通知するコールバック関数です。 次のものがあります。

カスタム要素構築器
要素の格上げで実行されます。
connectedCallback
要素接続された際に実行されます。
disconnectedCallback
要素切断された際に実行されます。
adoptedCallback
要素養子化 (他の文書に移動) された際に実行されます。
attributeChangedCallback
要素内容属性変更操作が発生した際に実行されます。

[9] カスタム要素構築器は、カスタム要素定義を作成する際に、 必ず指定します (define メソッドの第2引数)。 それ以外は、カスタム要素構築器prototype オブジェクトプロパティーとして、必要に応じて指定できます。

[12] カスタム要素構築器は、その時点ではまだカスタムでない要素について実行されます。 それ以外のコールバックは、カスタム要素について実行されます。

[10] カスタム要素反応は、該当する DOM 操作が発生した時に実行されます。 複数の変更が発生する場合であっても、一連の変更がすべて適用された後、 呼び出し元に戻る直前にまとめて実行されます。 著者視点では DOM 操作中に同期的に呼び出されていますが、 利用者エージェント視点では DOM 操作直後に非同期的に呼び出しているので、 著者DOM 操作の途中段階にアクセスすることはできませんし、 利用者エージェントDOM 操作中の不安定な状態を著者に晒さずに済みます。

[11] あるカスタム要素について、ある操作群に対するカスタム要素反応群は、 必ず同じ順序で実行されることが保証されます。 複数のカスタム要素全体については (カスタム要素反応内で他の要素を変更する場合があるので) 保証されません。 >>7

[99] カスタム要素反応器節点木操作すると予期せぬ結果となることがあるため、 これを避けるべきです。 >>7

[100] 例えば connectedCallback が呼ばれている要素が既に他のカスタム要素反応器によって切断されているかもしれません。

キュー

[70] 実行するべきカスタム要素反応は、 Webブラウザーによって要素ごとに管理されます。 要素ごとのキューを使うので、要素ごとの実行順序は保証されますが、 異なる要素でどの順序で実行されるかは保証されません。

[16] 要素は、カスタム要素反応キュー (custom element reaction queue) を持ちます。 これは、格上げ反応またはコールバック反応キューで、 初期状態はです。 >>7

[17] キューへの追加は、格上げ反応コールバック反応の項を参照。
[77] push/pop の他に、要素の格上げで空にされることがあります。

[71] 更に、どの要素に実行するべきカスタム要素反応が存在するかが、 要素キューによって管理されます。

[14] 要素キュー (element queue) は、 要素キューで、初期状態はです。 >>7

[13] 関連する類似起源閲覧文脈群の単位は、 カスタム要素反応群スタック (custom element reactions stack) を持ちます >>7

カスタム要素反応群スタック
スタック
要素キュースタック。初期状態は>>7
現在要素キュー (current element queue)
スタックの最上にある要素キュー >>7
バックアップ要素キュー (backup element queue)
要素キュー。初期状態はです。 >>7
バックアップ要素キュー処理中 (processing the backup element queue) フラグ
初期状態は未設定。 >>7

[72] 構文解析器DOM API 内部では、カスタム要素反応群スタックの本体スタック要素キューが使われます。 カスタム要素反応は同期的に呼び出され、そこから更に再帰的にカスタム要素反応が呼び出される可能性があるため、 要素キュースタックに積まれていくことになっています。

[73] contenteditable により利用者の操作で DOM 操作が行われた場合には、バックアップ要素キューが使われます >>7カスタム要素反応マイクロタスクで呼び出されます。

[15] 要素について適切な要素キューに要素を追加 (enqueue an element on the appropriate element queue) するには、 次のようにします >>7

  1. [58] 関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックなら、
    1. [59] 要素を、関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックバックアップ要素キューに追加します。
    2. [60] 関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックバックアップ要素キュー処理中フラグが設定されていなければ、
      1. [61] 関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックバックアップ要素キュー処理中フラグを設定します。
      2. [62] >>65マイクロタスクマイクロタスクをキューに追加します。
  2. [63] それ以外なら、
    1. [64] 要素を、関連する類似起源閲覧文脈群の単位カスタム要素反応群スタック現在要素キューに追加します。

[68] この処理は、格上げ反応コールバック反応の処理から呼び出されます。

[65] バックアップ要素キューに関するマイクロタスクは、次のようにします >>7

  1. [66] 関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックバックアップ要素キューカスタム要素反応群の呼び出しをします。
  2. [67] 関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックバックアップ要素キュー処理中フラグを未設定にします。

[18] 要素キューキューカスタム要素反応群の呼び出し (invoke custom element reactions) は、 次のようにします >>7

  1. [19] キューの各要素について、
    1. [20] 反応群を、要素カスタム要素反応キューに設定します。
    2. [21] 反応群が空でない限り、繰り返し、
      1. [22] 反応反応群の最初の項目とし、これを反応群から削除します。
      2. [23] 反応群の種別により、
        格上げ反応
        要素反応カスタム要素定義について、要素の格上げを実行します。 例外投げられたら、例外を報告します。
        コールバック反応
        反応コールバック関数呼び出します。 反応群の引数リストを引き渡します。 コールバックthis値は、要素とします。 例外投げられたら、例外を報告します。

[24] これは、通常の DOM 操作に関しては CEReactions から、構文解析器に関しては字句の要素の作成外来要素の挿入から呼び出されます。

拡張属性 CEReactions

[25] Web IDL のいくつかのメンバーには、 CEReactions 拡張属性を指定できます >>7CEReactions は、 カスタム要素反応を適宜実行しなければならないことを表しています。

[26] この拡張属性は、操作IDL属性設定器削除器以外に指定してはなりません読み取り専用属性に指定してはなりません>>7

[27] この拡張属性は、引数を指定してはなりません >>7

[28] この拡張属性が指定されている場合は、 当該メンバーの処理は、次のようにしなければなりません >>7

  1. [30] 関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックに、 要素キューpush します。
  2. [90] 結果を、当該メンバーの処理を実行した結果に設定します。
  3. [31] キューを、関連する類似起源閲覧文脈群の単位カスタム要素反応群スタックから pop した結果に設定します。
  4. [32] キューについてカスタム要素反応群の呼び出しを実行します。
  5. [29] 結果を返します。 (結果は「例外投げられた」の場合もあります。)

[33] つまり、当該メンバーの処理中に DOM 操作が発生し、 カスタム要素反応を実行しなければならないことになったら、 当該メンバーの処理の最後にまとめて順に実行されます。

[34] この拡張属性は、 DOM に変更を加えるあらゆる Web IDLメンバーに付与されています。

[52] vendor prefix 付きの内容属性反映するIDL属性は、 CEReactions 付きでなければなりません >>53

[69] その他 Webブラウザー独自 (非標準) の DOM 操作を伴うIDL属性メソッドも、 CEReactions 付きでなければなりません >>7

挿入手順群

[35] カスタム要素文書に接続された際は、その旨を通知するためスクリプトが実行される可能性があります。 (仕様書上は挿入手順群ではなく、挿入手順群の直後の別の処理として定義されています。)

[36] 挿入は、子孫について次のようにすることになっています >>44

  1. [37] 子孫影を含む文書中なら、
    1. [38] 子孫カスタムなら、
      1. [39] カスタム要素コールバック反応をキューに追加します。
        要素
        子孫
        コールバック名
        connectedCallback
        引数リスト
    2. [50] それ以外なら、
      1. [51] 子孫について要素の格上げの試行をします。

削除手順群

[41] disconnectedCallback の呼び出しは、仕様書上は削除手順群ではなく、 削除手順群の直後の別の処理として定義されています。

[42] 節点について、次のようにします >>40

  1. [43] 節点カスタムなら、
    1. [45] カスタム要素コールバック反応をキューに追加します。
      要素
      節点
      コールバック名
      disconnectedCallback
      引数リスト

属性変更手順群

[47] 仕様書上は、属性変更手順群ではなく、その直前に実行される別の処理として規定されています。 要素局所名古い値名前空間について、 次のようにします >>46

  1. [48] 要素カスタムなら、
    1. [49] カスタム要素コールバック反応をキューに追加します。
      要素
      要素
      コールバック名
      attributeChangedCallback
      引数リスト
      • 局所名
      • 古い値
      • 名前空間

養子化手順群

[75] 養子化手順群参照。

歴史

[1] Add custom elements to HTML · whatwg/html@6e7eaa4 ( 版) https://github.com/whatwg/html/commit/6e7eaa4bd2912965fd83766f99f984f249531f3a

[2] Formalize custom element reactions · whatwg/html@27aa7bc ( 版) https://github.com/whatwg/html/commit/27aa7bc4fa6f168654a8c858f0773e611f679b39

[3] Add [CEReactions] annotations to mutating methods · whatwg/dom@3cd02d1 ( 版) https://github.com/whatwg/dom/commit/3cd02d139c159a31fbb400e03932652c72fc7812

[4] Integrate callback invocation with IDL · Issue #186 · w3c/webcomponents ( 版) https://github.com/w3c/webcomponents/issues/186

[5] DOM XSLTProcessor - WHATWG Wiki ( 版) https://wiki.whatwg.org/wiki/DOM_XSLTProcessor

[6] Add [CEReactions] annotation to as · w3c/preload@b632000 ( 版) https://github.com/w3c/preload/commit/b632000d8bd32118d3b7833b7c0caca044329072

[54] Remove some redundant [CEReactions] for tables ( (domenic著, )) https://github.com/whatwg/html/commit/c2dfb033b144775e37975c6740a2f5d7842e1b16

[55] Export the definitions of [CEReactions] and [HTMLConstructor] ( (domenic著, )) https://github.com/whatwg/html/commit/6e040bfecceb8aed7949abda383656e0bbf449e0

[56] Enqueue custom element reactions appropriately during upgrades (domenic著, ) https://github.com/whatwg/html/commit/2328ccf97b80cba7835df3dc5d1a687d51fbfcf4

[57] Take care of missing custom element reactions (domenic著, ) https://github.com/whatwg/html/commit/a57c88711c995356e44d019f5bd81d0cdedac2bf

[74] Convert custom element callbacks to Web IDL callback types (domenic著, ) https://github.com/whatwg/html/commit/be055730a11a8f952feb8fdb73e7caa01460e5a4

[76] Process custom element connectedCallback immediately during parsing (domenic著, ) https://github.com/whatwg/html/commit/ca818ee1c8458c3b862acd00d11779294cb89eea

[78] Remove old-fashioned vendor-specific extension advice (annevk著, ) https://github.com/whatwg/html/commit/76f88a4015d55273749c34238d250b7bdb1aff62

[79] Correct some [CEReactions] usage (annevk著, ) https://github.com/whatwg/html/commit/404f98bb543a244e5aeffe266d581f317e295598

[80] Fix which built-in elements can be customized (domenic著, ) https://github.com/whatwg/html/commit/7d6b279b0d2bc30752700155a043b65441fe12e3

[81] Tweak [CEReactions] definition and usage (domenic著, ) https://github.com/whatwg/html/commit/c422734d44ae9897c1700daf08bd415e0dc5f9e1

[82] Remove [CEReactions] on [PutForwards] readonly attribute (johndai1984著, ) https://github.com/whatwg/dom/commit/5f1a6065921790e35b81871928f6d861bc6d8d29

[83] Clarify the behavour if the custom element reaction throws any exception · Issue #2842 · whatwg/html () https://github.com/whatwg/html/issues/2842

[84] Add [CEReactions] to createElement() (annevk著, ) https://github.com/whatwg/dom/commit/fb6638fa3d02985e43782d8857edaa915d499261

[85] Add [CEReactions] to createElement() by annevk · Pull Request #506 · whatwg/dom () https://github.com/whatwg/dom/pull/506

[86] Clarify custom element reaction arguments passed (domenic著, ) https://github.com/whatwg/html/commit/c5019ae75d7dfaaf7829cf45c56700e97b24ea61

[87] Custom Elements Methods Clarification · Issue #2299 · whatwg/html () https://github.com/whatwg/html/issues/2299

[88] Clarify custom element reaction arguments passed by domenic · Pull Request #3125 · whatwg/html () https://github.com/whatwg/html/pull/3125

[89] Make [CEReactions]'s treatment of exceptions explicit (domenic著, ) https://github.com/whatwg/html/commit/8b055c0497070731c526e8c0bb655af65fb4e10e

[91] How does CEReactions interact with thrown exceptions? · Issue #3217 · whatwg/html () https://github.com/whatwg/html/issues/3217

[92] Make [CEReactions]'s treatment of exceptions explicit by domenic · Pull Request #3235 · whatwg/html () https://github.com/whatwg/html/pull/3235

[93] Hide `nonce` content attribute values. (#2369) by mikewest · Pull Request #2373 · whatwg/html () https://github.com/whatwg/html/pull/2373

[94] Fix and clarify some [CEReactions] annotations (domenic著, ) https://github.com/whatwg/html/commit/023c11216ca2ee1c653df09a594b98fca1323975

[95] nonce IDL attribute should have the semantics of CEReactions · Issue #3887 · whatwg/html () https://github.com/whatwg/html/issues/3887

[96] textarea's value IDL attribute doesn't need CEReactions · Issue #3889 · whatwg/html () https://github.com/whatwg/html/issues/3889

[97] Fix and clarify some [CEReactions] annotations by domenic · Pull Request #3901 · whatwg/html () https://github.com/whatwg/html/pull/3901

[98] Custom element reactions ought not to modify the node tree (annevk著, ) https://github.com/whatwg/html/commit/cc6c51d5f7461880ea93736256137c6bb565270c

[101] Always enqueue an element regardless of callback by annevk · Pull Request #4127 · whatwg/html () https://github.com/whatwg/html/pull/4127

[102] Presence of disconnectedCallback can expedite an invocation of connectedCallback · Issue #760 · w3c/webcomponents () https://github.com/w3c/webcomponents/issues/760

[103] Add a nonintuitive disconnectedCallback example by annevk · Pull Request #4237 · whatwg/html () https://github.com/whatwg/html/pull/4237