仕様書

意味

[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 拡張属性を指定できます >>7。 CEReactions は、 カスタム要素反応を適宜実行しなければならないことを表しています。

[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