Edit

Page

Page title:

Page body:

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

* 仕様書

[REFS[
- [3] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) <https://html.spec.whatwg.org/#custom-element-conformance>
- [14] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) <https://html.spec.whatwg.org/#custom-element-constructor>
- [17] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) <https://html.spec.whatwg.org/#concept-custom-element-definition-constructor>
- [19] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) <https://html.spec.whatwg.org/#concept-upgrade-an-element>
- [45] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) <https://html.spec.whatwg.org/#upgrade-reaction>
- [43] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) <https://html.spec.whatwg.org/#enqueue-a-custom-element-upgrade-reaction>
]REFS]

* 意味

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

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

* 著者の要件

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

[FIG(list)[
- [5] [[構築器本体]]の最初の[[文]]として、[[引数]]なしで [CODE(JS)@en[super]]
を[[呼び出し]]する。
-- [6] これは、他の[[コード]]の[[実行]]前に正しい[[プロトタイプ鎖]]と
[CODE(JS)@en[this]] 値を確立するものです。
- [7] [CODE(JS)@en[return]] [[文]]は、単純な [[early-return]]
([CODE(JS)@en[return]] または [CODE(JS)@en[[[return]] [[this]]]])
の場合を除き、[[構築器本体]]中で使わない。
- [8] [[内容属性]]や[[内容]]を検査しない。
-- [9] [[格上げ][格上げ (カスタム要素)]]でない場合には[[内容属性]]や[[内容]]は現れません。
[[格上げ][格上げ (カスタム要素)]]の時にしか使えない[[要素]]は不便です。
- [10] [[内容属性]]や[[内容]]を設定しない。
-- [11] [CODE(DOMm)@en[createElement]] や [CODE(DOMm)@en[createElementNS]]
の呼び出し側の期待に反するからです。
- [74] [CODE(JS)@en[document.open]] や [CODE(JS)@en[document.write]] を使わない。
]FIG]

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

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

* [CODE[CustomElementConstructor]] 型

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

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

* [F[構築器][カスタム要素構築器]] (カスタム要素定義)

[18] [[カスタム要素定義]]は、[DFN[[F[[RUBYB[構築器]@en[constructor]]][カスタム要素構築器]]]]を持ちます [SRC[>>17]]。
[F[構築器][カスタム要素構築器]]は、[[カスタム要素構築器]]です [SRC[>>17]]。

[56] [F[構築器][カスタム要素構築器]]は、次の場面で呼び出されます。
[FIG(list short)[
- [[要素の作成]]
- [[要素の格上げ]]
]FIG]

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

* 格上げ

[51] [[カスタム要素]]の条件を潜在的に満たす[[要素]]を、
実際に[[カスタム要素]]とする操作を、
[[要素の格上げ]]といいます。[[要素の格上げ]]は、次の場面で、
適切な[[カスタム要素定義]]が存在する場合に行われます。
[FIG(list)[
- [52] [[要素の作成]]・[[字句の要素の作成]]
- [53] [[挿入]]
- [54] [[要素定義]] ([CODE(DOMm)@en[define]])
- [94] [[著者]]の明示的な指示 ([CODE(DOMm)@en[upgrade][要素の格上げ]])
]FIG]

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

-*-*-

[89] [CODE(DOMi)@en[CustomElementRegistry]] [[インターフェイス]]の
[DFN[[CODE(DOMm)@en[upgrade][要素の格上げ]]]] [[メソッド]]は、
[CODE[CEReactions]] であり、次のようにしなければ[MUST[なりません]] [SRC[>>19]]。

[FIG(steps)[
= [90] [VAR[根]]を、第1引数を [CODE(DOMi)@en[Node]] として解釈した結果に設定します。
= [91] [VAR[候補群]]を、
[VAR[根]]の[[影を含む包括的子孫]]の[[要素]]すべての[[影を含む木順]]の[[リスト]]に設定します。
= [92] [VAR[候補群]]の各[VAR[候補]]について、順に、
== [93] [VAR[候補]]の[[要素の格上げの試行]]を行います。
]FIG]

