Edit

Page

Page title:

Page body:

* 仕様書

[REFS[
- [2] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) <https://html.spec.whatwg.org/#element-definition>
]REFS]

* 意味

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

* 引数

[52] 本[[メソッド]]は、次の[[引数]]を受け取ります。
[FIG(list members)[
: [VAR[名前]] : 作成する[[カスタム要素定義]]の[F[名前][定義名]]となる[[妥当なカスタム要素名]]。 
[CODE[extends]] を指定する場合
([[カスタム化組み込み要素]]) は [CODE[is][is=""]] [[属性値]]、
指定しない場合 ([[自律カスタム要素]]) は[[要素名]]に相当します。
この引数は必須で、既存の他の[[カスタム要素定義]]の[F[名前][定義名]]と違っていなければなりません。
: [VAR[構築器]] : 作成する[[カスタム要素定義]]の[F[構築器][カスタム要素構築器]]となる[[関数]]。
この引数は必須で、既存の他の[[カスタム要素定義]]の[F[構築器][カスタム要素構築器]]と違っていなければなりません。
[[カスタム要素構築器]]の条件を満たすものである必要があります。
: [VAR[オプション群]] : [[辞書]] [CODE(DOMi)@en[ElementDefinitionOptions]]。
省略可能です。
]FIG]

[53] [[辞書]] [DFN[[CODE(DOMi)@en[ElementDefinitionOptions]]]] [SRC[>>2]] は、
次の[[メンバー]]を持ちます。
[FIG(list short)[
- [CODE(DOMa)@en[extends]]
]FIG]

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

;; [56] [CODE(DOMm)@en[createElement]] では[[要素名]]をまず指定して
[CODE(DOMa)@en[is][is=""]] [[メンバー]]に[[カスタム要素定義]]の[F[名前][定義名]]を指定しますが、
[CODE(DOMm)@en[define]] では逆に[F[名前][定義名]]をまず指定して、
[CODE(DOMa)@en[extends]] [[メンバー]]に[[要素名]]を指定します。

[EG[
[PRE(HTML code)[
class MyElement extends HTMLElement {
};
customElements.define ("my-element", MyElement);
]PRE]
]EG]

* 処理

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

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

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

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

[95] [CODE(DOMi)@en[CustomElementsRegistry]] [[オブジェクト]]は、
[DFN[[F[[RUBYB[[[要素定義が走っている]]]@en[element definition is running]]]]]]フラグを持ちます [SRC[>>2]]。

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

* 歴史

[1] [CITE@en[Add custom elements to HTML · whatwg/html@6e7eaa4]]
([TIME[2016-04-26 18:19:26 +09:00]] 版)
<https://github.com/whatwg/html/commit/6e7eaa4bd2912965fd83766f99f984f249531f3a>

[57] [CITE@en[Editorial: rename ElementRegistrationOptions to ElementDefinitionOptions]]
( ([[domenic]]著, [TIME[2016-05-08 23:29:58 +09:00]]))
<https://github.com/whatwg/html/commit/a082daa4aa272f4eae77b67aa3116af482f03e5e>

[58] [CITE@en[Make custom element definition trigger in-document upgrades]]
( ([[domenic]]著, [TIME[2016-05-10 15:52:27 +09:00]]))
<https://github.com/whatwg/html/commit/11bdd701e79c8dd6040586b5257eb01f3b620659>

[75] [CITE@en[Correctly find upgrade candidates during custom element definition]]
( ([[domenic]]著, [TIME[2016-05-17 15:06:36 +09:00]]))
<https://github.com/whatwg/html/commit/edda04a44c64352387199ba6ed412d27ea305bfb>

