ShadowRoot: adoptedStyleSheets-Eigenschaft

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Die adoptedStyleSheets-Eigenschaft des ShadowRoot-Interfaces legt ein Array von erstellten Stylesheets fest, das vom Schatten-DOM-Teilbaum verwendet wird.

Hinweis: Ein erstelltes Stylesheet ist ein Stylesheet, das programmatisch mit dem CSSStyleSheet()-Konstruktor erstellt wurde (im Vergleich zu einem, das von einem User-Agent erstellt wird, wenn ein Stylesheet aus einem Skript importiert, mit <style> und @import importiert oder über <link> verknüpft wird).

Dasselbe erstellte Stylesheet kann von mehreren ShadowRoot-Instanzen sowie vom übergeordneten Dokument (mithilfe der Document.adoptedStyleSheets-Eigenschaft) übernommen werden. Änderungen an einem übernommenen Stylesheet wirken sich auf alle übernehmenden Objekte aus.

Stylesheets in der adoptedStyleSheets-Eigenschaft werden zusammen mit den anderen Stylesheets des Schatten-DOMs betrachtet. Für die Bestimmung des endgültigen berechneten CSS eines Elements gelten sie als nach den anderen Stylesheets im Schatten-DOM (ShadowRoot.styleSheets) hinzugefügt.

Nur Stylesheets, die mit dem CSSStyleSheet()-Konstruktor erstellt wurden und sich im selben übergeordneten Document wie der Schattenwurzel befinden, können übernommen werden.

Wert

Der Wert ist ein Array von CSSStyleSheet-Instanzen, die mit dem CSSStyleSheet()-Konstruktor im Kontext des übergeordneten Document der Schattenwurzel erstellt wurden.

Falls das Array geändert werden muss, verwenden Sie in-place Mutationen wie push(). Die CSSStyleSheet-Instanzen selbst können ebenfalls geändert werden, und diese Änderungen gelten überall dort, wo das Stylesheet übernommen wird.

In einer früheren Version der Spezifikation war das Array nicht modifizierbar, sodass die einzige Möglichkeit, neue Stylesheets hinzuzufügen, darin bestand, ein neues Array der adoptedStyleSheets-Eigenschaft zuzuweisen.

Beispiele

Übernahme eines Stylesheets

Der untenstehende Code zeigt zunächst, wie ein Stylesheet erstellt wird, und dann wird CSSStyleSheet.replaceSync() aufgerufen, um eine Regel zum Stylesheet hinzuzufügen.

js
// Create an empty "constructed" stylesheet
const sheet = new CSSStyleSheet();
// Apply a rule to the sheet
sheet.replaceSync("a { color: red; }");

Dann erstellen wir ein ShadowRoot und übergeben das Stylesheet-Objekt innerhalb eines Arrays an adoptedStyleSheets.

js
// Create an element in the document and then create a shadow root:
const node = document.createElement("div");
const shadow = node.attachShadow({ mode: "open" });

// Adopt the sheet into the shadow DOM
shadow.adoptedStyleSheets = [sheet];

Wir können die Stylesheets immer noch ändern, nachdem sie dem Array hinzugefügt wurden. Unten fügen wir dem gleichen Stylesheet mit CSSStyleSheet.insertRule() eine neue Regel hinzu.

js
sheet.insertRule("* { background-color: blue; }");
// The document will now have blue background.

Ein neues Stylesheet anhängen

Neue Stylesheets können dem Dokument oder dem Schatten-Wurzel durch die Verwendung von adoptedStyleSheets.push() angehängt werden:

js
const extraSheet = new CSSStyleSheet();
extraSheet.replaceSync("p { color: green; }");

// Concat the new sheet.
shadow.adoptedStyleSheets.push(extraSheet);

Spezifikationen

Specification
CSS Object Model (CSSOM)
# dom-documentorshadowroot-adoptedstylesheets

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch