CSSKeyframeRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSKeyframeRule extends CSSRule

Beschreibung

CSSKeyframeRule steht im CSS-Objektmodell (CSSOM) für einen einzelnen Block innerhalb einer @keyframes-Regel, zum Beispiel from { opacity: 0; } oder 50% { transform: scale(1.2); }. Das Interface erbt von CSSRule. Seine Eigenschaft type hat den Wert 8 (CSSRule.KEYFRAME_RULE).

Direkt erzeugen lassen sich CSSKeyframeRule-Objekte nicht, denn es gibt keinen Konstruktor. Man bekommt sie über die cssRules-Liste einer CSSKeyframesRule oder über CSSKeyframesRule.findRule(). Neue Keyframes fügt man mit CSSKeyframesRule.appendRule() hinzu.

Wichtige Eigenschaften:

keyText (string): der Keyframe-Selektor als Text, z. B. "0%", "50%" oder "0%, 100%". Man kann ihn auch neu setzen.
style (CSSStyleDeclaration, nur lesbar): die Deklarationen des Keyframes. Über dieses Objekt lassen sich einzelne Werte lesen und ändern.
Geerbt von CSSRule: cssText, parentRule (die übergeordnete CSSKeyframesRule), parentStyleSheet.

Das Interface eignet sich dafür, bestehende CSS-Animationen zur Laufzeit zu untersuchen oder zu ändern, etwa um Werte an Nutzereingaben anzupassen. Für Animationen, die vollständig per Skript gesteuert werden, ist die Web Animations API (Element.animate()) meist die bessere Wahl.

Rückgabewert

Typ

CSSKeyframeRule

Beschreibung

Instanzen bekommt man über CSSKeyframesRule.cssRules oder CSSKeyframesRule.findRule(). Einen öffentlichen Konstruktor gibt es nicht.

Beispiele

Keyframes einer Animation auslesen

// Stylesheet mit einer Animation anlegen
const style = document.createElement('style');
style.textContent = `
  @keyframes pulse {
    from { opacity: 1; }
    50%  { opacity: 0.3; transform: scale(1.1); }
    to   { opacity: 1; }
  }
`;
document.head.append(style);

const keyframes = [...style.sheet.cssRules]
  .find((rule) => rule instanceof CSSKeyframesRule && rule.name === 'pulse');

for (const frame of keyframes.cssRules) {
  // frame ist ein CSSKeyframeRule
  console.log(frame.keyText, '→', frame.style.cssText);
}

0% → opacity: 1; 50% → opacity: 0.3; transform: scale(1.1); 100% → opacity: 1;

Keyframe zur Laufzeit ändern

const findKeyframes = (name) => {
  for (const sheet of document.styleSheets) {
    let rules;
    try { rules = sheet.cssRules; } catch { continue; } // CORS-geschützte Sheets überspringen
    for (const rule of rules) {
      if (rule instanceof CSSKeyframesRule && rule.name === name) return rule;
    }
  }
  return null;
};

const pulse = findKeyframes('pulse');
const middle = pulse?.findRule('50%'); // CSSKeyframeRule oder null

if (middle) {
  middle.style.setProperty('opacity', '0.1');
  middle.keyText = '40%'; // Selektor verschieben
  console.log(middle.cssText);
}

40% { opacity: 0.1; transform: scale(1.1); }

Neuen Keyframe hinzufügen und prüfen

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

pulse.appendRule('75% { opacity: 0.6; }');
const added = pulse.findRule('75%');

console.log(added instanceof CSSKeyframeRule);
console.log(added.parentRule === pulse);
console.log(added.style.getPropertyValue('opacity'));

true true 0.6

// Wichtig · Fallstricke

Normalisierung: Browser geben from und to in keyText meist als 0% und 100% zurück. Ein Vergleich mit "from" schlägt dann fehl. findRule() akzeptiert beide Schreibweisen.
Ungültiger keyText: Ein ungültiger Selektor (z. B. "150%") löst einen SyntaxError aus.
!important wird innerhalb von Keyframes ignoriert, auch wenn man es über style.setProperty() setzt.
Laufende Animationen: Änderungen an Keyframes wirken sich in modernen Browsern auf laufende Animationen aus. Das genaue Verhalten war früher nicht einheitlich, daher sollte man es im Zielbrowser testen.
CORS: Bei Stylesheets von fremden Ursprüngen ohne passende CORS-Header wirft der Zugriff auf cssRules einen SecurityError, deshalb in try/catch einschließen.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt. Alte WebKit-Versionen kannten nur das Präfix WebKitCSSKeyframeRule.

Siehe auch

Element.animate() CSSKeyframesRule CSSFontFaceRule CSSMediaRule CSSPageRule