CSSStyleRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSStyleRule extends CSSGroupingRule

Beschreibung

CSSStyleRule ist der CSSOM-Typ für normale Stilregeln, also einen Selektor mit Deklarationsblock. Solche Objekte bekommt man nicht über einen Konstruktor, sondern über die Liste cssRules eines CSSStyleSheet (z. B. document.styleSheets[0].cssRules) oder einer Gruppenregel wie @media. Ob es sich um eine Stilregel handelt, prüft man mit rule instanceof CSSStyleRule.

Wichtige Eigenschaften:

selectorText (string): der Selektor der Regel. Man kann ihn lesen und neu setzen. Ist der neue Selektor ungültig, wird die Zuweisung stillschweigend ignoriert.
style (CSSStyleDeclaration, schreibgeschützte Referenz): die Deklarationen. Änderungen daran wirken sofort auf alle Elemente, auf die der Selektor passt.
styleMap (StylePropertyMap): typisierter Zugriff über die CSS Typed OM.
cssRules, insertRule(), deleteRule(): seit CSS Nesting erbt die Schnittstelle von CSSGroupingRule und kann verschachtelte Regeln enthalten.
Von CSSRule geerbt: cssText, parentRule, parentStyleSheet.

Sinnvoll ist das z. B. für Themes, bei denen eine Regel zentral geändert wird, statt Tausende Elemente einzeln per Inline-Style anzufassen. Auch Werkzeuge, die Stylesheets untersuchen (Linter, Extraktion von „Critical CSS“), oder Konstruierbare Stylesheets für Web Components nutzen diese Schnittstelle.

Rückgabewert

Typ

CSSStyleRule

Beschreibung

Wird nicht direkt erzeugt. Man erhält solche Objekte als Einträge von CSSStyleSheet.cssRules oder CSSGroupingRule.cssRules.

Beispiele

Alle Stilregeln eines Stylesheets auflisten

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  .btn { color: white; background: navy; }
  @media (min-width: 600px) { .btn { padding: 1rem; } }
`);

for (const rule of sheet.cssRules) {
  if (rule instanceof CSSStyleRule) {
    console.log(rule.selectorText, '→', rule.style.cssText);
  } else {
    console.log('Andere Regel:', rule.constructor.name);
  }
}

.btn → color: white; background: navy; Andere Regel: CSSMediaRule

Theme-Farbe zentral in der Regel ändern

const style = document.createElement('style');
style.textContent = '.card { background: #fff; color: #222; }';
document.head.append(style);

const cardRule = [...style.sheet.cssRules]
  .find((r) => r instanceof CSSStyleRule && r.selectorText === '.card');

// Wirkt sofort auf alle .card-Elemente
cardRule.style.setProperty('background', '#1e1e1e');
cardRule.style.setProperty('color', '#eee');
console.log(cardRule.cssText);

.card { background: rgb(30, 30, 30); color: rgb(238, 238, 238); }

Selektor ändern und neue Regel einfügen

const sheet = new CSSStyleSheet();
const index = sheet.insertRule('.alt { margin: 0; }');
const rule = sheet.cssRules[index];

rule.selectorText = '.neu, .neu-2';
console.log(rule.selectorText);

rule.selectorText = '::ungültig(';   // wird ignoriert
console.log(rule.selectorText);

document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

.neu, .neu-2 .neu, .neu-2

Verschachtelte Regeln (CSS Nesting) auslesen

const sheet = new CSSStyleSheet();
sheet.replaceSync('.menu { color: black; &:hover { color: red; } }');

const menu = sheet.cssRules[0];
console.log(menu.cssRules.length);
console.log(menu.cssRules[0].selectorText);

1 &:hover

// Wichtig · Fallstricke

Cross-Origin-Stylesheets: Wird ein Stylesheet von einer fremden Domain ohne passende CORS-Header (crossorigin-Attribut plus Access-Control-Allow-Origin) geladen, löst schon der Zugriff auf cssRules einen SecurityError aus. Deshalb in try…catch einpacken.
Browser normalisieren Werte und Selektoren. #fff wird z. B. zu rgb(255, 255, 255), Leerzeichen ändern sich. Selektoren daher nicht per exaktem Zeichenkettenvergleich mit dem Quelltext abgleichen.
Ein ungültiger Wert bei selectorText oder style.setProperty() wirft keinen Fehler, sondern wird ignoriert.
Verschachtelung (cssRules, insertRule auf CSSStyleRule) gibt es erst in neueren Browsern (Chrome 112+, Safari 16.5+, Firefox 117+). In älteren fehlen diese Mitglieder.
styleMap (Typed OM) fehlt in Firefox bislang.
Änderungen an Regeln betreffen alle passenden Elemente und lösen eine Neuberechnung der Stile aus. Viele Änderungen deshalb bündeln, statt sie in einer Schleife einzeln vorzunehmen.

Siehe auch

CSSRule CSSStyleSheet CSSStyleDeclaration CSSGroupingRule CSSMediaRule CSSStyleSheet.prototype.insertRule() Document.styleSheets Document.adoptedStyleSheets