[36] [DFN[[RUBYB[要素の格上げの試行]@en[try to upgrade an element]]]]は、
[[要素]][VAR[要素]]について、次のようにします [SRC[>>19]]。
[FIG(steps)[
= [39] [VAR[定義]]を、[VAR[要素]]の[F[節点文書]]、[VAR[要素]]の[F[名前空間]]、
[VAR[要素]]の[F[局所名]]、[VAR[要素]]の[F[[[[CODE[is]]値]]]]について[[カスタム要素定義を探す]]処理を実行した結果に設定します。
= [40] [VAR[定義]]が [CODE[null]] でない場合、
== [41] [VAR[要素]]と[VAR[定義]]について、 [[enqueue a custom element upgrade reaction]]
を実行します。
]FIG]

;; [42] これは、[CODE[upgrade][要素の格上げ]] の他、
[[挿入]]から呼び出されます。

[20] [DFN[[RUBYB[要素の格上げ]@en[upgrade an element]]]]は、
[[カスタム要素定義]][VAR[定義]]と[[要素]][VAR[要素]]について、
次のようにします [SRC[>>19]]。
[FIG(steps)[
= [64] [VAR[要素]]が[F[カスタム]]か[VAR[要素]]の[F[カスタム要素状態]]が
[CODE[failed]] なら、
== [65] ここで停止します。
= [72] [VAR[要素]]の[F[カスタム要素定義]]を、[VAR[定義]]に設定します。
= [31] [VAR[要素]]の[F[属性リスト]]の各[VAR[属性]]について順に、
== [32] [[enqueue a custom element callback reaction]] を実行します。
[FIG(list members)[
: [VAR[要素]] : [VAR[要素]]
: [VAR[コールバック名]] : [CODE[attributeChangedCallback]]
: [VAR[引数リスト]] : 
[FIG(list)[
= [VAR[属性]]の[F[局所名]]
= [[null]]
= [VAR[属性]]の[F[値]]
= [VAR[属性]]の[F[名前空間]]
]FIG]
]FIG]
= [33] [VAR[要素]]が[[影を含む文書中]]なら、
== [34] [[enqueue a custom element callback reaction]] を実行します。
[FIG(list members)[
: [VAR[要素]] : [VAR[要素]]
: [VAR[コールバック名]] : [CODE[connectedCallback]]
: [VAR[引数リスト]] : [[空]]
]FIG]
= [21] [VAR[要素]]を、[VAR[定義]]の[F[構築スタック]]の末尾に追加します。
= [22] [VAR[構築器]]を、[VAR[定義]]の[F[構築器][カスタム要素構築器]]に設定します。
= [23] [VAR[結果]]を、[VAR[構築器]]について[[構築]]した結果に設定します。
([[例外]]が[[投げ]]られることもあります。)
= [27] [VAR[結果]]が[[例外]]が[[投げ]]られたことを表していなければ、
== [80] [CODE[[[SameValue]]([VAR[結果]], [VAR[要素]])]] が[[偽]]の場合、
==- [29] これは、 >>5 や >>7 に違反すると発生することがあります。
=== [79] [VAR[結果]]を、 [CODE(DOMe)@en[InvalidStateError]] [[例外]]が[[投げ]]られたとします。
= [24] [VAR[定義]]の[F[構築スタック]]の末尾の項目を削除します。
= [25] [VAR[結果]]が[[例外]]が[[投げ]]られたことを表していれば、
== [70] [VAR[要素]]の[F[カスタム要素状態]]を、 [CODE[failed]] に設定します。
== [85] [VAR[要素]]の[F[カスタム要素定義]]を、 [CODE[null]] に設定します。
== [81] [VAR[要素]]の[F[カスタム要素反応キュー]]を、空にします。
== [26] [VAR[結果]]の[[例外]]を[[投げ]]、ここで停止します。
= [30] [VAR[要素]]の[F[カスタム要素状態]]を、 [CODE[custom]] に設定します。
]FIG]

