ShadowRoot

Baseline

広く利用可能

この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2020年1月以降、すべてのブラウザーで利用可能です。

* この機能の一部は、対応レベルにばらつきがある場合があります。

完全な互換性情報を見る
もっと詳しく

ShadowRoot はシャドウ DOM API のインターフェイスで、文書のメイン DOM ツリーとは別にレンダリングされる DOM サブツリーのルートノードです。

要素のシャドウルートへの参照は Element.shadowRoot プロパティで受け取ることができます。これは Element.attachShadow() で mode オプションが open に設定されて作成されたときに提供されます。

インスタンスプロパティ

ShadowRoot.activeElement 読取専用: フォーカスを持っているシャドウツリー内の Element を返します。
ShadowRoot.adoptedStyleSheets: シャドウ DOM のサブツリーで使用するために構築されたスタイルシートの配列を追加します。これらは、同じ親 Document ノードを共有する他の DOM サブツリーや、文書自身と共有されることがあります。
ShadowRoot.clonable 読取専用: 論理値で、シャドウルートがクローン可能であるかどうかを示します。
ShadowRoot.customElementRegistry 読取専用: このシャドウルートに関連付けられた CustomElementRegistry オブジェクトを返します。設定されていない場合は null を返します。
ShadowRoot.delegatesFocus 読取専用: 論理値で、フォーカスできないノードが選択された場合に、シャドウルートがフォーカスを譲るかどうかを示します。
ShadowRoot.fullscreenElement 読取専用: このシャドウツリーで現在全画面表示になっている要素です。
ShadowRoot.host 読取専用: ShadowRoot が取り付けられた DOM 要素への参照を返します。
ShadowRoot.innerHTML: ShadowRoot 内の DOM ツリーを設定または返します。
ShadowRoot.mode 読取専用: ShadowRoot のモードで open または closed の値を取ります。これはシャドウルートの内部の機能に JavaScript からアクセスできるかどうかを定義します。
ShadowRoot.pictureInPictureElement 読取専用: シャドウツリー内で現在ピクチャインピクチャモードで表示されている Element を返します。
ShadowRoot.pointerLockElement 読取専用: ポインターがロックされている間、マウスイベントのターゲットとして設定されている Element を返します。ロックが保留中か、ポインターがロックされていないか、ターゲットがほかのツリーにある場合は null を返します。
ShadowRoot.referenceTarget: シャドウホストをホスト要素の外部から参照したときの、参照の実効的な対象を示す null 許容の文字列です。この値には、シャドウ DOM 内の要素の ID を指定します。設定すると、シャドウ DOM の外部からホスト要素を参照したとき、その参照の実効的な対象が指定した要素になります。
ShadowRoot.serializable 読取専用: 論理値で、シャドウルートがシリアライズ可能かどうかを示します。要素内のシリアライズ可能なシャドウルートは、options.serializableShadowRoots 引数が true に設定されている場合、Element.getHTML() または ShadowRoot.getHTML() によってシリアライズされます。これは、シャドウルートが作成される際に設定されます。
ShadowRoot.slotAssignment 読取専用: スロット割り当ての型（manual または named）を持つ文字列を返します。
ShadowRoot.styleSheets 読取専用: シャドウツリーに明示的にリンクされている、または埋め込まれている CSSStyleSheet オブジェクトの StyleSheetList を返します。

インスタンスメソッド

ShadowRoot.getAnimations(): 現在有効なすべての Animation オブジェクトのうち、ターゲット要素がシャドウツリーの子孫であるものの配列を返します。
ShadowRoot.getSelection(): ユーザーによって選択されたテキストの範囲または現在のキャレットの位置を表現する Selection オブジェクトを返します。
ShadowRoot.elementFromPoint(): 指定された座標における最上位の要素を返します。
ShadowRoot.elementsFromPoint(): 指定された座標における全要素からなる配列を返します。
ShadowRoot.setHTML(): HTML 文字列を構文解析・無害化して DocumentFragment に変換し、それをシャドウ DOM 内の既存のツリーと置き換える、XSS 対策済みの安全な方法を提供します。
ShadowRoot.setHTMLUnsafe(): HTML 文字列を無害化せずに文書フラグメントとして構文解析し、シャドウルートに元から存在するサブツリーと置き換えます。HTML 文字列には宣言型シャドウルートを含めることができます。これは、ShadowRoot.innerHTML を使用して HTML を設定した場合と同様に、テンプレート要素として構文解析されます。

イベント

以下のイベントは HTMLSlotElement からのイベントバブリングによって ShadowRoot で利用できます。

HTMLSlotElement slotchange event: そのスロットに含まれるノードが変更されたときに発行されるイベント。

例

以下のコードは、要素の属性で指定されたサイズと色の四角形を表示する life-cycle-callbacks の例から抜粋したものです（ライブデモも確認してください）。

<custom-square> 要素のクラス定義には、外部関数 updateStyle() を呼び出すライフサイクルコールバックが含まれています。この関数が要素にサイズと色を適用します。引数として this（カスタム要素自身）を渡していることが分かります。

class Square extends HTMLElement {
  // …
  connectedCallback() {
    console.log("四角形のカスタム要素がページに追加されました。");
    updateStyle(this);
  }

  attributeChangedCallback(name, oldValue, newValue) {
    console.log("四角形のカスタム要素の属性が変更されました。");
    updateStyle(this);
  }
  // …
}

updateStyle() 関数内では、Element.shadowRoot を使用してシャドウ DOM への参照を取得します。標準的な DOM の探索手法でシャドウ DOM 内の <style> 要素を見つけ、その中の CSS を更新します。

function updateStyle(elem) {
  const shadow = elem.shadowRoot;
  const childNodes = shadow.childNodes;
  for (const node of childNodes) {
    if (node.nodeName === "STYLE") {
      node.textContent = `
div {
  width: ${elem.getAttribute("l")}px;
  height: ${elem.getAttribute("l")}px;
  background-color: ${elem.getAttribute("c")};
}
      `;
    }
  }
}