* 仕様書 [REFS[ - [2] [CITE@en-GB-x-hixie[HTML Standard]] ([TIME[2016-05-14 09:55:50 +09:00]]) ]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]] 版) [57] [CITE@en[Editorial: rename ElementRegistrationOptions to ElementDefinitionOptions]] ( ([[domenic]]著, [TIME[2016-05-08 23:29:58 +09:00]])) [58] [CITE@en[Make custom element definition trigger in-document upgrades]] ( ([[domenic]]著, [TIME[2016-05-10 15:52:27 +09:00]])) [75] [CITE@en[Correctly find upgrade candidates during custom element definition]] ( ([[domenic]]著, [TIME[2016-05-17 15:06:36 +09:00]])) [46] [CITE@en[Don't read observedAttributes if there is no attributeChangedCallback]] ([[domenic]]著, [TIME[2016-06-16 17:08:30 +09:00]]) [25] [CITE@en[Convert custom element callbacks to Web IDL callback types]] ([[domenic]]著, [TIME[2016-06-30 02:10:53 +09:00]]) [36] [CITE@en[Fix customized built-in element "is" handling and reactions]] ([[domenic]]著, [TIME[2016-06-07 01:55:58 +09:00]]) [37] [CITE@en[Handle reentrant custom element definition]] ([[domenic]]著, [TIME[2016-06-07 17:18:04 +09:00]]) [87] [CITE@en[Disallow defining a custom element using HTMLElement or its subclasses]] ([[domenic]]著, [TIME[2016-06-16 17:09:53 +09:00]]) [90] [CITE@en[Disallow mismatches between custom element local names and brands]] ([[domenic]]著, [TIME[2016-07-20 03:00:04 +09:00]]) [91] [CITE@en[Disallow customElements.define being given named constructors]] ([[domenic]]著, [TIME[2016-07-21 14:53:26 +09:00]]) [92] [CITE@en[Implement new custom element adoption semantics]] ([[domenic]]著, [TIME[2016-07-21 18:25:57 +09:00]]) [93] [CITE@en[Clarify the order of saving custom element callbacks]] ([[domenic]]著, [TIME[2016-08-16 05:50:11 +09:00]]) [94] [CITE@en[Simplify the reentrance guard for custom element definition]] ([[domenic]]著, [TIME[2016-08-20 14:15:29 +09:00]]) [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]]) [88] [CITE@en[Use new.target.prototype in HTML element constructors]] ([[domenic]]著, [TIME[2016-09-15 23:34:11 +09:00]]) [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]]) [97] [CITE@en[Editorial: make the type of custom element constructors stricter]] ([[yuki3]]著, [TIME[2018-05-30 00:29:26 +09:00]]) [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]])