element definition

CustomElementsRegistry オブジェクト define メソッド (DOM)

仕様書

意味

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

引数

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

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

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

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

[56] createElement では要素名をまず指定して is メンバーカスタム要素定義名前を指定しますが、 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]
    ... のいずれかを満たす場合、
    1. [15] NotSupportedError投げます。
    2. [65] CEReactions の事後処理を行います。
    3. [66] ここで停止します。
  6. [17] extends を、オプション群extends に設定します。
  7. [18] extendsnull なら、
    1. [16] 局所名を、名前に設定します。
  8. [24] それ以外なら、
    1. [19] extends妥当なカスタム要素名なら
      1. [20] NotSupportedError投げます。
      2. [67] CEReactions の事後処理を行います。
      3. [68] ここで停止します。
    2. [21] extendsHTML名前空間に関する要素インターフェイス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]
    ... のすべてを満たす要素要素について、影を含む木順に、
    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変換したものに設定します。 例外投げられれば、改めて投げ、ここで停止します。
    2. [38] 写像キーコールバック名、値コールバックの組を追加します。
  5. [85] 写像キー attributeChangedCallback の項目が存在すれば、
    1. [72] iterable を、写像キー attributeChangedCallback の項目に設定します。
    2. [82] iterable未定義でなければ、
      1. [29] 被観察属性群を、 iterablesequence<DOMString>変換した結果に設定します。 例外投げられれば、改めて投げ、ここで停止します。
    3. [28] それ以外なら、
      1. [83] 被観察属性群を、空のに設定します。
  6. [26] それ以外なら、
    1. [27] 被観察属性群を、空のに設定します。
  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