KeyframeEffect.getKeyframes() — Methode · JavaScript-Referenz

Signatur

KeyframeEffect.prototype.getKeyframes()

Beschreibung

Mit getKeyframes() liest du die Keyframes eines KeyframeEffect aus, also die Zwischenstände einer Animation, die mit Element.animate(), new KeyframeEffect() oder per CSS (@keyframes, CSS-Transitions) angelegt wurde. Das Ergebnis liegt immer im normalisierten Array-Format vor: ein Objekt pro Keyframe, auch wenn die Keyframes ursprünglich im Objekt-Format ({ opacity: [0, 1] }) angegeben wurden.

Jedes Keyframe-Objekt enthält:

offset: der angegebene Offset (0–1) oder null, wenn keiner angegeben wurde.
computedOffset: der tatsächlich verwendete Offset. Fehlende Offsets werden gleichmäßig zwischen den Nachbarn verteilt.
easing: die Timing-Funktion bis zum nächsten Keyframe (Standard "linear").
composite: der Composite-Modus des Keyframes ("replace", "add", "accumulate" oder "auto").
Die animierten CSS-Eigenschaften in camelCase-Schreibweise (z. B. backgroundColor). Die Werte sind immer Strings.

Typische Einsatzgebiete sind Debugging und Inspektion von CSS-Animationen, das Kopieren oder Umkehren vorhandener Keyframes für einen neuen Effekt sowie Werkzeuge wie Animations-Editoren oder Timeline-Visualisierungen. Die Methode liefert eine Kopie: Änderungen am Array wirken sich nicht auf die laufende Animation aus. Dafür gibt es setKeyframes().

Rückgabewert

Typ

Array<ComputedKeyframe>

Beschreibung

Ein neues Array von Objekten, eines pro Keyframe. Jedes Objekt enthält offset, computedOffset, easing, composite und die animierten Eigenschaften als Strings. Gibt es keine Keyframes, ist das Array leer.

Beispiele

Keyframes einer per JS erzeugten Animation auslesen

const box = document.querySelector('.box');

const animation = box.animate(
  [
    { opacity: 0 },
    { opacity: 1, offset: 0.8 },
    { opacity: 0.5 }
  ],
  { duration: 1000 }
);

const frames = animation.effect.getKeyframes();
frames.forEach(({ offset, computedOffset, opacity }) => {
  console.log(`offset=${offset} computed=${computedOffset} opacity=${opacity}`);
});

offset=null computed=0 opacity=0 offset=0.8 computed=0.8 opacity=1 offset=null computed=1 opacity=0.5

Objekt-Format wird normalisiert

const el = document.querySelector('#banner');

const effect = new KeyframeEffect(
  el,
  { transform: ['translateX(0)', 'translateX(200px)'], easing: 'ease-in' },
  800
);

console.log(effect.getKeyframes());

[ { offset: null, computedOffset: 0, easing: "ease-in", composite: "auto", transform: "translateX(0)" }, { offset: null, computedOffset: 1, easing: "ease-in", composite: "auto", transform: "translateX(200px)" } ]

CSS-Animationen der Seite inspizieren

// CSS: .spinner { animation: spin 2s linear infinite; }
//      @keyframes spin { to { transform: rotate(360deg); } }

for (const anim of document.getAnimations()) {
  if (anim instanceof CSSAnimation) {
    const frames = anim.effect.getKeyframes();
    console.log(anim.animationName, frames.length, 'Keyframes');
    console.table(frames);
  }
}

spin 2 Keyframes

Vorhandene Animation umgekehrt abspielen lassen

const card = document.querySelector('.card');
const intro = card.animate(
  [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
  { duration: 400, fill: 'forwards' }
);

const reverseKeyframes = () =>
  intro.effect
    .getKeyframes()
    .reverse()
    // offset/computedOffset entfernen, damit neu verteilt wird
    .map(({ offset, computedOffset, ...rest }) => rest);

card.addEventListener('click', () => {
  card.animate(reverseKeyframes(), { duration: 400, fill: 'forwards' });
});

// Wichtig · Fallstricke

Werte sind Strings: Auch wenn du { opacity: 0 } übergibst, liefert getKeyframes() opacity: "0". Wer rechnen will, muss erst mit parseFloat() umwandeln.
offset und computedOffset: offset ist null, wenn kein Offset angegeben wurde. Für die tatsächliche Position immer computedOffset verwenden. Wenn du Keyframes an setKeyframes() oder animate() zurückgibst, entferne computedOffset und passe offset bei Bedarf an (z. B. beim Umkehren).
Kopie statt Referenz: Das zurückgegebene Array zu ändern, beeinflusst die Animation nicht. Änderungen erst mit effect.setKeyframes() übernehmen.
CSS-Animationen: Bei @keyframes können sich die Browser unterscheiden, etwa darin, ob fehlende Start- oder End-Keyframes ergänzt werden oder ob Werte als angegebene oder berechnete Werte (z. B. rgb(...) statt Farbname) zurückkommen. Für browserübergreifenden Code nicht auf exakte Strings vergleichen.
Kurzschreibweisen: Kurzschreibweisen wie margin oder background können je nach Browser in Einzeleigenschaften aufgelöst zurückkommen.
Kompatibilität: Wird in Chrome/Edge, Firefox und Safari (ab 13.1) unterstützt. Der Composite-Wert "auto" und die Rückgabe bei CSS-Animationen können in älteren Versionen abweichen.

Siehe auch

Element.animate() Animation.effect KeyframeEffect.setKeyframes() Performance.getEntries() CSSKeyframesRule.deleteRule()