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 zu dessen ShadowRoot zurück.

Elemente, an die Sie einen Schatten anfügen können

Beachten Sie, dass Sie nicht an jeden Elementtyp einen Schattenwurzel anfügen können. Aus Sicherheitsgründen können einige Elemente keinen Shadow-DOM haben (zum Beispiel <a>).

Die folgende Liste enthält Elemente, an die Sie eine Schattenwurzel anfügen können:

Aufruf dieser Methode bei einem Element, das bereits ein Schattengeber ist

Die Methode kann bei einem Element aufgerufen werden, das bereits über eine deklarative Schattenwurzel verfügt, vorausgesetzt, der angegebene Modus mode stimmt mit dem vorhandenen Modus überein. 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 Schattenwurzel erstellt hat und der clientseitige Code versucht, die Wurzel erneut anzufügen.

Andernfalls führt der Aufruf von attachShadow() bei einem Element, das bereits eine Schattenwurzel 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. Dies kann eines der folgenden sein:

open

Elemente der Schattenwurzel sind von JavaScript außerhalb der Wurzel zugänglich, zum Beispiel über Element.shadowRoot:

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

Verweigert den Zugriff auf die Knoten einer geschlossenen Schattenwurzel von JavaScript außerhalb:

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

Ein boolescher Wert, der angibt, ob die Schattenwurzel klonbar ist: Bei Einstellung auf true wird der Schattengeber, der mit Node.cloneNode() oder Document.importNode() geklont wird, die Schattenwurzel in der Kopie enthalten. Der Standardwert ist false.

delegatesFocus Optional

Ein boolescher Wert, der bei Einstellung auf true ein Verhalten festlegt, das Probleme bei benutzerdefinierten Elementen im Zusammenhang mit der Fokussierbarkeit mildert. Wenn ein nicht fokussierbarer Teil des Shadow-DOM angeklickt wird, erhält der erste fokussierbare Teil den Fokus, und der Schattengeber erhält alle verfügbaren :focus-Styling. Der Standardwert ist false.

serializable Optional

Ein boolescher Wert, der bei Einstellung auf true angibt, dass die Schattenwurzel serialisierbar ist. Wenn eingestellt, kann die Schattenwurzel durch Aufruf der Methoden Element.getHTML() oder ShadowRoot.getHTML() mit dem Parameter options.serializableShadowRoots, der auf true gesetzt ist, serialisiert werden. Der Standardwert ist false.

slotAssignment Optional

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

named

Elemente werden automatisch passenden <slot>-Elementen innerhalb dieser Schattenwurzel zugewiesen. Alle Nachkommen des Gastgebers mit einem slot-Attribut, das dem name-Attribut eines <slot> in dieser Schattenwurzel entspricht, werden diesem Slot zugewiesen. Alle obersten Kinder des Gastgebers ohne slot-Attribut werden einem <slot> ohne name-Attribut (dem "Standard-Slot") zugewiesen, wenn ein solcher vorhanden ist.

manual

Elemente werden nicht automatisch <slot>-Elementen zugeordnet. 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

Diese Ausnahme kann auftreten, wenn Sie versuchen, einer Schattenwurzel ein Element anzufügen:

  • außerhalb des HTML-Namespace oder das keinen Schatten haben kann.
  • bei dem die statische Eigenschaft disabledFeatures der Elementdefinition auf "shadow" gesetzt wurde.
  • das bereits eine Schattenwurzel hat, die nicht deklarativ erstellt wurde.
  • das eine deklarative Schattenwurzel hat, bei dem der angegebene mode nicht mit dem vorhandenen Modus übereinstimmt.

Beispiele

Word Count benutzerdefiniertes Element

Das folgende Beispiel stammt aus unserem word-count-web-component-Demo (sehen Sie es auch live). Sie können sehen, dass wir attachShadow() in der Mitte des Codes verwenden, um eine Schattenwurzel zu erstellen, an die wir dann den Inhalt unseres benutzerdefinierten Elements anfügen.

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

Shadow DOM deaktivieren

Wenn das Element eine statische Eigenschaft namens disabledFeatures hat, die ein Array ist und die Zeichenkette "shadow" enthält, 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