1. 4.13 カスタム要素
      1. 4.13.1 導入
        1. 4.13.1.1 自律カスタム要素の作成
        2. 4.13.1.2 フォームに関連付けられたカスタム要素の作成
        3. 4.13.1.3 デフォルトでアクセシブルなロール、ステート、およびプロパティをもつカスタム要素を作成する
        4. 4.13.1.4 カスタマイズされた組み込み要素の作成
        5. 4.13.1.5 自律カスタム要素の欠点
        6. 4.13.1.6 作成後の要素のアップグレード
      2. 4.13.2 カスタム要素のコンストラクターと反応の要件
      3. 4.13.3 コアコンセプト
      4. 4.13.4 CustomElementRegistryインターフェイス
      5. 4.13.5 カスタム要素応答
      6. 4.13.6 要素内部
        1. 4.13.6.1 シャドウルートアクセス
        2. 4.13.6.2 フォームに関連付けられたカスタム要素
        3. 4.13.6.3 アクセシビリティセマンティックス

4.13 カスタム要素

Using_custom_elements

Support in all current engines.

Firefox63+Safari10.1+Chrome54+
Opera41+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android63+Safari iOS10.3+Chrome Android54+WebView Android54+Samsung Internet6.0+Opera Android41+
caniuse.com table

4.13.1 導入

カスタム要素は、著者に完全に機能するDOM要素を独自に構築する方法を提供する。スクリプティングなどで事後に追加されたアプリケーション固有の動作とともに、著者は文書内で非標準要素を常に使用することができたが、そのような要素は歴史的に不適合であり、あまり機能しなかった。カスタム要素を定義することで、著者はパーサーに要素を正しく構成する方法と、そのクラスの要素が変更にどのように反応するかを通知できる。

カスタム要素は、(カスタム要素の定義のような)低レベルの著者公開拡張ポイントに関して、(HTMLの要素のような)既存のプラットフォーム機能を説明することによって、"プラットフォームを合理化する"ための大きな努力の一部である。今日、HTMLの既存要素の振る舞いを完全に説明することを妨げるカスタム要素(機能的および意味的な要素)の機能には多くの制限があるが、我々は時間の経過とともにこのギャップを縮小したいと思う。

4.13.1.1 自律カスタム要素の作成

自律カスタム要素を作成する方法を説明するために、国旗の小さなアイコンのレンダリングをカプセル化するカスタム要素を定義してみよう。私たちの目標は、次のように使用できるようにすることである:

<flag-icon country="nl"></flag-icon>

これを行うには、まずカスタム要素のクラスを宣言し、HTMLElementを拡張する:

class FlagIcon extends HTMLElement {
  constructor() {
    super();
    this._countryCode = null;
  }

  static get observedAttributes() { return ["country"]; }

  attributeChangedCallback(name, oldValue, newValue) {
    // name will always be "country" due to observedAttributes
    this._countryCode = newValue;
    this._updateRendering();
  }
  connectedCallback() {
    this._updateRendering();
  }

  get country() {
    return this._countryCode;
  }
  set country(v) {
    this.setAttribute("country", v);
  }

  _updateRendering() {
    // Left as an exercise for the reader. But, you'll probably want to
    // check this.ownerDocument.defaultView to see if we've been
    // inserted into a document with a browsing context, and avoid
    // doing any work if not.
  }
}

次に、要素を定義するために次のクラスを使用して必要がある:

customElements.define("flag-icon", FlagIcon);

この時点で、上記のコードは動作する。flag-iconタグを見るたびに、パーサーはFlagIconクラスの新しいインスタンスを作成し、要素の内部状態を設定し、レンダリングを更新するために使用する(適切な場合)、新しいcountry属性についてコードに伝える。

DOM APIを使用してflag-icon要素を作成することもできる:

const flagIcon = document.createElement("flag-icon")
flagIcon.country = "jp"
document.body.appendChild(flagIcon)

最後に、カスタム要素コンストラクター自体を使用することもできる。つまり、上記のコードは次のコードと同じである:

const flagIcon = new FlagIcon()
flagIcon.country = "jp"
document.body.appendChild(flagIcon)
4.13.1.2 フォームに関連付けられたカスタム要素の作成

