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.

* Some parts of this feature may have varying levels of support.

Экспериментальная возможность: Это экспериментальная технология
Так как спецификация этой технологии ещё не стабилизировалась, смотрите таблицу совместимости по поводу использования в различных браузерах. Также заметьте, что синтаксис и поведение экспериментальной технологии может измениться в будущих версиях браузеров, вслед за изменениями спецификации.

Метод Element.attachShadow() добавляет теневое DOM дерево к указанному элементу и возвращает ссылку на его ShadowRoot (корневой элемент созданного дерева).

Элементы которые можно добавить в теневой DOM

Обратите внимание, что не каждый элемент можно добавить в корень теневого дерева. Некоторые типы исключены по соображениям безопасности(например <a>), и некоторые другие. Вот список разрешённых элементов:

Синтаксис

var shadowroot = element.attachShadow(shadowRootInit);

Параметры

shadowRootInit

ShadowRootInit содержит следующие поля:

mode: Строка указывающая на режим инкапсуляции для shadowDOM:

  • open. Указывает на открытие режима инкапсуляции. Это означает что элементы shadowRoot доступны для внешнего мира element.shadowRoot

    element.shadowRoot === shadowroot; // returns true
    
  • closed. Указывает на закрытие режима инкапсуляции. Этот режим запрещает доступ к узлам node(s) и закрывать теневой корень для внешнего мира

    element.shadowRoot === shadowroot; // returns false
    element.shadowRoot === null; // returns true
    

Возвращает

Вернёт a ShadowRoot или null.

Исключения

Исключение Описание
InvalidStateError Элемент уже является хостом теневого DOM
NotSupportedError Вы пытаетесь прикрепить shadow DOM к HTML-элементу с некорректным именем, или к запрещённому элементу. (см. выше)

Примеры

Пример взят из демо компонента word-count-web-component, так-же доступно live demo. Вы можете найти метод attachShadow() примерно в середине кода. Метод создаёт корневой элемент теневого DOM к которому потом добавляется содержимое шаблона элемента.

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

Спецификации

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

Совместимость с браузерами

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
attachShadow
options.clonable parameter
options.delegatesFocus parameter
options.serializable parameter
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Uses a non-standard name.
Has more compatibility info.