CSSRuleList — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSRuleList

Beschreibung

CSSRuleList ist eine array-ähnliche Sammlung von CSSRule-Objekten. Man bekommt sie über die Eigenschaft cssRules von CSSStyleSheet und von Gruppierungsregeln wie CSSMediaRule, CSSSupportsRule, CSSContainerRule, CSSLayerBlockRule oder CSSKeyframesRule. Die Liste ist live. Fügt man also mit insertRule() eine Regel hinzu oder löscht man eine mit deleteRule(), ändert sich die bestehende Liste sofort mit.

Die Liste selbst kann man nicht direkt ändern. Es gibt kein push(), splice() und keine Zuweisung per Index. Änderungen laufen immer über die Methoden des übergeordneten Objekts (insertRule()/deleteRule()). Die einzelnen CSSRule-Objekte kann man dagegen ändern, zum Beispiel über rule.style.setProperty() bei einer CSSStyleRule.

Die Schnittstelle hat nur zwei Mitglieder:

length: die Anzahl der Regeln (schreibgeschützt).
item(index): gibt die Regel an der Position index zurück, sonst null. Kürzer geht es mit dem Index-Zugriff list[index], der bei ungültigem Index undefined liefert.

Man verwendet CSSRuleList, um Stylesheets zur Laufzeit auszuwerten oder zu ändern: Selektoren suchen, Media Queries auslesen, Themes umschalten, kritisches CSS herausziehen oder Stylesheets in Entwicklerwerkzeugen durchsuchen. Die Liste ist iterierbar, funktioniert also mit for...of, Spread-Syntax und Array.from().

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nur für `item(index)`: nullbasierte Position der gewünschten Regel. Liegt der Index außerhalb der Liste, ist das Ergebnis `null`.

Rückgabewert

Typ

CSSRuleList

Beschreibung

Die Liste selbst bekommt man aus cssRules. item() gibt ein CSSRule oder null zurück, length eine number.

Beispiele

Alle Regeln eines Stylesheets auflisten

// Ein Stylesheet mit Regeln anlegen
const style = document.createElement('style');
style.textContent = `
  body { margin: 0; }
  .btn { color: white; background: navy; }
  @media (max-width: 600px) { .btn { width: 100%; } }
`;
document.head.append(style);

const rules = style.sheet.cssRules; // CSSRuleList
console.log(rules.length);

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

3 CSSStyleRule → body { margin: 0px; } CSSStyleRule → .btn { color: white; background: navy; } CSSMediaRule → @media (max-width: 600px) { .btn { width: 100%; } }

item(), Index-Zugriff und Live-Verhalten

const sheet = new CSSStyleSheet();
sheet.replaceSync('h1 { color: red; }');

const rules = sheet.cssRules;
console.log(rules.length);           // 1
console.log(rules.item(0).selectorText);
console.log(rules.item(5));          // außerhalb: null
console.log(rules[5]);               // außerhalb: undefined

// Die Liste ist live und zeigt die Änderung sofort
sheet.insertRule('p { line-height: 1.5; }', rules.length);
console.log(rules.length);           // 2

1 h1 null undefined 2

Regel per Selektor finden und ändern (auch in Media Queries)

const findRules = (list, selector) => {
  const found = [];
  for (const rule of list) {
    if (rule instanceof CSSStyleRule && rule.selectorText === selector) {
      found.push(rule);
    }
    // Gruppierungsregeln haben eine eigene CSSRuleList
    if (rule.cssRules) found.push(...findRules(rule.cssRules, selector));
  }
  return found;
};

const sheet = document.styleSheets[0];
const btnRules = findRules(sheet.cssRules, '.btn');
btnRules.forEach((r) => r.style.setProperty('border-radius', '8px'));
console.log(`${btnRules.length} Regel(n) angepasst`);

2 Regel(n) angepasst

In ein echtes Array umwandeln

const sheet = new CSSStyleSheet();
sheet.replaceSync('a { color: blue; } b { font-weight: 900; } @font-face { font-family: X; src: local(Arial); }');

// Eine CSSRuleList hat kein map/filter, deshalb erst umwandeln
const selectors = [...sheet.cssRules]
  .filter((r) => r instanceof CSSStyleRule)
  .map((r) => r.selectorText);

console.log(selectors);

["a", "b"]

// Wichtig · Fallstricke

Cross-Origin-Stylesheets: Stammt ein Stylesheet über <link> von einer fremden Domain ohne passende CORS-Header (crossorigin-Attribut plus Access-Control-Allow-Origin), wirft der Zugriff auf sheet.cssRules einen SecurityError. Deshalb den Zugriff in try...catch packen, wenn man über document.styleSheets iteriert.
Kein echtes Array: Methoden wie map, filter oder forEach gibt es nicht. Erst mit Array.from() oder [...list] umwandeln. Die Umwandlung ist dann eine Momentaufnahme, die sich nicht mehr mitändert.
Live-Liste beim Löschen: Wer in einer Schleife mit deleteRule(i) Regeln entfernt, verschiebt dabei die Indizes. Deshalb rückwärts laufen (for (let i = rules.length - 1; i >= 0; i--)).
item() gibt bei ungültigem Index null zurück, der Index-Zugriff [i] dagegen undefined.
Verschachtelte Regeln (@media, @supports, @layer, @container, CSS-Nesting) tauchen in der obersten Liste nicht auf. Sie stecken in einer eigenen cssRules-Liste der Gruppierungsregel, die man rekursiv durchsuchen muss.
Die Iterierbarkeit (for...of) wird von allen modernen Browsern unterstützt. CSSRuleList selbst funktioniert in allen Browsern.

Siehe auch

CSSValueList CSSRule FileList DOMRectList NodeList