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.

Die Element.attachShadow() Methode fügt einem angegebenen 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 ein Shadow-Root anhängen können. Einige können aus Sicherheitsgründen keinen Shadow-DOM haben (zum Beispiel <a>).

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

Aufruf dieser Methode bei einem Element, das bereits ein Shadow-Host ist

Die Methode kann auf ein Element angewendet werden, das bereits über einen deklarativen Shadow Root verfügt, sofern der angegebene mode mit dem vorhandenen Modus übereinstimmt. In diesem Fall wird der bereits vorhandene ShadowRoot gelöscht und zurückgegeben. Dies ermöglicht Fälle, bei denen beispielsweise das serverseitige Rendering bereits deklarativ einen Shadow-Root erstellt hat und dann Client-Code versucht, den Root erneut anzuhängen.

Andernfalls wird ein Fehler ausgelöst, wenn attachShadow() auf ein Element aufgerufen wird, das bereits ein Shadow-Root hat.

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. Dies kann einer der folgenden sein:

open

Elemente des Shadow-Roots sind von außerhalb des Roots über JavaScript 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 eines geschlossenen Shadow-Roots von außerhalb desselben:

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

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

delegatesFocus Optional

Ein Boolean, der bei Einstellung auf true ein Verhalten angibt, das Probleme mit der Fokussierbarkeit von benutzerdefinierten Elementen mindert. Wenn ein nicht fokussierbarer Teil des Shadow-DOM angeklickt wird, erhält der erste fokussierbare Teil den Fokus, und der Shadow-Host erhält alle verfügbaren :focus-Styling. Der Standardwert ist false.

serializable Optional

Ein Boolean, der bei Einstellung auf true angibt, dass der Shadow-Root serialisierbar ist. Wenn eingestellt, kann der Shadow-Root durch Aufrufen der Methoden Element.getHTML() oder ShadowRoot.getHTML() mit dem Parameter options.serializableShadowRoots auf true serialisiert werden. Der Standardwert ist false.

slotAssignment Optional

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

named

Elemente werden automatisch den <slot>-Elementen innerhalb dieses Shadow-Roots zugewiesen. Alle Nachkommen des Hosts mit einem slot-Attribut, das mit dem name-Attribut eines <slot> innerhalb dieses Shadow-Roots übereinstimmt, werden diesem Slot zugewiesen. Alle obersten Kinder des Hosts ohne slot-Attribut werden einem <slot> ohne name-Attribut (dem "Standard-Slot") zugewiesen, sofern ein solcher vorhanden ist.

manual

Elemente werden nicht automatisch den <slot>-Elementen zugewiesen. Sie müssen stattdessen manuell mit HTMLSlotElement.assign() zugewiesen werden. Der Standardwert ist named.

Rückgabewert

Gibt ein ShadowRoot-Objekt zurück.

Ausnahmen

NotSupportedError DOMException

Dieser Fehler kann ausgelöst werden, wenn Sie versuchen, einem Element einen Shadow-Root anzuhängen:

  • außerhalb des HTML-Namespace oder einem, das nicht mit einem Shadow versehen werden kann.
  • bei dem die statische Eigenschaft disabledFeatures des Elementdefinitionsobjekts auf den Wert "shadow" gesetzt wurde.
  • das bereits über einen Shadow-Root verfügt, der nicht deklarativ erstellt wurde.
  • das über einen deklarativen Shadow Root verfügt, aber der angegebene mode nicht mit dem vorhandenen Modus übereinstimmt.

Beispiele

Benutzerdefiniertes Element zur Wortzählung

Das folgende Beispiel stammt aus unserem word-count-web-component Demo (siehe es live auch). Sie können sehen, dass wir attachShadow() in der Mitte des Codes verwenden, um einen Shadow-Root zu erstellen, an dem wir dann den Inhalt 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" });

Deaktivieren des Shadow-DOM

Wenn das Element eine statische Eigenschaft namens disabledFeatures hat, die ein Array mit dem String "shadow" enthält, dann wird der attachShadow()-Aufruf eine Ausnahme auslösen.

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 Standard
# ref-for-dom-element-attachshadow①

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch