CSSGroupingRule.insertRule() — Methode · JavaScript-Referenz

Signatur

CSSGroupingRule.prototype.insertRule(rule, index)

Beschreibung

insertRule() ist eine Methode von CSSGroupingRule. Das ist die Basisschnittstelle für At-Regeln, die selbst weitere Regeln enthalten, etwa CSSMediaRule (@media), CSSSupportsRule (@supports), CSSLayerBlockRule (@layer), CSSContainerRule (@container) und CSSStyleRule bei verschachteltem CSS. Die Methode liest einen CSS-Text ein und fügt die daraus entstandene Regel an der angegebenen Stelle in cssRules der Gruppe ein.

Nützlich ist das, wenn Stile zur Laufzeit gezielt innerhalb einer bestehenden Media-Query oder eines Feature-Queries ergänzt werden sollen. Ein Beispiel sind Themes oder CSS-in-JS-Bibliotheken, die ohne Textmanipulation von <style>-Elementen auskommen wollen. Die Regel wirkt sofort, ohne dass das Stylesheet neu geladen werden muss.

Die Methode funktioniert genau wie CSSStyleSheet.prototype.insertRule(), bezieht sich aber auf die Regelliste einer einzelnen Gruppenregel statt auf das ganze Stylesheet. Lässt man index weg, wird die Regel an Position 0 eingefügt, also am Anfang. Bei gleicher Spezifität hat sie deshalb die niedrigste Priorität innerhalb der Gruppe.

Parameter

Name	Typ	Default	Beschreibung
$rule Pflicht	string		Der CSS-Text genau einer Regel, z. B. `'.box { color: red; }'`. Mehrere Regeln oder reine Deklarationen ohne Selektor lösen einen `SyntaxError` aus.
$index	number	0	Position in `cssRules`, an der die Regel eingefügt wird. Erlaubt sind Werte von `0` bis `cssRules.length`. Mit `cssRules.length` wird die Regel am Ende angehängt.

Rückgabewert

Typ

number

Beschreibung

Der Index, an dem die neue Regel in cssRules der Gruppenregel eingefügt wurde.

Beispiele

Regel am Ende einer @media-Regel anhängen

const style = document.createElement('style');
style.textContent = '@media (min-width: 600px) { body { margin: 2rem; } }';
document.head.append(style);

const mediaRule = style.sheet.cssRules[0]; // CSSMediaRule
const idx = mediaRule.insertRule('.card { padding: 1.5rem; }', mediaRule.cssRules.length);

console.log(idx);
console.log(mediaRule.cssRules[idx].cssText);

1 .card { padding: 1.5rem; }

Standardposition 0 ohne index

const sheet = new CSSStyleSheet();
sheet.replaceSync('@supports (display: grid) { .a { color: red; } }');
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const supportsRule = sheet.cssRules[0];
supportsRule.insertRule('.b { color: blue; }'); // landet vor .a

console.log([...supportsRule.cssRules].map(r => r.selectorText));

[".b", ".a"]

Fehler sicher abfangen

const addToGroup = (groupRule, cssText) => {
  try {
    return groupRule.insertRule(cssText, groupRule.cssRules.length);
  } catch (err) {
    console.warn(`Regel abgelehnt (${err.name}):`, cssText);
    return -1;
  }
};

const sheet = new CSSStyleSheet();
sheet.replaceSync('@media print { h1 { font-size: 18pt; } }');
const media = sheet.cssRules[0];

console.log(addToGroup(media, 'p { orphans: 3; }'));
console.log(addToGroup(media, 'color: red;')); // kein Selektor
console.log(addToGroup(media, 'a {} b {}'));    // zwei Regeln

1 Regel abgelehnt (SyntaxError): color: red; -1 Regel abgelehnt (SyntaxError): a {} b {} -1

// Wichtig · Fallstricke

Standardindex ist 0: Ohne index wird die Regel am Anfang eingefügt, nicht am Ende. Zum Anhängen group.cssRules.length übergeben.
Ausnahmen: Ein index größer als cssRules.length löst einen IndexSizeError (DOMException) aus. Ungültiger CSS-Text oder mehrere Regeln lösen einen SyntaxError aus. Regeln, die an dieser Stelle nicht erlaubt sind, lösen einen HierarchyRequestError aus, z. B. @import innerhalb von @media.
Fremde Stylesheets: Bei Stylesheets von anderen Ursprüngen ohne CORS-Freigabe löst schon der Zugriff auf cssRules einen SecurityError aus.
Sicherheit: Keinen ungeprüften Nutzertext als Regel einfügen. CSS-Injection kann Layouts manipulieren oder über Attribut-Selektoren mit url() Daten ausspähen. Die Content Security Policy (style-src) wird bei der CSSOM-Manipulation nicht erneut geprüft.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Für CSSStyleRule als Gruppe (CSS-Verschachtelung) sind aktuelle Browserversionen nötig (etwa ab 2023).
Änderungen über das CSSOM erscheinen nicht im textContent des <style>-Elements.

Siehe auch

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