Animation.persist() — Methode · JavaScript-Referenz

Signatur

Animation.prototype.persist()

Beschreibung

Seit der Einführung des automatischen Entfernens ersetzter Animationen räumt der Browser beendete Animationen mit fill: "forwards" (oder "both") auf, sobald eine neuere Animation alle ihre Eigenschaften überschreibt. So entstehen keine Speicherlecks, wenn man z. B. bei jedem mousemove eine neue Animation mit element.animate() startet. Die entfernte Animation feuert ein remove-Ereignis, und ihre Eigenschaft replaceState wechselt auf "removed".

persist() schaltet dieses Verhalten für eine einzelne Animation ab: Ihr replaceState wird auf "persisted" gesetzt, und sie bleibt im Kompositionsstapel erhalten. Das ist vor allem dann nötig, wenn Animationen mit composite: "add" oder "accumulate" aufeinander aufbauen und die unteren Schichten für das Endergebnis gebraucht werden.

Man kann persist() auch nachträglich im remove-Handler (onremove) aufrufen, um eine bereits entfernte Animation wiederherzustellen. Die Methode nimmt keine Argumente entgegen und gibt nichts zurück.

Beispiele

Ersetzte Animation beibehalten

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

const first = box.animate(
  { transform: 'translateX(100px)' },
  { duration: 300, fill: 'forwards' }
);
first.persist();

const second = box.animate(
  { transform: 'translateX(200px)' },
  { duration: 300, fill: 'forwards' }
);

await second.finished;
console.log(first.replaceState);

persisted

Additive Animationen stapeln (composite: 'add')

const target = document.getElementById('target');

document.addEventListener('click', (event) => {
  // Jeder Klick verschiebt das Element additiv weiter
  const anim = target.animate(
    { transform: `translate(${event.movementX || 20}px, 0)` },
    { duration: 200, fill: 'forwards', composite: 'add' }
  );
  // Ohne persist() würde der Browser ältere Schritte entfernen
  // und die Summe der Verschiebungen ginge verloren
  anim.persist();
});

Entfernte Animation im remove-Handler wiederherstellen

const el = document.querySelector('.card');

const fade = el.animate(
  { opacity: [1, 0.5] },
  { duration: 500, fill: 'forwards' }
);

fade.addEventListener('remove', () => {
  console.log('Vorher:', fade.replaceState);
  fade.persist();
  console.log('Nachher:', fade.replaceState);
});

// Neue Animation überdeckt opacity vollständig
await fade.finished;
el.animate({ opacity: [0.5, 0.2] }, { duration: 500, fill: 'forwards' });

Vorher: removed Nachher: persisted

// Wichtig · Fallstricke

Speicherverbrauch: Dauerhafte Animationen werden nie automatisch freigegeben. Wer persist() in häufig ausgelösten Ereignissen (mousemove, scroll) aufruft, erzeugt einen wachsenden Animationsstapel. Besser ist es, den Endzustand regelmäßig mit commitStyles() ins style-Attribut zu schreiben und die Animationen danach mit cancel() abzubrechen.
Automatisch entfernt werden nur beendete Animationen mit Füllmodus, die vollständig überdeckt sind. Laufende Animationen oder solche ohne fill betrifft das nicht, dort hat persist() praktisch keine Auswirkung.
Rückgängig machen lässt sich persist() nicht, nur durch cancel().
Kompatibilität: Chrome/Edge ab 84, Firefox ab 75, Safari ab 14. In älteren Browsern fehlt die Methode. Vorher prüfen mit typeof anim.persist === 'function'.

Siehe auch

Animation Animation.replaceState Animation.commitStyles() Animation.cancel() Element.animate() new MutationObserver()