ShadowRoot

ShadowRoot はシャドウ DOM API のインターフェイスで、文書の DOM ツリーから分離してレンダリングされた部分ツリーのルートノードを指します。

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

インスタンスプロパティ

ShadowRoot.activeElement 読取専用

フォーカスを持っているシャドウツリー内の Element を返します。

ShadowRoot.adoptedStyleSheets

シャドウ DOM のサブツリーで使用するために構築されたスタイルシートの配列を追加します。 これらは、同じ親 Document ノードを共有する他の DOM サブツリーや、文書自身と共有されることがあります。

ShadowRoot.clonable 読取専用

論理値で、シャドウルートがクローン可能であるかどうかを示します。

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.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.setHTMLUnsafe()

HTML 文字列を、無害化せずに文書フラグメントとして解析し、シャドウルートに元から存在するサブツリーを置き換えます。HTML 文字列には宣言型のシャドウルートを記載することができます。これは、ShadowRoot.innerHTML を使用して設定された HTML のテンプレート要素として解釈されます。

イベント

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

HTMLSlotElement slotchange event

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

例

以下のコードは、サイズと色の属性が指定された四角形の要素を作る life-cycle-callbacks の例です。 (ライブでも確認)

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

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")};
}
 `;
 }
 }
}

仕様書

ブラウザーの互換性