CSSGroupingRule.deleteRule() — Methode · JavaScript-Referenz

Signatur

CSSGroupingRule.prototype.deleteRule(index)

Beschreibung

Die Methode deleteRule() der Schnittstelle CSSGroupingRule entfernt eine untergeordnete Regel aus einer gruppierenden At-Regel. Zu den gruppierenden Regeln zählen z. B. CSSMediaRule (@media), CSSSupportsRule (@supports), CSSContainerRule (@container), CSSLayerBlockRule (@layer { … }) und bei CSS-Verschachtelung auch CSSStyleRule.

Die zu entfernende Regel wird über ihren Index in der Live-Liste cssRules bestimmt. Nach dem Löschen rücken alle folgenden Regeln um eine Position nach vorn, deshalb verschieben sich ihre Indizes. Die Änderung wirkt sofort auf die Darstellung der Seite.

Typische Einsatzfälle: dynamisch erzeugte Stylesheets (Theme-Umschaltung, CSS-in-JS, Werkzeuge im Stil der Entwicklertools) aufräumen oder einzelne Regeln innerhalb einer Media-Query gezielt deaktivieren, ohne das ganze Stylesheet neu zu schreiben. Das Gegenstück ist CSSGroupingRule.insertRule().

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierter Index der zu entfernenden Regel in `cssRules` der Gruppierungsregel. Wird intern in einen vorzeichenlosen 32-Bit-Integer umgewandelt.

Beispiele

Regel aus einer @media-Regel entfernen

const style = document.createElement('style');
style.textContent = `
  @media (min-width: 600px) {
    body { background: lightblue; }
    h1 { color: navy; }
  }
`;
document.head.append(style);

const mediaRule = style.sheet.cssRules[0]; // CSSMediaRule
console.log(mediaRule.cssRules.length);

// Die body-Regel (Index 0) entfernen
mediaRule.deleteRule(0);

console.log(mediaRule.cssRules.length);
console.log(mediaRule.cssRules[0].cssText);

2 1 h1 { color: navy; }

Regel anhand ihres Selektors suchen und löschen

const removeRuleBySelector = (groupingRule, selector) => {
  const rules = [...groupingRule.cssRules];
  const index = rules.findIndex(
    (rule) => rule instanceof CSSStyleRule && rule.selectorText === selector
  );
  if (index !== -1) {
    groupingRule.deleteRule(index);
    return true;
  }
  return false;
};

const sheet = new CSSStyleSheet();
sheet.replaceSync(`@supports (display: grid) {
  .grid { display: grid; }
  .card { gap: 1rem; }
}`);
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const supportsRule = sheet.cssRules[0];
console.log(removeRuleBySelector(supportsRule, '.card'));
console.log(supportsRule.cssRules.length);

true 1

Alle Unterregeln sicher leeren (rückwärts löschen)

const clearGroupingRule = (groupingRule) => {
  // Rückwärts iterieren, da sich Indizes beim Löschen verschieben
  for (let i = groupingRule.cssRules.length - 1; i >= 0; i--) {
    groupingRule.deleteRule(i);
  }
};

const style = document.createElement('style');
style.textContent = '@media print { nav { display: none; } footer { display: none; } }';
document.head.append(style);

const printRule = style.sheet.cssRules[0];
clearGroupingRule(printRule);
console.log(printRule.cssRules.length);

Fehler bei ungültigem Index abfangen

const style = document.createElement('style');
style.textContent = '@media screen { p { margin: 0; } }';
document.head.append(style);

const rule = style.sheet.cssRules[0];
try {
  rule.deleteRule(5);
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Ungültiger Index: Ist index größer oder gleich cssRules.length, wird eine DOMException vom Typ IndexSizeError geworfen. Negative Werte werden in große vorzeichenlose Zahlen umgewandelt und lösen ebenfalls diesen Fehler aus.
Indizes verschieben sich: Wer mehrere Regeln in einer Schleife löscht, sollte rückwärts iterieren oder die Indizes vorher ermitteln. Sonst werden Regeln übersprungen.
Zustandsfehler: Wenn eine Regel nicht entfernt werden darf (z. B. eine @namespace-Regel auf Stylesheet-Ebene, die hier aber praktisch nicht vorkommt), kann eine InvalidStateError auftreten.
Cross-Origin-Stylesheets: Bei Stylesheets von fremden Ursprüngen ohne CORS-Freigabe ist schon der Zugriff auf cssRules gesperrt (SecurityError). Deshalb lässt sich dort auch deleteRule() nicht verwenden.
Nicht mit CSSStyleSheet.deleteRule() verwechseln: Diese Methode wirkt nur auf die Unterregeln der Gruppe, nicht auf die oberste Ebene des Stylesheets. Um die ganze @media-Regel zu entfernen, brauchst du sheet.deleteRule().
Kompatibilität: Wird von allen modernen Browsern unterstützt. Früher gab es die Methode nur auf CSSMediaRule bzw. CSSSupportsRule. Dass sie auf CSSStyleRule für verschachteltes CSS verfügbar ist, ist neu (ab ca. 2023).

Siehe auch

CSSPrimitiveValue.getRectValue() CSSGroupingRule.insertRule() CSSKeyframesRule.deleteRule() CSSStyleSheet.deleteRule() CSSKeyframesRule.appendRule()