;; [35] これは、[[要素の作成]]や [CODE(IDL xattr)@en[CEReactions]] から呼び出されます。

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

[46] [DFN[[RUBYB[カスタム要素格上げ反応をキューに追加]@en[enqueue a custom element upgrade reaction]]]]するには、
[[要素]][VAR[要素]]、
[[カスタム要素定義]][VAR[定義]]について、次のようにします [SRC[>>43]]。
[FIG(steps)[
= [47] [VAR[要素]]の[F[カスタム要素反応キュー]]に、
[VAR[定義]]の[[格上げ反応]]を追加します。
= [48] [VAR[要素]]について[[適切な要素キューに要素を追加]]します。
]FIG]

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

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

* 歴史

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

[2] [CITE@en[Add customElements.get() to retrieve a custom element constructor · whatwg/html@1d596a5]]
([TIME[2016-04-26 18:41:22 +09:00]] 版)
<https://github.com/whatwg/html/commit/1d596a555d3c2f067ae643e447eaa88137b595ac>

[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>

[59] [CITE@en[Editorial: custom element state "customized" → "custom"]]
( ([[domenic]]著, [TIME[2016-05-20 14:30:45 +09:00]]))
<https://github.com/whatwg/html/commit/5946d084658ff2f8d5ec3cea3c448175eaa5336e>

[61] [CITE@en[Fix inaccurate stack-popping in custom element upgrades]]
( ([[domenic]]著, [TIME[2016-05-29 15:06:11 +09:00]]))
<https://github.com/whatwg/html/commit/6561250ec3788938a2d64932093b0ea293b97174>

[62] [CITE@en[Enqueue custom element reactions appropriately during upgrades]]
([[domenic]]著, [TIME[2016-06-06 16:44:11 +09:00]])
<https://github.com/whatwg/html/commit/2328ccf97b80cba7835df3dc5d1a687d51fbfcf4>

[63] [CITE@en[Don't upgrade custom elements twice]]
([[domenic]]著, [TIME[2016-06-07 16:54:38 +09:00]])
<https://github.com/whatwg/html/commit/5798c66579b8076660178f484568adc67421dc23>

[66] [CITE@en[Prevent double custom element reaction enqueuing via upgrades]]
([[domenic]]著, [TIME[2016-06-24 01:21:10 +09:00]])
<https://github.com/whatwg/html/commit/657d3b2b97a0fd5ff1c353857f5b052f41bd3e0d>

[67] [CITE@en[Take care of missing custom element reactions]]
([[domenic]]著, [TIME[2016-06-30 03:04:46 +09:00]])
<https://github.com/whatwg/html/commit/a57c88711c995356e44d019f5bd81d0cdedac2bf>

[68] [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>

[69] [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[Set the stage for preventing double custom element constructor calls]]
([[domenic]]著, [TIME[2016-07-19 02:13:14 +09:00]])
<https://github.com/whatwg/dom/commit/539e45214f682797f4fa022815a08b6f044e1240>

[38] [CITE@en[Prevent double custom element constructor calls]]
([[domenic]]著, [TIME[2016-07-19 02:13:43 +09:00]])
<https://github.com/whatwg/html/commit/04e90c55c7526d8c96d20159bb23586670b93fd2>

[71] [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>

[73] [CITE@en[Make document.write etc. throw during parsing custom elements]]
([[domenic]]著, [TIME[2016-08-17 15:44:39 +09:00]])
<https://github.com/whatwg/html/commit/00c6fa07bdb9f0d08a28f6c6e1ababca7d08618c>

[75] [CITE@en[Make document.write etc. throw during parsing custom elements]]
([[domenic]]著, [TIME[2016-08-17 15:44:39 +09:00]])
<https://github.com/whatwg/html/commit/00c6fa07bdb9f0d08a28f6c6e1ababca7d08618c>

[76] [CITE@en[Set the custom element state to failed when upgrades misbehave]]
([[domenic]]著, [TIME[2016-09-07 06:40:05 +09:00]])
<https://github.com/whatwg/html/commit/b687759d5eccb354faca78fda5001ce3db428749>

[78] [CITE@en[Clear the custom element reaction queue if upgrading fails]]
([[domenic]]著, [TIME[2016-09-15 23:33:03 +09:00]])
<https://github.com/whatwg/html/commit/d00b810aeccf9a272b17400ed3daed7f100adec1>

[28] [CITE@en[Use Web IDL to construct custom element constructors]]
([[domenic]]著, [TIME[2017-03-28 13:20:59 +09:00]])
<https://github.com/whatwg/dom/commit/1ca094a209ba020348ac146c8bda157b7c5f3212>

[77] [CITE@en[Clarify custom element reaction arguments passed]]
([[domenic]]著, [TIME[2017-10-21 06:47:04 +09:00]])
<https://github.com/whatwg/html/commit/c5019ae75d7dfaaf7829cf45c56700e97b24ea61>

[82] [CITE@en[Custom Elements Methods Clarification · Issue #2299 · whatwg/html]]
([TIME[2017-10-21 16:28:52 +09:00]])
<https://github.com/whatwg/html/issues/2299>

[83] [CITE@en[Clarify custom element reaction arguments passed by domenic · Pull Request #3125 · whatwg/html]]
([TIME[2017-10-21 16:29:21 +09:00]])
<https://github.com/whatwg/html/pull/3125>

[84] [CITE@en[Fix ordering of custom element upgrade steps]]
([[domenic]]著, [TIME[2017-10-14 05:53:29 +09:00]])
<https://github.com/whatwg/html/commit/2b8a4752415a3a831adf41a97c217963455de220>

[86] [CITE@en[Elements that are upgrading have no CE definition when callback reactions are enqueued · Issue #2876 · whatwg/html]]
([TIME[2017-11-25 00:35:21 +09:00]])
<https://github.com/whatwg/html/issues/2876>

[87] [CITE@en[Fix ordering of custom element upgrade steps by domenic · Pull Request #3124 · whatwg/html]]
([TIME[2017-11-25 00:36:07 +09:00]])
<https://github.com/whatwg/html/pull/3124>

[88] [CITE@en[Add customElements.upgrade()]]
([[domenic]]著, [TIME[2018-03-07 14:23:26 +09:00]])
<https://github.com/whatwg/html/commit/6df48639fb6d6189a346ea7349f13fd14ace4c99>

[95] [CITE@en[Add customElements.upgrade()]]
([[domenic]]著, [TIME[2018-03-07 14:23:26 +09:00]])
<https://github.com/whatwg/html/commit/6df48639fb6d6189a346ea7349f13fd14ace4c99>

[96] [CITE@en[Add `customElements.upgrade` · Issue #710 · w3c/webcomponents]]
([TIME[2018-03-20 17:24:46 +09:00]])
<https://github.com/w3c/webcomponents/issues/710>

[97] [CITE@en[Add customElements.upgrade() by domenic · Pull Request #3535 · whatwg/html]]
([TIME[2018-03-20 17:25:53 +09:00]])
<https://github.com/whatwg/html/pull/3535>

[98] [CITE@en[Fix customElements.upgrade() to use shadow-including tree order]]
([[tkent-google]]著, [TIME[2018-04-16 11:04:13 +09:00]])
<https://github.com/whatwg/html/commit/5b653a9145425b32a4f1c78ffb1a1bda7fde9a6b>

[99] [CITE@en[custom-element: customElements.upgrade() should use "shadow-including tree order" by tkent-google · Pull Request #3626 · whatwg/html]]
([TIME[2018-04-17 15:04:01 +09:00]])
<https://github.com/whatwg/html/pull/3626>

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

Historical Legal Sensitive Parent: [Help / License]

Edit

Page

Page name(s)