CSSStyleSheet.addRule() — Methode · JavaScript-Referenz

Signatur

CSSStyleSheet.prototype.addRule(selector, style, index)

Beschreibung

addRule() fügt einem CSSStyleSheet eine neue Stilregel hinzu. Anders als bei insertRule() übergibt man den Selektor und die Deklarationen getrennt als zwei Strings. Intern baut der Browser daraus den Regeltext selector { style } und ruft damit insertRule() auf.

Die Methode stammt aus dem Internet Explorer und wurde nur in den CSSOM-Standard aufgenommen, weil alter Code sie weiter benutzt. Deshalb gilt sie als veraltet. Im Unterschied zu insertRule() hängt addRule() die Regel standardmäßig am Ende des Stylesheets an, wenn kein Index angegeben ist. Außerdem gibt sie immer -1 zurück und nicht den tatsächlichen Index.

Brauchbar ist addRule() heute höchstens noch zum Warten von Altcode oder für Polyfills. In neuem Code verwendet man insertRule() oder, bei komplett neu aufgebauten Stylesheets, replace() bzw. replaceSync() auf einem erzeugten CSSStyleSheet.

Parameter

Name	Typ	Default	Beschreibung
$selector	string	"undefined"	Der Selektor der neuen Regel, z. B. `".warnung"` oder `"h1, h2"`. Wird er weggelassen, wird der Text `"undefined"` als Selektor verwendet. Das ist praktisch immer ein Fehler.
$style	string	"undefined"	Die Deklarationen ohne geschweifte Klammern, z. B. `"color: red; font-weight: bold"`. Ein leerer String erzeugt eine leere Regel `selector { }`.
$index	number	sheet.cssRules.length (Ende)	Die Position in `cssRules`, an der die Regel eingefügt wird. Ohne Angabe wird die Regel angehängt. Ist der Index größer als die Anzahl der Regeln, wird ein `IndexSizeError` geworfen.

Rückgabewert

Typ

number

Beschreibung

Immer -1, unabhängig davon, an welcher Stelle die Regel eingefügt wurde. Den tatsächlichen Index liefert nur insertRule().

Beispiele

Regel an ein bestehendes Stylesheet anhängen

// Neues <style>-Element anlegen und dessen Stylesheet verwenden
const styleEl = document.createElement('style');
document.head.append(styleEl);
const sheet = styleEl.sheet;

const result = sheet.addRule('.warnung', 'color: #b00; font-weight: bold');

console.log(result);
console.log(sheet.cssRules[0].cssText);

-1 .warnung { color: rgb(187, 0, 0); font-weight: bold; }

Regel an einer bestimmten Position einfügen

const styleEl = document.createElement('style');
styleEl.textContent = 'p { margin: 0; } a { color: blue; }';
document.head.append(styleEl);
const sheet = styleEl.sheet;

// An Position 1 einfügen, also zwischen p und a
sheet.addRule('h1', 'font-size: 2rem', 1);

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

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

Altcode modernisieren: addRule durch insertRule ersetzen

const sheet = document.head.appendChild(document.createElement('style')).sheet;

// Alt:
// sheet.addRule('.box', 'padding: 1rem');

// Neu, gleiche Wirkung (Regel wird angehängt):
const addRuleCompat = (sheet, selector, style, index = sheet.cssRules.length) =>
  sheet.insertRule(`${selector} { ${style} }`, index);

const idx = addRuleCompat(sheet, '.box', 'padding: 1rem');
console.log(idx, sheet.cssRules[idx].cssText);

0 .box { padding: 1rem; }

Fehler bei ungültigem Index abfangen

const sheet = document.head.appendChild(document.createElement('style')).sheet;

try {
  sheet.addRule('.x', 'color: red', 5); // Stylesheet ist leer
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Veraltet: Die Methode existiert nur aus Kompatibilitätsgründen. In neuem Code insertRule() verwenden, denn sie ist klarer und gibt den echten Index zurück.
Rückgabewert: Es kommt immer -1 zurück. Den Wert also nicht als Index verwenden.
Anderes Standardverhalten: addRule() hängt ohne Index am Ende an. insertRule() fügt ohne Index an Position 0 ein, also am Anfang. Das ist wichtig, wenn man Altcode umstellt, weil sich sonst die Kaskade ändern kann.
Nur Stilregeln: At-Regeln wie @media lassen sich nicht sinnvoll mit getrennten Strings für Selektor und Stil angeben. Dafür insertRule() mit dem kompletten Regeltext verwenden.
Syntaxfehler: Ein ungültiger Selektor löst einen SyntaxError aus. Ein zu großer Index führt zu einem IndexSizeError.
Stylesheets von anderen Ursprüngen: Bei Stylesheets, die über <link> von einem anderen Ursprung ohne CORS geladen wurden, ist der Zugriff gesperrt. Dann wird ein SecurityError geworfen.
Sicherheit: Keine ungeprüften Nutzereingaben als Selektor oder Stil übergeben. Eingeschleustes CSS kann Inhalte verstecken oder Daten über Attribut-Selektoren und url() abgreifen.
Browser-Unterstützung: Chrome, Edge, Firefox (ab Version 68) und Safari unterstützen die Methode, sie kann aber jederzeit als Altlast gelten.

Siehe auch

CSSStyleSheet.insertRule() CSSStyleSheet.removeRule() CSSStyleSheet.deleteRule() CSSStyleSheet.cssRules CSSStyleSheet.replaceSync() CSSStyleSheet CSSStyleValue.parse()