[46] [CITE@en[Don't read observedAttributes if there is no attributeChangedCallback]]
([[domenic]]著, [TIME[2016-06-16 17:08:30 +09:00]])
<https://github.com/whatwg/html/commit/9ac1071abe7fca185604b56b89cb969ea34e39db>

[25] [CITE@en[Convert custom element callbacks to Web IDL callback types]]
([[domenic]]著, [TIME[2016-06-30 02:10:53 +09:00]])
<https://github.com/whatwg/html/commit/be055730a11a8f952feb8fdb73e7caa01460e5a4>

[36] [CITE@en[Fix customized built-in element "is" handling and reactions]]
([[domenic]]著, [TIME[2016-06-07 01:55:58 +09:00]])
<https://github.com/whatwg/html/commit/4e632a82728d68a8a6bd32f02083762b7792ddf7>

[37] [CITE@en[Handle reentrant custom element definition]]
([[domenic]]著, [TIME[2016-06-07 17:18:04 +09:00]])
<https://github.com/whatwg/html/commit/270b5f3e48411063c431fdf98dbe41766ddc20b1>

[87] [CITE@en[Disallow defining a custom element using HTMLElement or its subclasses]]
([[domenic]]著, [TIME[2016-06-16 17:09:53 +09:00]])
<https://github.com/whatwg/html/commit/69847259ecd9b3166b88e24ab2d5f6dd8bd59aec>

[90] [CITE@en[Disallow mismatches between custom element local names and brands]]
([[domenic]]著, [TIME[2016-07-20 03:00:04 +09:00]])
<https://github.com/whatwg/html/commit/0c45df84a6dab701e5a8e3eefd3d566ce3591737>

[91] [CITE@en[Disallow customElements.define being given named constructors]]
([[domenic]]著, [TIME[2016-07-21 14:53:26 +09:00]])
<https://github.com/whatwg/html/commit/f9c5830228859596589090ee41417798a2641875>

[92] [CITE@en[Implement new custom element adoption semantics]]
([[domenic]]著, [TIME[2016-07-21 18:25:57 +09:00]])
<https://github.com/whatwg/html/commit/feb77d09793a2ed8d49a6949dbca73eabb60ae79>

[93] [CITE@en[Clarify the order of saving custom element callbacks]]
([[domenic]]著, [TIME[2016-08-16 05:50:11 +09:00]])
<https://github.com/whatwg/html/commit/5ce53c222382bf884ab9e9879396543bf00d4fef>

[94] [CITE@en[Simplify the reentrance guard for custom element definition]]
([[domenic]]著, [TIME[2016-08-20 14:15:29 +09:00]])
<https://github.com/whatwg/html/commit/4bfa7130c7e2f953b07787d8a297eacdf51644e2>

[84] [CITE@en[Move the check on registering an element interface as a custom element]]
([[domenic]]著, [TIME[2016-08-23 16:20:59 +09:00]])
<https://github.com/whatwg/html/commit/9c9b08013261bfa93cce4cbddbcd03d866717e11>

[88] [CITE@en[Use new.target.prototype in HTML element constructors]]
([[domenic]]著, [TIME[2016-09-15 23:34:11 +09:00]])
<https://github.com/whatwg/html/commit/93ce959946249590515a3cf1a4b939a24605fc90>

[89] [CITE@en[window.customElements.define retrieves the lifetime callbacks in an odd order · Issue #3580 · whatwg/html]]
([TIME[2018-03-23 02:06:41 +09:00]])
<https://github.com/whatwg/html/issues/3580>

[97] [CITE@en[Editorial: make the type of custom element constructors stricter]]
([[yuki3]]著, [TIME[2018-05-30 00:29:26 +09:00]])
<https://github.com/whatwg/html/commit/f8bd887aff17a5ffaf8c50c76b937815c92fc5e4>

[98] [CITE@en[Make the type of custom element constructor stricter by yuki3 · Pull Request #3703 · whatwg/html]]
([TIME[2018-06-01 01:33:47 +09:00]])
<https://github.com/whatwg/html/pull/3703>

Historical Legal Sensitive Parent: [Help / License]

Edit

Page

Errors

Page name(s)