Element: attachShadow() Methode

Beachten Sie, dass Sie nicht an jeden Elementtyp einen Shadow-Root anhängen können. Einige können aus Sicherheitsgründen keinen Shadow-DOM haben (zum Beispiel ).

Die folgende Liste enthält Elemente, an die Sie einen Shadow-Root anhängen können:

• Jedes autonome benutzerdefinierte Element mit einem gültigen Namen
• h1
• h2
• h3
• h4
• h5
• h6

Die Methode kann bei einem Element aufgerufen werden, das bereits eine deklarative Shadow-Root hat, vorausgesetzt, der angegebene Modus mode passt zum bestehenden Modus. In diesem Fall wird die bereits vorhandene ShadowRoot geleert und zurückgegeben. Dies ermöglicht Situationen, in denen serverseitiges Rendering bereits deklarativ eine Shadow-Root erstellt hat und dann clientseitiger Code versucht, die Root erneut anzuhängen.

Andernfalls wird das Aufrufen von attachShadow() bei einem Element, das bereits eine Shadow-Root hat, eine Ausnahme werfen.

options

Ein Objekt, das die folgenden Felder enthält:

mode

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

open

Elemente der Shadow-Root sind von 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 kopierbar ist: Wenn auf true gesetzt, wird das Shadow-Host-Element, das mit Node.cloneNode() oder Document.importNode() geklont wird, die Shadow-Root in die Kopie aufnehmen. Der Standardwert ist false.

delegatesFocus Optional

Ein Boolean, der, wenn auf true gesetzt, ein Verhalten angibt, das Probleme mit der Fokussierbarkeit benutzerdefinierter Elemente mindert. Wenn auf einen nicht fokussierbaren Teil des Shadow-DOMs geklickt wird, erhält der erste fokussierbare Teil den Fokus, und das Shadow-Host-Element erhält jegliche verfügbare :focus-Stilierung. Der Standardwert ist false.

serializable Optional

Ein Boolean, der, wenn auf true gesetzt, angibt, dass die Shadow-Root serialisierbar ist. Wenn gesetzt, darf die 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 zu -Elementen innerhalb dieser Shadow-Root zugewiesen. Alle Nachkommen des Hosts mit einem slot-Attribut, das dem name-Attribut eines innerhalb dieser Shadow-Root entspricht, werden diesem Slot zugewiesen. Jegliche obersten Nachkommen des Hosts ohne slot-Attribut werden einem ohne name-Attribut (dem „Standard-Slot“) zugewiesen, wenn einer vorhanden ist.

manual

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

Gibt ein ShadowRoot Objekt zurück.

NotSupportedError DOMException

Dieser Fehler kann auftreten, wenn Sie versuchen, einem Element eine Shadow-Root hinzuzufügen:

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

Das folgende Beispiel stammt aus unserem Wortzähl-Webkomponenten Demo (sehen Sie es auch live). 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.

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

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

Beispiel:

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

• ShadowRoot.mode
• ShadowRoot.delegatesFocus
• ShadowRoot.slotAssignment
• Deklaratives Anfügen einer Shadow-Root mit dem shadowrootmode-Attribut des