trueの値を持つ静的なformAssociatedプロパティを追加すると、自律カスタム要素フォーム関連カスタム要素になる。ElementInternalsインターフェイスは、フォームコントロール要素に共通の関数およびプロパティを実装するのに役立つ。

class MyCheckbox extends HTMLElement {
  static get formAssociated() { return true; }
  static get observedAttributes() { return ['checked']; }

  constructor() {
    super();
    this._internals = this.attachInternals();
    this.addEventListener('click', this._onClick.bind(this));
  }

  get form() { return this._internals.form; }
  get name() { return this.getAttribute('name'); }
  get type() { return this.localName; }

  get checked() { return this.getAttribute('checked'); }
  set checked(flag) { this.toggleAttribute('checked', Boolean(flag)); }

  attributeChangedCallback(name, oldValue, newValue) {
    // name will always be "checked" due to observedAttributes
    this._internals.setFormValue(this.checked ? 'on' : null);
  }

  _onClick(event) {
    this.checked = !this.checked;
  }
}
customElements.define('my-checkbox', MyCheckbox);

カスタム要素my-checkboxは、組み込みのフォームに関連付けられた要素のように使うことができる。たとえば、formまたはlabel の中に置くことでmy-checkbox要素が関連付けられ、formを送信することでmy-checkbox実装で提供されるデータが送信される。

<form action="..." method="...">
  <label><my-checkbox name="agreed"></my-checkbox> I read the agreement.</label>
  <input type="submit">
</form>
4.13.1.3 デフォルトでアクセシブルなロール、ステート、およびプロパティをもつカスタム要素を作成する

ElementInternalsの適切なプロパティを使用することにより、カスタム要素はデフォルトのアクセシビリティセマンティクスを持つことができる。 次のコードは、前のセクションのフォームに関連付けられたチェックボックスを拡張して、アクセシビリティ技術から見たデフォルトのロールおよびチェック状態を適切に設定する:

class MyCheckbox extends HTMLElement {
  static get formAssociated() { return true; }
  static get observedAttributes() { return ['checked']; }

  constructor() {
    super();
    this._internals = this.attachInternals();
    this.addEventListener('click', this._onClick.bind(this));

    this._internals.role = 'checkbox';
    this._internals.ariaChecked = false;
  }

  get form() { return this._internals.form; }
  get name() { return this.getAttribute('name'); }
  get type() { return this.localName; }

  get checked() { return this.getAttribute('checked'); }
  set checked(flag) { this.toggleAttribute('checked', Boolean(flag)); }

  attributeChangedCallback(name, oldValue, newValue) {
    // name will always be "checked" due to observedAttributes
    this._internals.setFormValue(this.checked ? 'on' : null);
    this._internals.ariaChecked = this.checked;
  }

  _onClick(event) {
    this.checked = !this.checked;
  }
}
customElements.define('my-checkbox', MyCheckbox);

組み込み要素の場合と同様に、これらはデフォルトにすぎず、roleおよびaria-*属性を使用するページ著者によって上書きできることに注意する:

<!-- This markup is non-conforming -->
<input type="checkbox" checked role="button" aria-checked="false">
<!-- This markup is probably not what the custom element author intended -->
<my-checkbox role="button" checked aria-checked="false">

カスタム要素の著者は、アクセシビリティセマンティクスのどの側面が強いネイティヴセマンティクスであるかを説明することが勧められる。つまり、カスタム要素のユーザーによって上書きされるべきではない。この例では、my-checkbox要素の著者は、そのroleおよびaria-checked値は強いネイティヴセマンティクスであるため、上記のようなコードを勧めないと述べている。

4.13.1.4 カスタマイズされた組み込み要素の作成

カスタマイズされた組み込み要素は、自律カスタム要素とはわずかに異なる定義があり、そして大きく異なる使われ方をする、独自の種類のカスタム要素である。この要素は、新しいカスタム機能でHTMLの既存要素を拡張することで、HTMLの既存要素由来の動作の再利用を可能にするために存在する。残念なことに、HTML要素の既存の動作の多くが自律カスタム要素を純粋に使用して複製できないため、これは重要である。代わりに、カスタマイズされた組み込み要素は、既存の要素にカスタム構築動作、ライフサイクルフック、およびプロトタイプチェーンをインストールを可能にし、既存の要素の上にこれらの機能を本質的に"混在"させる。

