Element: attachShadow() メソッド
============================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

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

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

シャドウルートはすべての要素に追加できるわけではありません。セキュリティ上の理由でシャドウ DOM を持てないものもあります（`<a>` など）。

以下にシャドウルートを追加**できる**要素を列挙します。

* 任意の自律カスタム要素で有効な名前を持つもの
* `<article>`
* `<aside>`
* `<blockquote>`
* `<body>`
* `<div>`
* `<footer>`
* h1
* h2
* h3
* h4
* h5
* h6
* `<header>`
* `<main>`
* `<nav>`
* `<p>`
* `<section>`
* `<span>`
構文
--


```js
attachShadow(options)
```

### 引数

`options`

以下のフィールドを含むオブジェクトです。

`mode`

 文字列で、シャドウ DOM ツリーの*カプセル化モード*を指定します。
 以下のいずれかをの値を取ります。


`open`

シャドウルートの要素には、例えば `Element.shadowRoot` を使用して、ルートの外部の JavaScript からアクセスできます。


```js
element.attachShadow({ mode: "open" });
element.shadowRoot; // ShadowRoot オブジェクトを返す
```


`closed`

閉じたシャドウルートに対する外部の JavaScript からのアクセスを拒否します。


```js
element.attachShadow({ mode: "closed" });
element.shadowRoot; // null を返す
```


`delegatesFocus` 省略可

論理値で、 `true` に設定された場合、フォーカス可能性に関するカスタム要素の問題を緩和します。シャドウ DOM のフォーカスができない部分がクリックされた場合、最初のフォーカス可能な部分がフォーカスを得て、シャドウホストは `:focus` のスタイルを利用することができます。既定値は `false` です。

`slotAssignment` 省略可

シャドウ DOM ツリーの *スロット割り当てモード* を指定します。これは以下のいずれかです。

`named`

要素は自動的にこのシャドウルート内の `<slot>` 要素に割り当てられます。このシャドウルート内の `<slot>` の `name` 属性と一致する `slot` 属性を持つホスティングの子孫は、そのスロットに割り当てられます。ホスティングの最上位の子で `slot` 属性を持たないものは、 `name` 属性を持たない `<slot>`（「既定のスロット」）が存在する場合、そのスロットに割り当てられます。

`manual`

 要素は自動的に `<slot>` 要素に割り当てることはできません。代わりに、`HTMLSlotElement.assign()` で手動で割り当てる必要があります。
 既定値は `named` です。



### 返値

`ShadowRoot` オブジェクトです。

### 例外

`InvalidStateError` `DOMException`

取り付けようとしている要素が既にシャドウホストである場合。

`NotSupportedError` `DOMException`

シャドウルートを HTML 名前空間外の要素に取り付けようとした場合、シャドウを取り付けられない要素であった場合、要素の定義で静的プロパティ `disabledFeatures` が `"shadow"` の値であった場合。

例
-

 以下の例は word-count-web-component のデモを使用しています(実行例)。
 コードの途中で `attachShadow()` を使ってシャドウルートを作成し、そこにカスタム要素の中身を取り付けているのがわかると思います。


```js
// 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
    const wcParent = this.parentNode;

    function countWords(node) {
      const text = node.innerText || node.textContent;
      return text
        .trim()
        .split(/\s+/g)
        .filter((a) => a.trim().length > 0).length;
    }

    const count = `Words: ${countWords(wcParent)}`;

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

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

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

    // Update count when element content changes
    setInterval(() => {
      const count = `Words: ${countWords(wcParent)}`;
      text.textContent = count;
    }, 200);
  }
}

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

仕様書
---

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-attachshadow① |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `ShadowRoot.mode`
* `ShadowRoot.delegatesFocus`
* `ShadowRoot.slotAssignment` (en-US)