StyleSheet.disabled — Eigenschaft · JavaScript-Referenz

Signatur

StyleSheet.disabled

Beschreibung

Die Eigenschaft disabled des StyleSheet-Interfaces (und damit auch von CSSStyleSheet) ist lesbar und schreibbar. Hat sie den Wert true, ignoriert der Browser alle Regeln dieses Stylesheets. Bei false wird es normal angewendet. Die Änderung wirkt sofort, das Stylesheet wird also weder entfernt noch neu geladen.

Typische Einsatzfälle sind Theme-Umschalter (z. B. Hell/Dunkel), das vorübergehende Abschalten von Druck- oder Debug-Styles und alternative Stylesheets. Gegenüber dem Entfernen und erneuten Einfügen eines <link>-Elements hat das Umschalten über disabled einen Vorteil: Das CSS bleibt geparst im Speicher und ist beim Wiedereinschalten sofort verfügbar.

Auf das Stylesheet greifst du über document.styleSheets, über HTMLLinkElement.sheet bzw. HTMLStyleElement.sheet zu, oder im Fall von Constructable Stylesheets direkt über die mit new CSSStyleSheet() erzeugte Instanz.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean	false	Beim Setzen: `true` deaktiviert das Stylesheet, `false` aktiviert es. Andere Werte werden in einen booleschen Wert umgewandelt.

Beispiele

Status aller Stylesheets auslesen

// Listet alle Stylesheets des Dokuments mit ihrem Status auf
const sheets = [...document.styleSheets];
sheets.forEach((sheet, i) => {
  const quelle = sheet.href ?? '(inline <style>)';
  console.log(`${i}: ${quelle} – deaktiviert: ${sheet.disabled}`);
});

0: https://example.com/main.css – deaktiviert: false 1: (inline <style>) – deaktiviert: false

Dunkelmodus per Button umschalten

// HTML: <link id="dark-theme" rel="stylesheet" href="dark.css">
//       <button id="toggle">Theme wechseln</button>
const darkSheet = document.getElementById('dark-theme').sheet;
const button = document.getElementById('toggle');

// Gespeicherte Einstellung übernehmen
darkSheet.disabled = localStorage.getItem('theme') !== 'dark';

button.addEventListener('click', () => {
  darkSheet.disabled = !darkSheet.disabled;
  localStorage.setItem('theme', darkSheet.disabled ? 'light' : 'dark');
  console.log(`Dunkelmodus aktiv: ${!darkSheet.disabled}`);
});

Dunkelmodus aktiv: true

Constructable Stylesheet für Debug-Rahmen ein- und ausschalten

// Debug-Stylesheet einmalig erzeugen und einhängen
const debugSheet = new CSSStyleSheet();
debugSheet.replaceSync('* { outline: 1px solid rgba(255, 0, 0, 0.5); }');
document.adoptedStyleSheets = [...document.adoptedStyleSheets, debugSheet];

// Standardmäßig aus
debugSheet.disabled = true;

// Mit Strg+Umschalt+D umschalten
document.addEventListener('keydown', (e) => {
  if (e.ctrlKey && e.shiftKey && e.key === 'D') {
    debugSheet.disabled = !debugSheet.disabled;
    console.log('Debug-Rahmen:', debugSheet.disabled ? 'aus' : 'an');
  }
});

Debug-Rahmen: an

// Wichtig · Fallstricke

Nicht verwechseln: HTMLLinkElement.disabled (Attribut am <link>-Element) und StyleSheet.disabled (am Stylesheet-Objekt) sind zwei verschiedene Dinge. Wenn das disabled-Attribut schon im HTML steht, lädt der Browser das Stylesheet gar nicht, und link.sheet ist dann null.
element.sheet ist null, solange ein externes Stylesheet noch nicht geladen ist. Greif daher erst nach dem load-Event des <link>-Elements darauf zu.
Wird das <link>- oder <style>-Element aus dem DOM entfernt und wieder eingefügt, entsteht ein neues Stylesheet-Objekt. Ein vorher gesetzter disabled-Status geht dabei verloren.
Bei alternativen Stylesheets (rel="alternate stylesheet" mit title) sind diese anfangs deaktiviert. Setzt du disabled = false, werden sie aktiviert.
Bei Stylesheets von fremden Ursprüngen verhindert CORS den Zugriff auf cssRules. disabled lässt sich trotzdem lesen und setzen.
Die Eigenschaft wird von allen modernen Browsern unterstützt. Constructable Stylesheets (new CSSStyleSheet()) gibt es in Safari erst ab Version 16.4.

Siehe auch

StyleSheet CSSStyleSheet Document.styleSheets Document.adoptedStyleSheets HTMLLinkElement.sheet HTMLLinkElement.disabled StyleSheet.media