カスタマイズされた組み込み要素は、ユーザーエージェントや他のソフトウェアが要素のセマンティクスおよび動作を識別するために要素のローカル名として扱うので、自律カスタム要素とは異なる構文を必要とする。つまり、既存の動作の上に構築するカスタマイズされた組み込み要素の概念は、元のローカル名を保持する拡張要素に決定的に依存する。

この例において、plastic-buttonというカスタマイズされた組み込み要素を作成する。これは通常のボタンのように動作するが、クリックするたびにファンシーなアニメーション効果が追加される。今回はHTMLElementの代わりにHTMLButtonElementを拡張するが、前と同じようにクラスを定義することから始める:

class PlasticButton extends HTMLButtonElement {
  constructor() {
    super();

    this.addEventListener("click", () => {
      // Draw some fancy animation effects!
    });
  }
}

カスタム要素を定義する場合、extendsオプションも指定する必要がある:

customElements.define("plastic-button", PlasticButton, { extends: "button" });

一般に、拡張されている要素の名前は、同じインターフェイスを共有する要素(HTMLQuoteElementを共有するqblockquoteの両者など)を共有するため、拡張する要素インターフェイスを単に調べるだけでは判断することができない。

解析されたHTMLソーステキストからカスタマイズされた組み込み要素を構築するには、button要素のis属性を使用する。

<button is="plastic-button">Click Me!</button>

カスタマイズされた組み込み要素自律カスタム要素として使用しようとするとうまくいかない。つまり、<plastic-button>Click me?</plastic-button>は特別な動作をしないHTMLElementを作成するだけである。

プログラムでカスタマイズしたビルトイン要素を作成する必要がある場合、次のcreateElement()の形式を使用することができる:

const plasticButton = document.createElement("button", { is: "plastic-button" });
plasticButton.textContent = "Click me!";

前と同じように、コンストラクターも動作する:

const plasticButton2 = new PlasticButton();
console.log(plasticButton2.localName);  // will output "button"
console.assert(plasticButton2 instanceof PlasticButton);
console.assert(plasticButton2 instanceof HTMLButtonElement);

プログラムでカスタマイズした組み込み要素を作成する場合、明示的に設定されていないのでis属性はDOMに存在しない。ただし、シリアライズ時に出力に追加される

console.assert(!plasticButton.hasAttribute("is"));
console.log(plasticButton.outerHTML); // will output '<button is="plastic-button"></button>'

作成方法に関係なく、buttonが特別であるすべての方法は、そのような"プラスチックボタン"にも適用される:フォーカス動作、フォーム送信に関与する能力、disabled属性など。

カスタマイズされた組み込み要素は、有用なユーザーエージェントが提供する動作またはAPIを持つ既存のHTML要素を拡張を可能にするように設計されている。そのため、この仕様で定義される既存のHTML要素のみを拡張することができ、要素インターフェイスとしてHTMLUnknownElementを使用するように定義されたbgsoundblinkisindexkeygenmulticolnextid、またはspacerなどのレガシー要素は拡張できない。

この要件の1つの理由は将来の互換性である。もしカスタマイズされた組み込み要素が、たとえばcomboboxのような、現在不明の要素を拡張したものが定義されたなら、派生したカスタマイズされた組み込み要素のコンシューマーが、ユーザーエージェント提供の動作に興味を持たない基本要素に依存するようになるため、これはこの仕様が将来combobox要素を定義することを妨げるかもしれない。

4.13.1.5 自律カスタム要素の欠点

以下で規定されているように、そして上記で触れたように、単にtaco-buttonという要素を定義して使用しても、そのような要素がボタンを表すことを意味しない。つまり、ウェブブラウザー、検索エンジン、アクセシビリティ技術などのツールは、定義された名前だけに基づいて、結果の要素をボタンとして自動的に処理しない。

自律カスタム要素を依然として使用する一方で、様々なユーザーに所望のボタンセマンティクスを伝えるためためには、複数の技術を用いる必要がある:

これらの点を念頭に置いて、(無効にする機能を含む)ボタンのセマンティクスを伝える責任を負ったフル機能のtaco-buttonは、次のようになる:

