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

仕様書

[2] HTML Standard (2016-05-14 09:55:50 +09:00) https://html.spec.whatwg.org/#element-definition

意味

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

引数

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

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

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

extends

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

[56] createElement では要素名をまず指定して is メンバーにカスタム要素定義の名前を指定しますが、 define では逆に名前をまず指定して、 extends メンバーに要素名を指定します。

class MyElement extends HTMLElement {
};
customElements.define ("my-element", MyElement);

処理

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

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

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

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

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

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