upgrade

upgrade

[60] カスタム要素構築器 (コンストラクター) (custom element constructor) は、 カスタム要素が作成された時に実行される JavaScript関数です。 カスタム要素定義する際に (著者が) 指定できます。

仕様書

意味

[15] カスタム要素構築器 (custom element constructor) は、 カスタム要素構築器 (コンストラクター) です >>14カスタム要素構築器は、 (通常の要素のように利用者エージェントが定義するのではなく) 著者が定義します。

[16] カスタム要素構築器は、いくつかの条件を満たさなければならないことを除けば、 普通の JavaScript構築器と変わりありません。つまり、 単なる JavaScript関数です。

著者の要件

[4] 著者は、カスタム要素構築器について、次の条件を満たさなければなりません >>3

[13] 一般に、構築器は、初期状態や既定値の設定、 イベントリスナー影ホストの設定に使うべきです>>3

[12] 一般に、処理 (特に fetchレンダリングを伴うもの) はできるだけ構築器ではなく、 connectedCallback を使うべきですただし、 connectedCallback は何度も実行されることがありますから、本当に一度だけ実行したい初期化作業は対策が必要になります。 >>3

CustomElementConstructor

[100] Web IDLtypedef CustomElementConstructor は、 any を返す関数です HTML Standard。 つまり任意の値を返す関数を表しています。

[101] define メソッドで使われています。

構築器 (カスタム要素定義)

[18] カスタム要素定義は、構築器 (constructor) を持ちます >>17構築器は、カスタム要素構築器です >>17

[56] 構築器は、次の場面で呼び出されます。

[57] 他に、 define で重複検査やプロパティーの参照のためにアクセスされます。

格上げ

[51] カスタム要素の条件を潜在的に満たす要素を、 実際にカスタム要素とする操作を、 要素の格上げといいます。要素の格上げは、次の場面で、 適切なカスタム要素定義が存在する場合に行われます。

[55] 要素の格上げによって、元々 HTMLElement実装していた要素オブジェクトは、 カスタム要素構築器の実行を経てカスタム要素クラスオブジェクトになります。


[89] CustomElementRegistry インターフェイスupgrade メソッドは、 CEReactions であり、次のようにしなければなりません >>19

  1. [90] を、第1引数を Node として解釈した結果に設定します。
  2. [91] 候補群を、 影を含む包括的子孫要素すべての影を含む木順リストに設定します。
  3. [92] 候補群の各候補について、順に、
    1. [93] 候補要素の格上げの試行を行います。

[36] 要素の格上げの試行 (try to upgrade an element) は、 要素要素について、次のようにします >>19

  1. [39] 定義を、要素節点文書要素名前空間要素局所名要素isについてカスタム要素定義を探す処理を実行した結果に設定します。
  2. [40] 定義null でない場合、
    1. [41] 要素定義について、 enqueue a custom element upgrade reaction を実行します。

[42] これは、upgrade の他、 挿入から呼び出されます。

[20] 要素の格上げ (upgrade an element) は、 カスタム要素定義定義要素要素について、 次のようにします >>19

  1. [64] 要素カスタム要素カスタム要素状態failed なら、
    1. [65] ここで停止します。
  2. [72] 要素カスタム要素定義を、定義に設定します。
  3. [31] 要素属性リストの各属性について順に、
    1. [32] enqueue a custom element callback reaction を実行します。
      要素
      要素
      コールバック名
      attributeChangedCallback
      引数リスト
      1. 属性局所名
      2. null
      3. 属性
      4. 属性名前空間
  4. [33] 要素影を含む文書中なら、
    1. [34] enqueue a custom element callback reaction を実行します。
      要素
      要素
      コールバック名
      connectedCallback
      引数リスト
  5. [21] 要素を、定義構築スタックの末尾に追加します。
  6. [22] 構築器を、定義構築器に設定します。
  7. [23] 結果を、構築器について構築した結果に設定します。 (例外投げられることもあります。)
  8. [27] 結果例外投げられたことを表していなければ、
    1. [80] SameValue(結果, 要素)の場合、
      • [29] これは、 >>5>>7 に違反すると発生することがあります。
      1. [79] 結果を、 InvalidStateError 例外投げられたとします。
  9. [24] 定義構築スタックの末尾の項目を削除します。
  10. [25] 結果例外投げられたことを表していれば、
    1. [70] 要素カスタム要素状態を、 failed に設定します。
    2. [85] 要素カスタム要素定義を、 null に設定します。
    3. [81] 要素カスタム要素反応キューを、空にします。
    4. [26] 結果例外投げ、ここで停止します。
  11. [30] 要素カスタム要素状態を、 custom に設定します。

[35] これは、要素の作成CEReactions から呼び出されます。

[44] 格上げ反応 (upgrade reaction) は、 要素の格上げを行うもので、カスタム要素定義を持ちます。 >>45

