StyleSheetList — Schnittstelle · JavaScript-Referenz

Signatur

interface StyleSheetList

Beschreibung

StyleSheetList ist eine live aktualisierte, schreibgeschützte Sammlung aller Stylesheets, die explizit per <link rel="stylesheet"> oder <style> in ein Dokument oder eine Shadow Root eingebunden sind. Man bekommt sie über document.styleSheets oder shadowRoot.styleSheets. Einen öffentlichen Konstruktor gibt es nicht.

Die Liste stellt die Eigenschaft length und die Methode item(index) bereit. Außerdem kann man mit einem Index in eckigen Klammern (sheets[0]) zugreifen und sie mit for...of durchlaufen, weil sie iterierbar ist. Array-Methoden wie map oder filter fehlen aber. Dafür wandelt man die Liste vorher mit Array.from() oder dem Spread-Operator in ein echtes Array um.

Typische Einsatzzwecke sind: zur Laufzeit CSS-Regeln prüfen, ein bestimmtes Stylesheet aktivieren oder deaktivieren (sheet.disabled), Design-Umschalter (Theme-Switcher) bauen und Debugging- oder Analyse-Werkzeuge schreiben, die alle geladenen Regeln auswerten.

Beispiele

Alle Stylesheets des Dokuments auflisten

const sheets = document.styleSheets;
console.log(`Anzahl: ${sheets.length}`);

for (const sheet of sheets) {
  // href ist null bei eingebetteten <style>-Elementen
  console.log(sheet.href ?? '(inline <style>)', sheet.ownerNode?.nodeName);
}

Anzahl: 2 https://example.com/main.css LINK (inline <style>) STYLE

Zugriff per item() und Index

const sheets = document.styleSheets;
const first = sheets.item(0);   // gleichwertig: sheets[0]
console.log(first === sheets[0]);
console.log(sheets.item(999));  // außerhalb des Bereichs

true null

Theme-Umschalter über disabled

// <link rel="stylesheet" href="dark.css" title="dark">
const toggleTheme = (title, enabled) => {
  for (const sheet of document.styleSheets) {
    if (sheet.title === title) sheet.disabled = !enabled;
  }
};

toggleTheme('dark', true);

Alle CSS-Regeln sicher einsammeln (CORS beachten)

const allRules = Array.from(document.styleSheets).flatMap((sheet) => {
  try {
    return Array.from(sheet.cssRules);
  } catch (err) {
    // Fremd-Stylesheets ohne CORS-Freigabe werfen SecurityError
    console.warn('Kein Zugriff auf', sheet.href);
    return [];
  }
});

const selectors = allRules
  .filter((rule) => rule instanceof CSSStyleRule)
  .map((rule) => rule.selectorText);
console.log(selectors.slice(0, 3));

["body", ".header", ".nav a"]

// Wichtig · Fallstricke

Live-Liste: Werden <style>- oder <link>-Elemente hinzugefügt oder entfernt, ändert sich die Liste sofort mit. Wer beim Durchlaufen gleichzeitig das DOM verändert, sollte vorher mit Array.from() einen Schnappschuss anlegen.
Kein echtes Array: map, filter und forEach stehen nicht zur Verfügung. for...of funktioniert in modernen Browsern.
CORS/Sicherheit: Bei Stylesheets von fremden Ursprüngen ohne crossorigin-Attribut und passende CORS-Header wirft der Zugriff auf cssRules einen SecurityError. Die Liste selbst enthält solche Stylesheets trotzdem.
Ladezeitpunkt: Ein <link>-Stylesheet steht erst nach seinem load-Ereignis vollständig zur Verfügung. Vorher können sheet oder cssRules leer sein.
Nicht enthalten: Konstruierte Stylesheets (new CSSStyleSheet()), die über adoptedStyleSheets eingebunden sind, und Inline-style-Attribute tauchen in der Liste nicht auf.
Die Schnittstelle wird von allen modernen Browsern unterstützt. shadowRoot.styleSheets gibt es in allen Browsern mit Shadow-DOM-Unterstützung.

Siehe auch

CSSStyleSheet StyleSheet Document.styleSheets ShadowRoot.styleSheets Document.adoptedStyleSheets CSSRuleList Array.from