仕様書

意味

[3] CustomElementsRegistry インターフェイスの define メソッドは、 要素定義element definition、すなわち CustomElementsRegistry オブジェクトへのカスタム要素定義の追加を行います >>2。

引数

[52] 本メソッドは、次の引数を受け取ります。

名前
作成するカスタム要素定義の名前定義名となる妥当なカスタム要素名。 extends を指定する場合 (カスタム化組み込み要素) は isis="" 属性値、 指定しない場合 (自律カスタム要素) は要素名に相当します。 この引数は必須で、既存の他のカスタム要素定義の名前定義名と違っていなければなりません。
構築器
作成するカスタム要素定義の構築器カスタム要素構築器となる関数。 この引数は必須で、既存の他のカスタム要素定義の構築器カスタム要素構築器と違っていなければなりません。 カスタム要素構築器の条件を満たすものである必要があります。
オプション群
辞書 ElementDefinitionOptions。 省略可能です。

[53] 辞書 ElementDefinitionOptions >>2 は、 次のメンバーを持ちます。

[54] 辞書 ElementDefinitionOptions のメンバー extends は、 DOMString で、 必須です >>3。 extends は、カスタム化組み込み要素における、 拡張する元の要素の名前要素名を指定するものです。 指定する要素名は、正規の HTML要素の名前要素名でなければなりません。

[56] createElement では要素名をまず指定して isis="" メンバーにカスタム要素定義の名前定義名を指定しますが、 define では逆に名前定義名をまず指定して、 extends メンバーに要素名を指定します。
class MyElement extends HTMLElement {
};
customElements.define ("my-element", MyElement);

処理

[55] 本メソッドは、カスタム要素定義を作成し、 Window に保存するものです。更に、 既に作成された要素があれば、作成した定義に添って要素の格上げも実行します。

これ以後に新たに要素の作成が行われる場合は、その時点で要素の格上げが行われます。

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

  1. [5] 次の引数が指定されたものとして処理します。
    名前
    第1引数 DOMString (必須)
    構築器
    第2引数 CustomElementConstructor (必須)
    オプション群
    第3引数 ElementDefinitionOptions (省略可能)
  2. [6] CEReactions の事前処理を行います。
  3. [8] 構築器に IsConstructor を適用した結果が偽の場合、
    1. [9] TypeError を投げます。
    2. [60] CEReactions の事後処理を行います。
    3. [59] ここで停止します。
  4. [10] 名前が妥当なカスタム要素名でなければ、
    1. [11] SyntaxError DOMException を投げます。
    2. [61] CEReactions の事後処理を行います。
    3. [62] ここで停止します。
  5. [12]
    • [73] 文脈オブジェクトに名前定義名が名前の項目がある
    • [14] 文脈オブジェクトに構築器カスタム要素構築器が構築器の項目がある
    ... のいずれかを満たす場合、
    1. [15] NotSupportedError を投げます。
    2. [65] CEReactions の事後処理を行います。
    3. [66] ここで停止します。
  6. [17] extends を、オプション群の extends に設定します。
  7. [18] extends が null なら、
    1. [16] 局所名を、名前に設定します。
  8. [24] それ以外なら、
    1. [19] extends が妥当なカスタム要素名なら、
      1. [20] NotSupportedError を投げます。
      2. [67] CEReactions の事後処理を行います。
      3. [68] ここで停止します。
    2. [21] extends と HTML名前空間に関する要素インターフェイスが HTMLUnknownElement なら、
      1. [22] NotSupportedError を投げます。
      2. [69] CEReactions の事後処理を行います。
      3. [70] ここで停止します。
    3. [23] 局所名を、extends に設定します。
  9. [13] 文脈オブジェクトの要素定義が走っているフラグが設定されていれば、
    1. [63] NotSupportedError を投げます。
    2. [79] CEReactions の事後処理を行います。
    3. [80] ここで停止します。
  10. [96] 文脈オブジェクトの要素定義が走っているフラグを設定します。
  11. [64] 写像と被観測属性群を、構築器についてメンバーの処理 (>>74) を実行した結果に設定します。例外を、投げられた例外に設定します。
  12. [81] 文脈オブジェクトの要素定義が走っているフラグを削除します。
  13. [76] 例外が null でなければ、
    1. [77] CEReactions の事後処理を行います。
    2. [78] 例外を改めて投げ、ここで停止します。
  14. [39] 定義を、カスタム要素定義に設定します。
    カスタム要素定義
    名前定義名
    名前
    局所名
    局所名
    構築器カスタム要素構築器
    構築器
    被観察属性群
    被観察属性群
    生活環コールバック群
    写像
  15. [40] 定義を、文脈オブジェクトに追加します。
  16. [41] 文書を、文脈オブジェクトの大域オブジェクトの文書に設定します。
  17. [42]
    • [47] 文書の影を含む子孫
    • [43] 名前空間がHTML名前空間
    • [44] 局所名が局所名
    • [45] extends が null でない場合、 is値が名前
    ... のすべてを満たす要素要素について、影を含む木順に、
    1. [48] enqueue a custom element upgrade reaction を要素と定義について実行します。
  18. [49] 文脈オブジェクトの定義時約束写像にキーが名前の項目項目が含まれていれば、
    1. [50] 項目の値を未定義について解決約束の解決します。
    2. [51] 項目を文脈オブジェクトの定義時約束写像から削除します。
  19. [7] CEReactions の事後処理を行います。