[46] カスタム要素格上げ反応をキューに追加 (enqueue a custom element upgrade reaction) するには、 要素要素カスタム要素定義定義について、次のようにします >>43

  1. [47] 要素カスタム要素反応キューに、 定義格上げ反応を追加します。
  2. [48] 要素について適切な要素キューに要素を追加します。

[49] これは、カスタム要素定義の作成時や、要素の格上げの試行で呼び出されます。

[50] 実行についてはカスタム要素キューを参照。

歴史

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

[2] Add customElements.get() to retrieve a custom element constructor · whatwg/html@1d596a5 ( 版) <https://github.com/whatwg/html/commit/1d596a555d3c2f067ae643e447eaa88137b595ac>

[58] Make custom element definition trigger in-document upgrades ( (domenic著, )) <https://github.com/whatwg/html/commit/11bdd701e79c8dd6040586b5257eb01f3b620659>

[59] Editorial: custom element state "customized" → "custom" ( (domenic著, )) <https://github.com/whatwg/html/commit/5946d084658ff2f8d5ec3cea3c448175eaa5336e>

[61] Fix inaccurate stack-popping in custom element upgrades ( (domenic著, )) <https://github.com/whatwg/html/commit/6561250ec3788938a2d64932093b0ea293b97174>

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

[63] Don't upgrade custom elements twice (domenic著, ) <https://github.com/whatwg/html/commit/5798c66579b8076660178f484568adc67421dc23>

[66] Prevent double custom element reaction enqueuing via upgrades (domenic著, ) <https://github.com/whatwg/html/commit/657d3b2b97a0fd5ff1c353857f5b052f41bd3e0d>

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

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

[69] Fix customized built-in element "is" handling and reactions (domenic著, ) <https://github.com/whatwg/html/commit/4e632a82728d68a8a6bd32f02083762b7792ddf7>

[37] Set the stage for preventing double custom element constructor calls (domenic著, ) <https://github.com/whatwg/dom/commit/539e45214f682797f4fa022815a08b6f044e1240>

[38] Prevent double custom element constructor calls (domenic著, ) <https://github.com/whatwg/html/commit/04e90c55c7526d8c96d20159bb23586670b93fd2>

[71] Implement new custom element adoption semantics (domenic著, ) <https://github.com/whatwg/html/commit/feb77d09793a2ed8d49a6949dbca73eabb60ae79>

[73] Make document.write etc. throw during parsing custom elements (domenic著, ) <https://github.com/whatwg/html/commit/00c6fa07bdb9f0d08a28f6c6e1ababca7d08618c>

[75] Make document.write etc. throw during parsing custom elements (domenic著, ) <https://github.com/whatwg/html/commit/00c6fa07bdb9f0d08a28f6c6e1ababca7d08618c>

[76] Set the custom element state to failed when upgrades misbehave (domenic著, ) <https://github.com/whatwg/html/commit/b687759d5eccb354faca78fda5001ce3db428749>

[78] Clear the custom element reaction queue if upgrading fails (domenic著, ) <https://github.com/whatwg/html/commit/d00b810aeccf9a272b17400ed3daed7f100adec1>

[28] Use Web IDL to construct custom element constructors (domenic著, ) <https://github.com/whatwg/dom/commit/1ca094a209ba020348ac146c8bda157b7c5f3212>

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

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

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

[84] Fix ordering of custom element upgrade steps (domenic著, ) <https://github.com/whatwg/html/commit/2b8a4752415a3a831adf41a97c217963455de220>

[86] Elements that are upgrading have no CE definition when callback reactions are enqueued · Issue #2876 · whatwg/html () <https://github.com/whatwg/html/issues/2876>

[87] Fix ordering of custom element upgrade steps by domenic · Pull Request #3124 · whatwg/html () <https://github.com/whatwg/html/pull/3124>

[88] Add customElements.upgrade() (domenic著, ) <https://github.com/whatwg/html/commit/6df48639fb6d6189a346ea7349f13fd14ace4c99>

[95] Add customElements.upgrade() (domenic著, ) <https://github.com/whatwg/html/commit/6df48639fb6d6189a346ea7349f13fd14ace4c99>

[96] Add `customElements.upgrade` · Issue #710 · w3c/webcomponents () <https://github.com/w3c/webcomponents/issues/710>

[97] Add customElements.upgrade() by domenic · Pull Request #3535 · whatwg/html () <https://github.com/whatwg/html/pull/3535>

[98] Fix customElements.upgrade() to use shadow-including tree order (tkent-google著, ) <https://github.com/whatwg/html/commit/5b653a9145425b32a4f1c78ffb1a1bda7fde9a6b>

[99] custom-element: customElements.upgrade() should use "shadow-including tree order" by tkent-google · Pull Request #3626 · whatwg/html () <https://github.com/whatwg/html/pull/3626>

[102] Make the type of custom element constructor stricter by yuki3 · Pull Request #3703 · whatwg/html () <https://github.com/whatwg/html/pull/3703>