CSSRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSRule

Beschreibung

CSSRule ist die gemeinsame Basisschnittstelle aller Regeln im CSS Object Model (CSSOM). Jede Regel eines Stylesheets, egal ob eine normale Stilregel wie .btn { color: red } oder eine At-Regel wie @media, @font-face oder @keyframes, erscheint in JavaScript als Objekt einer spezialisierten Unterklasse von CSSRule. Beispiele sind CSSStyleRule, CSSMediaRule, CSSKeyframesRule, CSSImportRule, CSSFontFaceRule, CSSSupportsRule, CSSLayerBlockRule und CSSContainerRule.

Einen eigenen Konstruktor gibt es nicht. CSSRule-Objekte bekommt man über CSSStyleSheet.cssRules (eine CSSRuleList) oder über cssRules von Gruppierungsregeln wie CSSMediaRule. Neue Regeln fügt man mit CSSStyleSheet.insertRule() ein.

Die Basisschnittstelle hat folgende Eigenschaften:

cssText: der Quelltext der Regel als String, serialisiert vom Browser.
parentRule: die umschließende Regel (z. B. ein @media-Block) oder null.
parentStyleSheet: das CSSStyleSheet, zu dem die Regel gehört.
type (veraltet): ein numerischer Typcode, z. B. CSSRule.STYLE_RULE (1) oder CSSRule.MEDIA_RULE (4).

Im Alltag braucht man CSSRule vor allem, um Stylesheets zur Laufzeit zu untersuchen oder zu ändern: um Regeln nach Selektor zu finden, Design-Themes umzuschalten, CSS-Analysewerkzeuge zu bauen oder Animationen dynamisch anzupassen. Welche Art von Regel vorliegt, prüft man heute am besten mit instanceof statt über type.

Rückgabewert

Typ

CSSRule

Beschreibung

Kein Konstruktor. Man erhält Instanzen, meist einer Unterklasse wie CSSStyleRule, über CSSStyleSheet.cssRules oder CSSGroupingRule.cssRules.

Beispiele

Alle Regeln eines Stylesheets auflisten

// Setzt voraus: <style id="app-css">.btn { color: red } @media (max-width: 600px) { .btn { color: blue } }</style>
const sheet = document.getElementById('app-css').sheet;

for (const rule of sheet.cssRules) {
  console.log(rule.constructor.name, '→', rule.cssText);
}

CSSStyleRule → .btn { color: red; } CSSMediaRule → @media (max-width: 600px) { .btn { color: blue; } }

Regeltyp mit instanceof erkennen (rekursiv)

const walkRules = (rules, depth = 0) => {
  for (const rule of rules) {
    const indent = '  '.repeat(depth);
    if (rule instanceof CSSStyleRule) {
      console.log(`${indent}Stilregel: ${rule.selectorText}`);
    } else if (rule instanceof CSSMediaRule) {
      console.log(`${indent}@media ${rule.conditionText}`);
      walkRules(rule.cssRules, depth + 1); // verschachtelte Regeln
    } else if (rule instanceof CSSKeyframesRule) {
      console.log(`${indent}@keyframes ${rule.name}`);
    }
  }
};

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  .card { padding: 1rem; }
  @media (prefers-color-scheme: dark) { .card { background: #222; } }
  @keyframes fade { from { opacity: 0 } to { opacity: 1 } }
`);
walkRules(sheet.cssRules);

Stilregel: .card @media (prefers-color-scheme: dark) Stilregel: .card @keyframes fade

Regel einfügen und parentStyleSheet / parentRule nutzen

const sheet = new CSSStyleSheet();
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const idx = sheet.insertRule('@media print { .no-print { display: none; } }');
const mediaRule = sheet.cssRules[idx];
const inner = mediaRule.cssRules[0];

console.log(inner.selectorText);
console.log(inner.parentRule === mediaRule);
console.log(inner.parentStyleSheet === sheet);

.no-print true true

Stilregel zur Laufzeit ändern (Theme-Farbe)

const sheet = new CSSStyleSheet();
sheet.replaceSync(':root { --accent: steelblue; }');
document.adoptedStyleSheets = [sheet];

const setAccent = (color) => {
  const rule = [...sheet.cssRules].find(
    (r) => r instanceof CSSStyleRule && r.selectorText === ':root'
  );
  rule?.style.setProperty('--accent', color);
};

setAccent('tomato');
console.log(sheet.cssRules[0].cssText);

:root { --accent: tomato; }

// Wichtig · Fallstricke

Zugriff auf fremde Stylesheets: Wenn ein Stylesheet von einer anderen Origin ohne passende CORS-Header geladen wurde (z. B. über ein CDN), löst der Zugriff auf sheet.cssRules einen SecurityError aus. Mit <link crossorigin="anonymous"> und Access-Control-Allow-Origin auf dem Server lässt sich das beheben. Den Zugriff sonst in try/catch kapseln.
type ist veraltet: Neuere Regelarten wie @layer und @container haben keinen eigenen Typcode mehr, sie liefern 0. Deshalb besser instanceof verwenden.
Beim Schreiben von cssText passiert nichts: Auf der Basisschnittstelle ist das Setzen von cssText laut Spezifikation wirkungslos. Man ändert Deklarationen über CSSStyleRule.style oder ersetzt ganze Regeln mit deleteRule() und insertRule().
Serialisierung: cssText gibt die vom Browser normalisierte Form zurück. Leerzeichen, Kurzschreibweisen und Farbformate können vom Original abweichen und sich zwischen Browsern unterscheiden.
Performance: Wer viele Regeln zur Laufzeit ändert, löst jedes Mal eine Neuberechnung der Stile aus. Änderungen daher bündeln. Für einfache Theme-Wechsel sind CSS-Custom-Properties meist günstiger.
Die Basisschnittstelle wird von allen Browsern unterstützt. Einzelne Unterklassen wie CSSContainerRule und CSSLayerBlockRule gibt es erst in neueren Browserversionen.

Siehe auch

CSSScale CSSValue CSS CSSPageRule CSSRotate