CSSKeyframesRule.appendRule() — Methode · JavaScript-Referenz

Signatur

CSSKeyframesRule.prototype.appendRule(rule)

Beschreibung

Die Methode appendRule() des Interfaces CSSKeyframesRule nimmt einen Keyframe als CSS-Text entgegen, z. B. "50% { opacity: 0.5; }", parst ihn und hängt ihn als neues CSSKeyframeRule-Objekt an die Liste cssRules einer bestehenden @keyframes-Regel an.

Das ist nützlich, wenn Animationen dynamisch aufgebaut oder angepasst werden sollen, etwa wenn Zwischenschritte aus Nutzereingaben oder Messwerten berechnet werden, ohne ein komplettes <style>-Element neu zu schreiben. Zusammen mit deleteRule() und findRule() lässt sich eine Keyframe-Animation so vollständig über das CSSOM steuern.

Wichtig: Die Reihenfolge in cssRules spielt für die Animation keine Rolle, entscheidend sind die Prozentangaben (Keyframe-Selektoren). Gibt es denselben Selektor mehrfach, gewinnt bei gleichen Eigenschaften der zuletzt angefügte Keyframe (Kaskade innerhalb von @keyframes).

Parameter

Name	Typ	Default	Beschreibung
$rule Pflicht	string		Ein Keyframe als CSS-Text, bestehend aus Keyframe-Selektor(en) und Deklarationsblock, z. B. `"from { color: red; }"`, `"25%, 75% { transform: scale(1.2); }"`.

Beispiele

Keyframe zu einer bestehenden Animation hinzufügen

// CSS im Dokument: @keyframes pulse { from { opacity: 1; } to { opacity: 0; } }
const findKeyframes = (name) => {
  for (const sheet of document.styleSheets) {
    for (const rule of sheet.cssRules) {
      if (rule instanceof CSSKeyframesRule && rule.name === name) return rule;
    }
  }
  return null;
};

const pulse = findKeyframes('pulse');
if (pulse) {
  pulse.appendRule('50% { opacity: 0.3; }');
  console.log(pulse.cssRules.length);
  console.log(pulse.cssRules[2].keyText);
}

3 50%

Animation komplett per JavaScript erzeugen

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

// Leere @keyframes-Regel anlegen
const index = sheet.insertRule('@keyframes slide {}', sheet.cssRules.length);
const slide = sheet.cssRules[index];

// Keyframes aus Daten berechnen
const steps = [0, 30, 60, 100];
steps.forEach((p, i) => {
  slide.appendRule(`${p}% { transform: translateX(${i * 50}px); }`);
});

document.querySelector('.box')?.style.setProperty('animation', 'slide 2s ease-in-out infinite');
console.log(slide.cssText);

@keyframes slide { 0% { transform: translateX(0px); } 30% { transform: translateX(50px); } 60% { transform: translateX(100px); } 100% { transform: translateX(150px); } }

Keyframe ersetzen mit deleteRule() und appendRule()

const updateKeyframe = (keyframesRule, selector, declarations) => {
  keyframesRule.deleteRule(selector); // entfernt vorhandenen Keyframe, falls vorhanden
  keyframesRule.appendRule(`${selector} { ${declarations} }`);
};

const rule = [...document.styleSheets[0].cssRules]
  .find((r) => r instanceof CSSKeyframesRule && r.name === 'pulse');

if (rule) {
  updateKeyframe(rule, '50%', 'opacity: 0.8; background: gold;');
  console.log(rule.findRule('50%').style.opacity);
}

0.8

// Wichtig · Fallstricke

Ungültiger Text: Lässt sich rule nicht als Keyframe parsen (z. B. "abc { }" oder fehlende Klammern), wird je nach Browser stillschweigend nichts eingefügt oder ein SyntaxError geworfen. Ergebnis ggf. über cssRules.length prüfen.
Cross-Origin-Stylesheets: Der Zugriff auf cssRules externer Stylesheets ohne passende CORS-Header wirft einen SecurityError. Eigene <style>-Elemente oder Constructable Stylesheets verwenden.
Laufende Animationen: Änderungen wirken sich in modernen Browsern auf laufende Animationen aus; ältere Engines übernahmen sie teils erst nach Neustart der Animation (z. B. animation-name kurz zurücksetzen).
Historie: Frühere Spezifikationsentwürfe nannten die Methode insertRule(); alte Firefox-Versionen unterstützten nur diese. In aktuellen Browsern ist appendRule() überall verfügbar.
Für rein skriptgesteuerte Animationen ist die Element.animate()-API (Web Animations) meist einfacher als CSSOM-Manipulation.

Siehe auch

Element.animate() WorkletSharedStorage.remainingBudget() CSSKeyframesRule.findRule() CSSKeyframesRule.deleteRule() CSSGroupingRule.deleteRule()