class TacoButton extends HTMLElement {
  static get observedAttributes() { return ["disabled"]; }

  constructor() {
    super();
    this._internals = this.attachInternals();
    this._internals.role = "button";

    this.addEventListener("keydown", e => {
      if (e.code === "Enter" || e.code === "Space") {
        this.dispatchEvent(new PointerEvent("click", {
          bubbles: true,
          cancelable: true
        }));
      }
    });

    this.addEventListener("click", e => {
      if (this.disabled) {
        e.preventDefault();
        e.stopImmediatePropagation();
      }
    });

    this._observer = new MutationObserver(() => {
      this._internals.ariaLabel = this.textContent;
    });
  }

  connectedCallback() {
    this.setAttribute("tabindex", "0");

    this._observer.observe(this, {
      childList: true,
      characterData: true,
      subtree: true
    });
  }

  disconnectedCallback() {
    this._observer.disconnect();
  }

  get disabled() {
    return this.hasAttribute("disabled");
  }
  set disabled(flag) {
    this.toggleAttribute("disabled", Boolean(flag));
  }

  attributeChangedCallback(name, oldValue, newValue) {
    // name will always be "disabled" due to observedAttributes
    if (this.disabled) {
      this.removeAttribute("tabindex");
      this._internals.ariaDisabled = "true";
    } else {
      this.setAttribute("tabindex", "0");
      this._internals.ariaDisabled = "false";
    }
  }
}

このかなり複雑な要素定義であっても、要素はカスタマーに使用する喜びとはならない。その要素は、自身の意志のtabindex属性を継続的に"発芽"し、tabindex="0"フォーカス機能の動作の選択は、現在のプラットフォームのbutton動作と一致しなくてもよい 。これは、(通常、コンシューマーがデフォルトの動作を上書きできるように予約されているにもかかわらず)そのためにtabindex属性の使用を強制する、現時点では、カスタム要素のデフォルトのフォーカス動作を指定する方法がないためである。

対照的に、前節で示したように、単一のカスタマイズされた組み込み要素は、button要素のセマンティクスと動作を自動的に継承する。これらの動作を手動で実装する必要はない。一般に、HTMLの既存要素の上に構築される重要な動作やセマンティクスを持つ要素については、カスタマイズされた組み込み要素の開発、保守、および消費が容易になる。

4.13.1.6 作成後の要素のアップグレード

要素定義はいつでも発生する可能性があるため、非カスタム要素が作成され、適切な定義を登録した後でカスタム要素にすることができる。 このプロセスを、通常の要素からカスタム要素に要素を"アップグレードする"と呼ぶ。

アップグレードは、パーサーなどで関連する要素が最初に作成された後に、カスタム要素定義を登録することが望ましい場合のシナリオを可能にする。これにより、カスタム要素内のコンテンツを段階的に強化することができる。例えば、以下の HTML文書において、img-viewerの要素定義は非同期的にロードされる:

<!DOCTYPE html>
<html lang="en">
<title>Image viewer example</title>

<img-viewer filter="Kelvin">
  <img src="images/tree.jpg" alt="A beautiful tree towering over an empty savannah">
</img-viewer>

<script src="js/elements/img-viewer.js" async></script>

ここでのimg-viewer要素の定義は、マークアップで<img-viewer>タグの後に配置された、async属性でマークされたscript要素を用いて読み込まれる。 スクリプトの読み込み中、img-viewer要素は、spanと同様に未定義の要素として扱われる。 スクリプトが読み込まれると、img-viewer要素が定義され、ページ上の既存のimg-viewer要素は、カスタム要素の定義が適用してアップグレードされる(これはおそらく、文字列"Kelvin"によって識別される画像フィルターの適用し、画像の視覚的外観を向上させることが含まれる )。


アップグレードは文書ツリー内の要素にのみ適用されることに注意する。(正式には、接続される要素。)文書に挿入されない要素は、アップグレードされないままである。例はこの点を説明する:

<!DOCTYPE html>
<html lang="en">
<title>Upgrade edge-cases example</title>

<example-element></example-element>

