Метод элемента: attachShadow()

Базовая реализация Широко доступна

Эта функция хорошо отработана и работает на многих устройствах и версиях браузеров. Она доступна в браузерах с января 2020 года.

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

Элементы, к которым можно прикрепить тень

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

Ниже приведен список элементов, к которым можно прикрепить корень тени:

Любой автономный пользовательский элемент с валидным именем
<article>
<aside>
<blockquote>
<body>
<div>
<footer>
h1
h2
h3
h4
h5
h6
<header>
<main>
<nav>
<p>
<section>
<span>

Вызов этого метода для элемента, который уже является узлом тени

Метод может быть вызван для элемента, который уже имеет декларативный корень тени, при условии, что указанный режим mode совпадает с существующим режимом. В этом случае ShadowRoot, который уже присутствовал, будет очищен и возвращён. Это позволяет в случаях, когда, например, серверная отрисовка уже декларативно создала корень тени, а затем клиентский код пытается снова прикрепить корень.

В противном случае вызов attachShadow() для элемента, который уже имеет корень тени, вызовет исключение.

Синтаксис

attachShadow(options)

Параметры

options

Объект, содержащий следующие поля:

mode

Строка, определяющая режим инкапсуляции для дерева тени DOM. Может принимать одно из следующих значений:

open

Элементы корня тени доступны из JavaScript вне корня, например, с помощью Element.shadowRoot:

element.attachShadow({ mode: "open" });
element.shadowRoot; // Returns a ShadowRoot obj

closed

Запрещает доступ к узлам закрытого корня тени из JavaScript вне него:

element.attachShadow({ mode: "closed" });
element.shadowRoot; // Returns null

clonable Необязательно

Булево значение, определяющее, можно ли клонировать корень тени: при установке в значение true, клонированный узел тени вместе с узлом-хостом с помощью Node.cloneNode() или Document.importNode() будет включен в копию. По умолчанию значение false.

delegatesFocus Необязательно

Булево значение, которое, когда установлено в true, определяет поведение, смягчающее проблемы с фокусировкой пользовательских элементов. При нажатии на нефокусируемую часть тени DOM, фокус переключается на первую фокусируемую часть, а узлу-хосту предоставляются все доступные :focus стили. По умолчанию значение false.

serializable Необязательно

Булево значение, которое, при установке в значение true, указывает, что корень тени сериализуем. При установке, корень тени может быть сериализован вызовом методов Element.getHTML() или ShadowRoot.getHTML() с параметром options.serializableShadowRoots установленным в значение true. По умолчанию значение false.

slotAssignment Необязательно

Строка, определяющая режим назначения слотов для дерева тени DOM. Может принимать одно из следующих значений:

named: Элементы автоматически назначаются элементам <slot> внутри этого корня тени. Любые потомки узла-хоста с атрибутом slot , соответствующим атрибуту name элемента <slot> внутри этого корня тени, будут назначены этому слоту. Любые дочерние элементы узла-хоста без атрибута slot будут назначены элементу <slot> без атрибута name (слот по умолчанию), если такой элемент присутствует.
manual: Элементы не назначаются автоматически элементам <slot>. Вместо этого их необходимо вручную назначить с помощью HTMLSlotElement.assign(). По умолчанию значение named.

Возвращаемое значение

Возвращает объект ShadowRoot.

Исключения

NotSupportedError DOMException

Это исключение может быть выброшено при попытке прикрепить корень тени к элементу:

вне пространства имён HTML или к элементу, к которому нельзя прикрепить тень.
если статическому свойству элемента disabledFeatures задано значение "shadow".
если элемент уже имеет корень тени, который не был создан декларативно.
если элемент имеет декларативный корень тени, но указанный mode не соответствует существующему режиму.

Примеры

Пример пользовательского элемента подсчёта слов

Следующий пример взят из нашего примера пользовательского элемента подсчёта слов (посмотреть в действии). Вы можете увидеть, что мы используем attachShadow() в середине кода для создания корня тени, к которому затем мы прикрепляем содержимое нашего пользовательского элемента.

// 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
    this.parentNode.addEventListener("input", () => {
      text.textContent = `Words: ${countWords(wcParent)}`;
    });
  }
}

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

Отключение тени DOM

Если у элемента есть статическое свойство с именем disabledFeatures, которое является массивом, содержащим строку "shadow", то вызов attachShadow() выбросит исключение.

Например:

class MyCustomElement extends HTMLElement {
  // Disable shadow DOM for this element.
  static disabledFeatures = ["shadow"];

  constructor() {
    super();
  }

  connectedCallback() {
    // Create a shadow root.
    // This will throw an exception.
    const shadow = this.attachShadow({ mode: "open" });
  }
}

// Define the new element
customElements.define("my-custom-element", MyCustomElement);

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

Спецификация
DOM # ref-for-dom-element-attachshadow①

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

	Рабочий стол					Мобильный
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на IOS	Samsung Internet	WebView Android
`attachShadow`	53	79	63	40	10	53	63	41	10	6.0	53
`options_clonable_parameter`	124	124	123	110	17.416.4	124	123	82	17.416.4	27.0	124
`options_delegatesFocus_parameter`	53	79	94	40	13.1	53	94	41	13.4	6.0	53
`options_serializable_parameter`	125	125	Нет	111	Нет	125	Нет	83	Нет	27.0	125

См. также

ShadowRoot.mode
ShadowRoot.delegatesFocus
ShadowRoot.slotAssignment
Деликатное прикрепление тенистого корня с помощью атрибута shadowrootmode элемента <template>
Деликатное тенистое DOM на web.dev (2023)

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow