/
862.txt
191 lines (157 loc) · 10.3 KB
/
862.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
[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]]
の呼び出し側の期待に反するからです。
]FIG]
[13] 一般に、[[構築器]]は、初期状態や既定値の設定、
[[イベントリスナー]]や[[影ホスト]]の設定に使う[SHOULD[べきです]]。 [SRC[>>3]]
[12] 一般に、処理 (特に [[fetch]] や[[レンダリング]]を伴うもの)
はできるだけ[[構築器]]ではなく、 [CODE[connectedCallback]]
を使う[SHOULD[べきです]]。
[WEAK[ただし、 [CODE[connectedCallback]] は何度も実行されることがありますから、本当に一度だけ実行したい初期化作業は対策が必要になります。]]
[SRC[>>3]]
* [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]])
]FIG]
[55] [[要素の格上げ]]によって、元々 [CODE(DOMi)@en[HTMLElement]]
を[[実装]]していた[[要素]][[オブジェクト]]は、
[[カスタム要素構築器]]の実行を経て[[カスタム要素]]の[[クラス]]の[[オブジェクト]]になります。
[20] [DFN[[RUBYB[要素の格上げ]@en[upgrade an element]]]]は、
[[カスタム要素定義]][VAR[定義]]と[[要素]][VAR[要素]]について、
次のようにします [SRC[>>19]]。
[FIG(steps)[
= [64] [VAR[要素]]が[F[カスタム]]なら、
== [65] ここで停止します。
= [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[C]] を、[VAR[定義]]の[F[構築器][カスタム要素構築器]]に設定します。
= [23] [VAR[結果]]を、[VAR[C]] に [CODE[Construct]] を適用した結果に設定します。
= [24] [VAR[定義]]の[F[構築スタック]]の末尾の項目を削除します。
= [25] [VAR[結果]]が [[abrupt completion]] なら、
== [26] [VAR[結果]]を返してここで停止します。
(これは、[[例外]]が[[投げ]]られたら改めて[[投げ]]ることを表します。)
= [27] [VAR[結果]]の[F(ss)[値]]と[VAR[要素]]について [CODE[SameValue]]
を適用した結果が[[偽]]なら、
== [28] [CODE[InvalidStateError]] を[[投げ]]、ここで停止します。
=- [29] これは、 >>5 や >>7 に違反すると発生することがあります。
= [30] [VAR[要素]]の[F[カスタム要素状態]]を、 [CODE[custom]] に設定します。
]FIG]
;; [35] これは、[[要素の作成]]や [CODE(IDL xattr)@en[CEReactions]] から呼び出されます。
[36] [DFN[[RUBYB[要素の格上げの試行]@en[try to upgrade an element]]]]は、
[[要素]][VAR[要素]]について、次のようにします [SRC[>>19]]。
[FIG(steps)[
= [37] [VAR[文書]]を、[VAR[要素]]の[F[節点文書]]に設定します。
= [38] [VAR[is]] を、[VAR[要素]]の [CODE(HTMLa)@en[is][is=""]] [[属性値]]に設定します。
= [39] [VAR[定義]]を、[VAR[文書]]、[VAR[要素]]の[F[名前空間]]、
[VAR[要素]]の[F[局所名]]、[VAR[is]] について[[カスタム要素定義を探す]]処理を実行した結果に設定します。
= [40] [VAR[定義]]が [[null]] でなければ、
== [41] [VAR[要素]]と[VAR[定義]]について、 [[enqueue a custom element upgrade reaction]]
を実行します。
]FIG]
;; [42] これは、[[挿入]]から呼び出されます。
[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] [[関連する類似起源閲覧文脈群の単位]]の[F[カスタム要素キュー]]に、
[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>