<script>
  "use strict";

  const inDocument = document.querySelector("example-element");
  const outOfDocument = document.createElement("example-element");

  // Before the element definition, both are HTMLElement:
  console.assert(inDocument instanceof HTMLElement);
  console.assert(outOfDocument instanceof HTMLElement);

  class ExampleElement extends HTMLElement {}
  customElements.define("example-element", ExampleElement);

  // After element definition, the in-document element was upgraded:
  console.assert(inDocument instanceof ExampleElement);
  console.assert(!(outOfDocument instanceof ExampleElement));

  document.body.appendChild(outOfDocument);

  // Now that we've moved the element into the document, it too was upgraded:
  console.assert(outOfDocument instanceof ExampleElement);
</script>

4.13.2 カスタム要素のコンストラクターと反応の要件

カスタム要素コンストラクターをオーサリングするとき、著者は以下の適合性要件に拘束される:

これらの要件のいくつかは、要素の作成中に直接的または間接的のいずれかでチェックされ、それらに従わないと、パーサーまたはDOM APIによってインスタンス化できないカスタム要素をもたらす。これは、たとえコンストラクターによって開始されたマイクロタスク内で作業が行われるとしても当てはまる。マイクロタスクのチェックポイントは、作成直後に発生する可能性があるためである。

カスタム要素反応を作成する場合、予期しない結果が生じる可能性があるため、ノードツリーの操作を避けるべきである。

要素のconnectedCallbackは、要素が切断される前にキューに入れることができるが、コールバックキューはまだ処理されているため、接続されなくなった要素のconnectedCallbackをもたらす:

class CParent extends HTMLElement {
  connectedCallback() {
    this.firstChild.remove();
  }
}
customElements.define("c-parent", CParent);

class CChild extends HTMLElement {
  connectedCallback() {
    console.log("CChild connectedCallback: isConnected =", this.isConnected);
  }
}
customElements.define("c-child", CChild);

const parent = new CParent(),
      child = new CChild();
parent.append(child);
document.body.append(parent);

// Logs:
// CChild connectedCallback: isConnected = false

4.13.3 コアコンセプト

カスタム要素は、カスタムである要素となる。非公式には、そのコンストラクターおよびプロトタイプが、ユーザーエージェントによってではなく、著者によって定義されていることを意味する。この著者が提供するコンストラクター関数をカスタム要素コンストラクターと呼ぶ。

2つの異なるタイプのカスタム要素を定義できる:

Global_attributes/is

Firefox63+SafariNoChrome67+
Opera55+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android63+Safari iOSNoChrome Android67+WebView Android67+Samsung Internet9.0+Opera Android48+
  1. 自律カスタム要素。これは、extendsオプションなしで定義されている。 これらのタイプのカスタム要素は、定義された名前と同じローカル名を持つ。

  2. カスタマイズされた組み込み要素。これは、extendsオプションで定義されている。これらのタイプのカスタム要素は、extendsオプションで渡される値と同じローカル名を持ち、定義された名前is属性の値として使用され、したがってこれは妥当なカスタム要素名でなければならない。

カスタム要素作成された後、is属性の値を変更しても要素の動作は変更されない。

自律カスタム要素は、以下の要素定義を持つ:

カテゴリー
フローコンテンツ
フレージングコンテンツ
パルパブルコンテンツ
フォームに関連付けられたカスタム要素の場合:記載ラベル付け可能送信可能リセット可能フォームに関連付けられた要素
この要素を使用できるコンテキスト
フレージングコンテンツが期待される場所。
コンテンツモデル
透過的
コンテンツ属性
グローバル属性is属性を除く
formフォームに関連付けられたカスタム要素の場合 — 要素をform要素に関連付ける
disabledフォームに関連付けられたカスタム要素の場合 — フォームコントロールが無効かどうか
readonlyフォームに関連付けられたカスタム要素の場合 — willValidateに影響し、カスタム要素の著者によって追加されたすべての動作
nameフォームに関連付けられたカスタム要素の場合 — フォームの送信およびform.elementsに使用する要素の名前
名前空間を持たないその他の属性(文参照)。
アクセシビリティの考慮
フォームに関連付けられたカスタム要素の場合:著者向け 実装者向け
そうでなければ:著者向け実装者向け
DOMインターフェイス
要素の著者によって提供される(HTMLElementから継承)

