Element.attachShadow()

Element.attachShadow() メソッドは、シャドウ DOM ツリーを特定の要素に追加し、そのシャドウルート (ShadowRoot) への参照を返します。

シャドウツリーを追加できる要素

シャドウルートは全ての要素に追加できるわけではありません。 (<a> など) セキュリティ上の理由でシャドウ DOM を持てないものもあります。以下にシャドウルートを追加できる要素を列挙します。

構文

var shadowroot = element.attachShadow(shadowRootInit);

引数

shadowRootInit
ShadowRootInit ディクショナリで、以下のプロパティを含みます。
mode

文字列で、シャドウ DOM ツリーのカプセル化モードを指定します。以下のうちの一つを取ります。

  • open: シャドウルートに外部の JavaScript からアクセスできます。例えば、 Element.shadowRoot を使ってアクセスできます。
    element.shadowRoot; // ShadowRoot オブジェクトを返します
  • closed: シャドウルートに外部の JavaScript からアクセスできません。
    element.shadowRoot; // null を返します
    
delegatesFocus
真偽値で、 true に設定された場合、フォーカス可能性に関するカスタム要素の問題を緩和します。シャドウ DOM のフォーカスができない部分がクリックされた場合、最初のフォーカス可能な部分がフォーカスを得て、シャドウホストは :focus のスタイルを利用することができます。

返値

ShadowRoot オブジェクトです。

例外

例外 説明
InvalidStateError shadow root を追加しようとしている要素は、すでに shadow host です。
NotSupportedError shadow root を追加しようとしている要素は、HTML の名前空間外であるか、shadow DOM を持てない要素です(上記の通り)。

以下の例は word-count-web-component のデモを使用しています(実行例)。 attachShadow() はコードの真ん中付近で shadow root を作るために使用されています。その後カスタム要素を追加しています。

// Create a class for the element
class WordCount extends HTMLParagraphElement {
  constructor() {
    // Always call super first in constructor
    super();

    // count words in element's parent element
    var wcParent = this.parentNode;

    function countWords(node){
      var text = node.innerText || node.textContent
      return text.split(/\s+/g).length;
    }

    var count = 'Words: ' + countWords(wcParent);

    // Create a shadow root
    var shadow = this.attachShadow({mode: 'open'});

    // Create text node and add word count to it
    var text = document.createElement('span');
    text.textContent = count;

    // Append it to the shadow root
    shadow.appendChild(text);

    // Update count when element content changes
    setInterval(function() {
      var count = 'Words: ' + countWords(wcParent);
      text.textContent = count;
    }, 200)
  }
}

// Define the new element
customElements.define('word-count', WordCount, { extends: 'p' });

仕様書

仕様書 状態 備考
DOM
attachShadow() の定義
現行の標準

ブラウザーの互換性

BCD tables only load in the browser