CSSGroupingRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSGroupingRule extends CSSRule

Beschreibung

CSSGroupingRule ist eine abstrakte Basisschnittstelle des CSS Object Model (CSSOM). Sie beschreibt alle CSS-Regeln, die selbst eine Liste weiterer Regeln enthalten. Direkt erzeugen kann man sie nicht – man trifft sie über abgeleitete Schnittstellen an, etwa CSSMediaRule (@media), CSSSupportsRule (@supports), CSSContainerRule (@container), CSSLayerBlockRule (@layer { … }), CSSScopeRule (@scope), CSSStartingStyleRule und – dank CSS-Verschachtelung – auch CSSStyleRule.

Die Schnittstelle erbt von CSSRule (also cssText, parentRule, parentStyleSheet) und ergänzt:

cssRules – eine live CSSRuleList mit den verschachtelten Regeln (nur lesbar).
insertRule(rule, index) – fügt eine neue Regel an Position index ein und gibt diesen Index zurück.
deleteRule(index) – entfernt die Regel an Position index.

Praktisch nützlich ist CSSGroupingRule immer dann, wenn man Stylesheets zur Laufzeit analysieren oder verändern will: z. B. alle Regeln innerhalb von Media-Queries rekursiv durchlaufen, Theme-Regeln in einen @media (prefers-color-scheme: dark)-Block einfügen oder Regeln aus einem bestimmten Kaskaden-Layer entfernen. Mit rule instanceof CSSGroupingRule lässt sich generisch prüfen, ob eine Regel Kindregeln besitzt.

Parameter

Name	Typ	Default	Beschreibung
$rule Pflicht	string		Für `insertRule()`: der CSS-Text genau einer Regel, z. B. `".btn { color: red; }"`.
$index	number	0	Für `insertRule()`: Einfügeposition in `cssRules` (0 = Anfang, `cssRules.length` = Ende). Für `deleteRule()`: Pflicht, Position der zu löschenden Regel.

Rückgabewert

Typ

CSSGroupingRule

Beschreibung

Instanzen erhält man nur indirekt, z. B. über document.styleSheets[i].cssRules. insertRule() liefert den Index (number) der eingefügten Regel, deleteRule() liefert undefined.

Beispiele

Gruppierende Regeln eines Stylesheets finden

// Stylesheet mit verschachtelten At-Regeln anlegen
const style = document.createElement('style');
style.textContent = `
  body { margin: 0; }
  @media (max-width: 600px) { .nav { display: none; } .logo { width: 80px; } }
  @supports (display: grid) { .layout { display: grid; } }
`;
document.head.append(style);

for (const rule of style.sheet.cssRules) {
  if (rule instanceof CSSGroupingRule) {
    console.log(rule.constructor.name, '→', rule.cssRules.length, 'Kindregeln');
  }
}

CSSMediaRule → 2 Kindregeln CSSSupportsRule → 1 Kindregeln

Regel in eine Media-Query einfügen und wieder löschen

const sheet = new CSSStyleSheet();
sheet.replaceSync('@media (prefers-color-scheme: dark) { body { background: #111; } }');
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const darkRule = sheet.cssRules[0]; // CSSMediaRule, also CSSGroupingRule

// Am Ende anhängen
const idx = darkRule.insertRule('a { color: #8ab4f8; }', darkRule.cssRules.length);
console.log(idx, darkRule.cssRules[idx].cssText);

// Wieder entfernen
darkRule.deleteRule(idx);
console.log(darkRule.cssRules.length);

1 a { color: rgb(138, 180, 248); } 1

Alle Style-Regeln rekursiv sammeln

const collectStyleRules = (ruleList, result = []) => {
  for (const rule of ruleList) {
    if (rule instanceof CSSStyleRule) result.push(rule.selectorText);
    // Rekursion in jede gruppierende Regel (@media, @supports, @layer, Nesting …)
    if (rule instanceof CSSGroupingRule) collectStyleRules(rule.cssRules, result);
  }
  return result;
};

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  h1 { font-size: 2rem; }
  @layer base { p { line-height: 1.5; } @media print { p { color: black; } } }
`);
console.log(collectStyleRules(sheet.cssRules));

["h1", "p", "p"]

// Wichtig · Fallstricke

Abstrakt: new CSSGroupingRule() wirft einen TypeError. Man bekommt Instanzen nur über die CSSOM-Regellisten.
Cross-Origin-Stylesheets: Bei Stylesheets von fremden Ursprüngen ohne passende CORS-Header wirft schon der Zugriff auf sheet.cssRules einen SecurityError. Zugriffe daher in try/catch kapseln.
insertRule() akzeptiert nur eine Regel; ungültiges CSS führt zu SyntaxError, ein Index außerhalb des Bereichs zu IndexSizeError. Manche Regeln sind an bestimmten Stellen nicht erlaubt (z. B. @import in @media) → HierarchyRequestError.
cssRules ist live: Wer beim Iterieren löscht, sollte rückwärts laufen, um Indexverschiebungen zu vermeiden.
Dass CSSStyleRule von CSSGroupingRule erbt (CSS-Nesting), ist relativ neu (ca. 2023, Chrome 112+, Safari 16.5+, Firefox 117+). In älteren Browsern ist CSSStyleRule keine CSSGroupingRule. Ebenso ist CSSConditionRule in älteren Versionen teils direkt von CSSRule abgeleitet.
Änderungen über das CSSOM landen nicht im Quelltext des <style>-Elements; style.textContent bleibt unverändert.

Siehe auch

CSSRule CSSRuleList CSSConditionRule CSSMediaRule CSSSupportsRule CSSLayerBlockRule CSSStyleRule CSSStyleSheet CSSGroupingRule.insertRule() CSSGroupingRule.deleteRule() CSSGroupingRule.cssRules