Element: attachShadow() Methode

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.

Die Element.attachShadow() Methode fügt einem bestimmten Element einen Shadow-DOM-Baum hinzu und gibt eine Referenz auf dessen ShadowRoot zurück.

Elemente, an die Sie einen Shadow anhängen können

Beachten Sie, dass Sie nicht an jeden Elementtyp eine Shadow-Root anhängen können. Es gibt einige, die aus Sicherheitsgründen keinen Shadow-DOM haben können (zum Beispiel <a>).

Folgende Liste zeigt Elemente, an die Sie einen Shadow-Root anhängen können:

Aufruf dieser Methode bei einem Element, das bereits einen Shadow-Host hat

Die Methode kann auf einem Element aufgerufen werden, das bereits eine deklarative Shadow-Root hat, vorausgesetzt, der angegebene Modus mode entspricht dem vorhandenen Modus. In diesem Fall wird die bereits vorhandene ShadowRoot gelöscht und zurückgegeben. Dies ermöglicht Fälle, in denen beispielsweise serverseitiges Rendering bereits deklarativ eine Shadow-Root erstellt hat und dann clientseitiger Code versucht, die Root erneut anzuhängen.

Andernfalls führt der Aufruf von attachShadow() bei einem Element, das bereits eine Shadow-Root hat, zu einer Ausnahme.

Syntax

js
attachShadow(options)

Parameter

options

Ein Objekt, das die folgenden Felder enthält:

mode

Ein String, der den Kapselungsmodus für den Shadow-DOM-Baum angibt. Dieser kann einer der folgenden sein:

open

Elemente der Shadow-Root sind mit JavaScript außerhalb der Root zugänglich, zum Beispiel mit Element.shadowRoot:

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

Verweigert den Zugriff auf die Knoten einer geschlossenen Shadow-Root von JavaScript außerhalb:

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

Ein Boolean, der angibt, ob die Shadow-Root klonbar ist: Wenn auf true gesetzt, wird der Shadow-Host, der mit Node.cloneNode() oder Document.importNode() geklont wurde, die Shadow-Root in der Kopie enthalten. Der Standardwert ist false.

delegatesFocus Optional

Ein Boolean, der, wenn auf true gesetzt, ein Verhalten spezifiziert, das Probleme von benutzerdefinierten Elementen in Bezug auf Fokusierbarkeit mindert. Wenn ein nicht fokussierbarer Teil des Shadow-DOMs angeklickt wird, erhält der erste fokussierbare Teil den Fokus, und der Shadow-Host erhält alle verfügbaren :focus Stile. Der Standardwert ist false.

serializable Optional

Ein Boolean, der, wenn auf true gesetzt, anzeigt, dass die Shadow-Root serialisierbar ist. Wenn gesetzt, kann die Shadow-Root serialisiert werden, indem die Methoden Element.getHTML() oder ShadowRoot.getHTML() mit dem Parameter options.serializableShadowRoots auf true aufgerufen werden. Der Standardwert ist false.

slotAssignment Optional

Ein String, der den Slot-Zuweisungsmodus für den Shadow-DOM-Baum angibt. Dieser kann sein:

named

Elemente werden automatisch <slot> Elementen innerhalb dieser Shadow-Root zugewiesen. Alle Nachkommen des Hosts mit einem slot Attribut, das zum name Attribut eines <slot> innerhalb dieser Shadow-Root passt, werden diesem Slot zugewiesen. Alle obersten Kinder des Hosts ohne slot Attribut werden einem <slot> ohne name Attribut zugewiesen (der "Standard-Slot"), wenn einer vorhanden ist.

manual

Elemente werden nicht automatisch <slot> Elementen zugewiesen. Stattdessen müssen sie manuell mit HTMLSlotElement.assign() zugewiesen werden. Der Standardwert ist named.

Rückgabewert

Gibt ein ShadowRoot Objekt zurück.

Ausnahmen

NotSupportedError DOMException

Dieser Fehler kann auftreten, wenn Sie versuchen, eine Shadow-Root an ein Element anzuhängen:

  • außerhalb des HTML-Namespace oder das keinen Shadow angehängt bekommen kann.
  • bei dem die statische Eigenschaft disabledFeatures des Element-Definitionswerts den Wert "shadow" erhalten hat.
  • das bereits eine Shadow-Root besitzt, die nicht deklarativ erstellt wurde.
  • das eine deklarative Shadow-Root hat, aber der angegebene mode nicht mit dem vorhandenen Modus übereinstimmt.

Beispiele

Wortzählungs-Komponente

Das folgende Beispiel stammt aus unserem word-count-web-component Demo (sehen Sie es live auch). Sie können sehen, dass wir attachShadow() in der Mitte des Codes verwenden, um eine Shadow-Root zu erstellen, an die wir dann die Inhalte unseres benutzerdefinierten Elements anhängen.

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

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

Deaktivierung des Shadow-DOMs

Wenn das Element eine statische Eigenschaft namens disabledFeatures hat, die ein Array enthält, das den String "shadow" beinhaltet, dann wird der Aufruf von attachShadow() eine Ausnahme werfen.

Zum Beispiel:

js
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);

Spezifikationen

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

Browser-Kompatibilität

Siehe auch