自律カスタム要素は特別な意味を持たない:その要素の子を表すカスタマイズされた組み込み要素は、それが拡張した要素のセマンティクスを継承する。

要素の著者によって決定された、要素の機能に関連する名前空間なしの属性は、属性名がXML互換、かつASCII大文字を含まない限り、自律カスタム要素上で指定してもよい。例外はis属性であり、これは自律カスタム要素に指定してはならない(かつ指定しても何の効果もない)。

カスタマイズされた組み込み要素は、それらが拡張する要素に基づいて、属性に関する通常の要件に従う。カスタム属性ベースの動作を追加するには、data-*属性を使用する。


フォーム関連フィールドがtrueに設定されているカスタム要素定義に要素が関連付けられている場合、自律カスタム要素フォームに関連付けられたカスタム要素と呼ばれる。

name属性は、フォームに関連付けられたカスタム要素の名前を表す。disabled属性は、フォームに関連付けられたカスタム要素を非対話的にし、その送信値が送信されないようにするために使用される。form属性は、フォームに関連付けられたカスタム要素をそのフォーム所有者に明示的に関連付けるために使用される。

フォームに関連付けられたカスタム要素readonly属性は、要素が制約検証から除外されることを指定する。ユーザーエージェントはこの属性のための他の動作を提供しないが、カスタム要素の著者は、可能であれば、組み込みフォームコントロール上のreadonly属性の動作と同様に、何らかの適切な方法でコントロールを編集不能にするために、その存在を使用すべきである。

制約検証フォームに関連付けられたカスタム要素readonly属性が指定されている場合、その要素は制約検証から除外される

フォームに関連付けられたカスタム要素リセットアルゴリズムは、要素、コールバック名"formResetCallback"、および空の引数リストをもつカスタム要素のコールバック反応をキューに加えることである。


妥当なカスタム要素名は、次のすべての要件を満たす一連の文字である:

これらの要件により、妥当なカスタム要素名の多数の目標が保証される。

これらの制限とは別に、<math-α><emotion-😍>などのユースケースに最大源の柔軟性を与えるために、さまざまな名前が許可されている。

4.13.4 CustomElementRegistryインターフェイス

カスタム要素コンストラクターHTMLElementインターフェイスを継承しており、Windowオブジェクトごとに正確に1 つのHTMLElementインターフェイスが存在するため、カスタム要素レジストリはDocument オブジェクトの代わりに、Windowオブジェクトに関連付けられる。

window . customElements . define(name, constructor)

CustomElementRegistry/define

Support in all current engines.

Firefox63+Safari10.1+Chrome66+
Opera53+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android63+Safari iOS10.3+Chrome Android66+WebView Android66+Samsung Internet9.0+Opera Android47+
指定された名前を指定されたコンストラクターに自律カスタム要素としてマッピングする、新しいカスタム要素を定義する。
window . customElements . define(name, constructor, { extends: baseLocalName })
指定された名前を指定されたコンストラクターに、提供されたbaseLocalNameで識別される要素タイプカスタマイズされた組み込み要素としてマッピングする、新しいカスタム要素を定義する。カスタム要素または不明な要素を拡張しようとすると、"NotSupportedError" DOMExceptionが投げられる。
window . customElements . get(name)

CustomElementRegistry/get

Support in all current engines.

Firefox63+Safari10.1+Chrome66+
Opera53+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android63+Safari iOS10.3+Chrome Android66+WebView Android66+Samsung Internet9.0+Opera Android47+
指定された名前に対して定義されたカスタム要素コンストラクターを回収する。指定された名前カスタム要素定義がない場合、undefinedを返す。
window . customElements . whenDefined(name)

CustomElementRegistry/whenDefined

Support in all current engines.

Firefox63+Safari10.1+Chrome66+
Opera53+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android63+Safari iOS10.3+Chrome Android66+WebView Android66+Samsung Internet9.0+Opera Android47+
カスタム要素が指定された名前で定義されたときにカスタム要素のコンストラクターで満たされるプロミスを返す。 (そのようなカスタム要素がすでに定義されている場合、返されたプロミスはすぐに満たされる。)妥当なカスタム要素名が指定されない場合、 "SyntaxError" DOMExceptionで拒否されたプロミスを返す。
window . customElements . upgrade(root)

CustomElementRegistry/upgrade

Firefox63+Safari?Chrome68+
Opera55+Edge79+
Edge (Legacy)NoInternet ExplorerNo
Firefox Android63+Safari iOS?Chrome Android68+WebView Android68+Samsung Internet10.0+Opera Android48+
たとえ接続されていないとしても、ルートシャドウを含むすべての子孫要素をアップグレードしようとする

要素定義は、CustomElementRegistryカスタム要素定義を追加するプロセスである。 これは、define()メソッドによって実現される。

whenDefined()メソッドを使用して、すべての適切なカスタム要素定義されるまで、アクションを実行しないようにすることができる。この例において、使用する自律カスタム要素のすべてが定義されるまで、動的に読み込まれる記事のコンテンツを非表示するために、それを:defined疑似クラスと組み合わる。

articleContainer.hidden = true;

fetch(articleURL)
  .then(response => response.text())
  .then(text => {
    articleContainer.innerHTML = text;

    return Promise.all(
      [...articleContainer.querySelectorAll(":not(:defined)")]
        .map(el => customElements.whenDefined(el.localName))
    );
  })
  .then(() => {
    articleContainer.hidden = false;
  });

upgrade()メソッドは、自由に要素をアップグレード可能にする。 通常、要素は接続されたときに自動的にアップグレードされるが、この方法は、要素を接続する準備ができる前にアップグレードする必要がある場合に使用できる。

const el = document.createElement("spider-man");

class SpiderMan extends HTMLElement {}
customElements.define("spider-man", SpiderMan);

console.assert(!(el instanceof SpiderMan)); // not yet upgraded

customElements.upgrade(el);
console.assert(el instanceof SpiderMan);    // upgraded!

4.13.5 カスタム要素応答

カスタム要素は、著者によるコードを実行することで特定の発生に応答する機能をがある:

これらの反応をまとめてカスタム要素応答と呼ぶ。

カスタム要素反応が呼び出される方法は、デリケートな操作の途中で著者のコードが実行されるのを避けるために、特別な注意を払って行われる。実質的に、"ユーザースクリプトに戻る直前"まで遅延される。これは、ほとんどの目的では同期して実行されているように見えるが、複雑な複合操作(クローニング範囲操作など)の場合は、すべての関連するユーザーエージェントの処理ステップが完了するまで遅延され、その後、バッチとしてまとめて実行されることを意味する。

カスタム要素反応は常に、少なくとも1つのカスタム要素のローカルコンテキスト内で、トリガーアクションと同じ順序で呼び出されることが保証されている。(カスタム要素反応コードは独自の変更を実行できるため、複数の要素にまたがるグローバルな順序付けを保証することはできない。)

4.13.6 要素内部

特定の機能は、カスタム要素の作成者が利用可能であることを意図されているが、カスタム要素の利用者は意図されていない。これらは、element.attachInternals()メソッドによって提供され、ElementInternalsのインスタンスを返す。ElementInternalsのプロパティおよびメソッドは、ユーザーエージェントがすべての要素に提供する内部機能の制御を可能にする。

element . attachInternals()

カスタム要素elementをターゲットとするElementInternalsオブジェクトを返す。elementカスタム要素でない場合、"internals"機能が要素定義の一部として無効にされた場合、または同じ要素で2回呼び出された場合、例外を投げる。

4.13.6.1 シャドウルートアクセス
internals . shadowRoot

ターゲット要素シャドウホストである場合、 internalsターゲット要素ShadowRootを返し、そうでなければnullを返す。

4.13.6.2 フォームに関連付けられたカスタム要素
internals . setFormValue(value)

internalsターゲット要素状態送信値の両方をvalueに設定する。

valueがnullである場合、要素はフォームの送信に参加しない。

internals . setFormValue(value, state)

internalsターゲット要素送信値valueに設定し、その状態stateに設定する。

valueがnullである場合、要素はフォームの送信に参加しない。

internals . form

internalsターゲット要素フォーム所有者を返す。

internals . setValidity(flags, message [, anchor ])