[74] メンバーの処理とは、構築器について次のようにすることを言います。

  1. [30] プロトタイプを、 Get(構築器, prototype) に設定します。例外が投げられれば、改めて投げ、ここで停止します。
  2. [31] プロトタイプに Type を適用した結果が Object でなければ、
    1. [32] TypeError を投げ、ここで停止します。
  3. [33] 写像を、写像に設定します。
  4. [34] コールバック名として connectedCallback, disconnectedCallback, adoptedCallback, attributeChangedCallback について順に、
    1. [35] コールバックを、 Get(プロトタイプ, コールバック名) の結果を Function に変換変換 (Web IDL)したものに設定します。 例外が投げられれば、改めて投げ、ここで停止します。
    2. [38] 写像にキーコールバック名、値コールバックの組を追加します。
  5. [85] 写像にキー attributeChangedCallback の項目が存在すれば、
    1. [72] iterable を、写像のキー attributeChangedCallback の項目に設定します。
    2. [82] iterable が未定義でなければ、
      1. [29] 被観察属性群を、 iterable を sequencesequence<><DOMString> に変換変換 (WebIDL)した結果に設定します。 例外が投げられれば、改めて投げ、ここで停止します。
    3. [28] それ以外なら、
      1. [83] 被観察属性群を、空の列sequence<>に設定します。
  6. [26] それ以外なら、
    1. [27] 被観察属性群を、空の列sequence<>に設定します。
  7. [71] 写像と被観測属性群を返します。

[95] CustomElementsRegistry オブジェクトは、 要素定義が走っているelement definition is runningフラグを持ちます >>2。

[86] CustomElementsRegistry オブジェクトは、 定義される名前の集合set of being-defined namesと定義される構築器の集合set of being-defined constructorsを持ちます >>2。これらは define が同じカスタム要素名やカスタム要素構築器で再帰的に呼び出されるのを防ぐためのものです。

歴史

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

[57] Editorial: rename ElementRegistrationOptions to ElementDefinitionOptions ( (domenic著, )) https://github.com/whatwg/html/commit/a082daa4aa272f4eae77b67aa3116af482f03e5e

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

[75] Correctly find upgrade candidates during custom element definition ( (domenic著, )) https://github.com/whatwg/html/commit/edda04a44c64352387199ba6ed412d27ea305bfb

[46] Don't read observedAttributes if there is no attributeChangedCallback (domenic著, ) https://github.com/whatwg/html/commit/9ac1071abe7fca185604b56b89cb969ea34e39db

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

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

[37] Handle reentrant custom element definition (domenic著, ) https://github.com/whatwg/html/commit/270b5f3e48411063c431fdf98dbe41766ddc20b1

[87] Disallow defining a custom element using HTMLElement or its subclasses (domenic著, ) https://github.com/whatwg/html/commit/69847259ecd9b3166b88e24ab2d5f6dd8bd59aec

[90] Disallow mismatches between custom element local names and brands (domenic著, ) https://github.com/whatwg/html/commit/0c45df84a6dab701e5a8e3eefd3d566ce3591737

[91] Disallow customElements.define being given named constructors (domenic著, ) https://github.com/whatwg/html/commit/f9c5830228859596589090ee41417798a2641875

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

[93] Clarify the order of saving custom element callbacks (domenic著, ) https://github.com/whatwg/html/commit/5ce53c222382bf884ab9e9879396543bf00d4fef

[94] Simplify the reentrance guard for custom element definition (domenic著, ) https://github.com/whatwg/html/commit/4bfa7130c7e2f953b07787d8a297eacdf51644e2

[84] Move the check on registering an element interface as a custom element (domenic著, ) https://github.com/whatwg/html/commit/9c9b08013261bfa93cce4cbddbcd03d866717e11

[88] Use new.target.prototype in HTML element constructors (domenic著, ) https://github.com/whatwg/html/commit/93ce959946249590515a3cf1a4b939a24605fc90

[89] window.customElements.define retrieves the lifetime callbacks in an odd order · Issue #3580 · whatwg/html () https://github.com/whatwg/html/issues/3580

[97] Editorial: make the type of custom element constructors stricter (yuki3著, ) https://github.com/whatwg/html/commit/f8bd887aff17a5ffaf8c50c76b937815c92fc5e4

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