Animation.replaceState — Eigenschaft · JavaScript-Referenz

Signatur

Animation.replaceState

Beschreibung

Die Eigenschaft replaceState einer Animation gehört zum Mechanismus „automatisches Entfernen gefüllter Animationen“ (Replaceable Animations). Wenn man viele Animationen mit fill: "forwards" oder fill: "both" auf dasselbe Element und dieselben Eigenschaften anwendet, zum Beispiel bei jeder Mausbewegung, würden sich ohne diesen Mechanismus unbegrenzt viele Animationen ansammeln. Das kostet Speicher und bremst die Seite aus. Browser entfernen deshalb Animationen, die abgeschlossen sind und von neueren Animationen vollständig überdeckt werden.

Die Eigenschaft liefert einen von drei Zeichenketten-Werten:

"active": Die Animation ist aktiv oder wurde bisher nicht ersetzt. Das ist der Ausgangswert.
"removed": Der Browser hat die Animation entfernt, weil eine andere Animation sie ersetzt hat. Sie wirkt nicht mehr auf das Element, und das Ereignis remove wurde ausgelöst.
"persisted": Mit Animation.prototype.persist() wurde festgelegt, dass die Animation nicht automatisch entfernt werden darf.

Die Eigenschaft ist nützlich zur Fehlersuche und für Logik, die wissen muss, ob der Endzustand einer Animation noch sichtbar ist. Zusammen mit dem Ereignis remove und der Methode commitStyles() kann man den Endzustand einer entfernten Animation ins style-Attribut übernehmen, statt ihn zu verlieren.

Rückgabewert

Typ

"active" | "removed" | "persisted"

Beschreibung

Eine Zeichenkette mit dem aktuellen Ersetzungszustand der Animation. Die Eigenschaft ist schreibgeschützt.

Beispiele

Ersetzungszustand nach mehreren gefüllten Animationen prüfen

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

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

await Promise.all([first.finished, second.finished]);
// Kurz warten, bis der Browser das Entfernen verarbeitet hat
await new Promise(requestAnimationFrame);

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

removed active

Entfernte Animationen protokollieren (remove-Ereignis)

const target = document.querySelector('.follower');

document.addEventListener('mousemove', (e) => {
  const anim = target.animate(
    { transform: `translate(${e.clientX}px, ${e.clientY}px)` },
    { duration: 300, fill: 'forwards' }
  );

  anim.addEventListener('remove', () => {
    // An dieser Stelle gilt immer: replaceState === 'removed'
    console.log('Entfernt:', anim.replaceState);
  });
});

Entfernt: removed (wird für jede ersetzte Animation ausgegeben)

Animation mit persist() vor dem Entfernen schützen

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

const base = el.animate({ opacity: [1, 0.5] }, { duration: 500, fill: 'forwards' });
base.persist();
console.log(base.replaceState);

el.animate({ opacity: [0.5, 0.2] }, { duration: 500, fill: 'forwards' });

// Alle Animationen am Element auflisten, die noch wirken
const states = el.getAnimations().map((a) => a.replaceState);
console.log(states);

persisted ["persisted", "active"]

Endzustand vor dem Entfernen übernehmen

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

const anim = card.animate({ backgroundColor: 'gold' }, { duration: 400, fill: 'forwards' });

anim.addEventListener('remove', () => {
  if (anim.replaceState === 'removed') {
    // Berechneten Endzustand ins style-Attribut schreiben
    anim.commitStyles();
  }
});

// Wichtig · Fallstricke

Nur gefüllte, abgeschlossene Animationen werden entfernt: Eine Animation wird nur dann ersetzt, wenn sie beendet ist, einen Füllmodus hat, zur Dokument-Zeitleiste gehört und alle ihre animierten Eigenschaften von neueren Animationen überdeckt werden. Laufende oder pausierte Animationen behalten "active".
Zeitpunkt: Das Entfernen geschieht asynchron, wenn der Browser das nächste Mal die Animationen aktualisiert, also nicht gleich nach dem Aufruf von animate(). Wer replaceState synchron direkt danach liest, erhält noch "active".
Entfernt heißt nicht abgebrochen: Eine entfernte Animation löst kein cancel-Ereignis aus, und ihr playState bleibt "finished". Nur ihre Wirkung auf das Element entfällt. element.getAnimations() liefert sie nicht mehr.
Stil verloren? Wenn eine Eigenschaft nach dem Entfernen auf den Ausgangswert „zurückspringt“, sollte man im remove-Handler commitStyles() aufrufen oder die Animation mit persist() behalten. Achtung: Dauerhaft behaltene Animationen verbrauchen Speicher.
Kompatibilität: Unterstützt ab Chrome/Edge 84, Firefox 75 und Safari 14. Ältere Browser liefern undefined. Zur Merkmalserkennung eignet sich 'replaceState' in Animation.prototype.

Siehe auch

Animation.prototype.persist() Animation.prototype.commitStyles() Animation.playState Element.prototype.animate() Element.prototype.getAnimations() Animation