internalsターゲット要素flags引数で示された制約の影響を受けるものとしてマークし、要素の検証メッセージをmessageに設定する。anchorが指定される場合、ユーザーエージェントは、フォームの所有者がインタラクティブに検証される、またはreportValidity()が呼び出されたときに、internalsターゲット要素の制約に関する問題を示すために使用することがある。

internals . setValidity({})

internalsターゲット要素その制約を満たすものとしてマークする。

internals . willValidate

フォームの送信時にinternalsターゲット要素が検証される場合はtrueを返す。そうでなけれればfalseを返す。

internals . validity

internalsターゲット要素ValidityStateオブジェクトを返す。

internals . validationMessage

もしinternalsターゲット要素の妥当性をチェックしたならば、ユーザーに表示されるエラーメッセージを返すだろう。

valid = internals . checkValidity()

internalsターゲット要素に妥当性の問題がない場合はtrueを返す。 そうでなければfalseを返す。 後者の場合要素でinvalidイベントを発火する。

valid = internals . reportValidity()

internalsターゲット要素が一切妥当性の問題を持たない場合はtrueを返す。そうでなければfalseを返し、要素でinvalidイベントを発火させ、そして(イベントが中止されない場合)ユーザーに問題を報告する。

internals . labels

internalsターゲット要素が関連付けられているすべてのlabel 要素のNodeListを返す。

それぞれのフォームに関連付けられたカスタム要素送信値を持つ。フォーム送信時に1つ以上のエントリーを提供するために使用される。送信値の初期値はnullであり、送信値はnull、文字列、File、またはエントリーリストにすることができる。

それぞれのフォームに関連付けられたカスタム要素状態を持つ。これは、ユーザーエージェントが要素に対するユーザーの入力を復元できる情報である。状態の初期値はnullであり、状態はnull、文字列、File,、またはエントリーリストにすることができる。

カスタム要素の著者はsetFormValue()メソッドを使用して要素の送信値状態を設定し、これらをユーザーエージェントに伝達する。

ユーザーエージェントが、たとえばナビゲーションやユーザーエージェントの再起動後など、フォームに関連付けられたカスタム要素状態を復元するのがよいと考えている場合、その要素、コールバック名"formStateRestoreCallback"、復元する状態を含む引数リスト、および"restore"をもつカスタム要素のコールバック反応をエンキューしてもよい。

ユーザーエージェントがフォーム記入アシスト機能を持っている場合、その機能が呼び出されたときに、フォームに関連付けられたカスタム要素、コールバック名"formStateRestoreCallback"、状態値の履歴といくつかのヒューリスティックによって決定された状態値を含む引数リスト、および"autocomplete"とともにフォームに関連付けられたカスタム要素のコールバック反応をエンキューしてもよい。

一般に、状態はユーザーによって指定された情報であり、送信値はサーバーへの送信に適した、正規化またはサニタイズ後の値である。 次の例は、これを具体的に示している:

ユーザーに日付の指定を求めるフォームに関連付けられたカスタム要素があるとする。 ユーザーは"3/15/2019"を指定するが、コントロールはサーバーに"2019-03-15"を送信しようとする。"3/15/2019"は要素の状態であり、"2019-03-15"送信値である。

既存のチェックボックスinputタイプの動作をエミュレートするカスタム要素を開発するとする。 その送信値は、そのvalueコンテンツ属性の値、または文字列"on"になる。その状態は、"checked""unchecked""checked/indeterminate"、または"unchecked/indeterminate"のいずれかになる。

4.13.6.3 アクセシビリティセマンティックス
internals . role [ = value ]

internalsターゲット要素のデフォルトのARIAロールを設定または取得する。これは、ページの著者がrole属性を使用して上書きしない限り、使用される。

internals . aria* [ = value ]

internalsターゲット要素のさまざまなデフォルトのARIAステートまたはプロパティを設定または取得する。これは、ページの著者がaria-*属性を使用してそれらを上書きしない限り、使用される。

ElementInternalsroleおよびaria*プロパティを使用することで、カスタム要素の著者は、ネイティヴ要素がどのように振る舞うかに類似の、カスタム要素にデフォルトのアクセシブルなロール、ステート、およびプロパティ値を設定することができる。詳細は上記の例を参照のこと。