TransitionEvent.animation — Eigenschaft · JavaScript-Referenz

Signatur

TransitionEvent.animation

Beschreibung

Die Eigenschaft animation eines TransitionEvent gibt das Objekt der Web Animations API zurück, das die auslösende CSS-Transition darstellt. Das ist in der Regel eine Instanz von CSSTransition, die von Animation erbt. Die Eigenschaft ist schreibgeschützt.

Bisher lieferte ein TransitionEvent nur beschreibende Daten wie propertyName, elapsedTime und pseudoElement. Wer die laufende Transition steuern wollte (pausieren, umkehren, Zeitpunkt abfragen, auf finished warten), musste sie über element.getAnimations() heraussuchen. event.animation gibt Ihnen das passende Objekt direkt, ohne Suche und ohne Verwechslungsgefahr, wenn mehrere Transitionen gleichzeitig laufen.

Sinnvoll ist das vor allem bei transitionrun und transitionstart: Hier läuft die Transition noch, und Sie können sie über Methoden wie pause(), reverse() oder playbackRate beeinflussen. Bei transitionend und transitioncancel ist die Transition schon beendet bzw. abgebrochen. Das Objekt eignet sich dort nur noch für Abfragen wie transitionProperty oder effect.getTiming().

Rückgabewert

Typ

CSSTransition | Animation | null

Beschreibung

Das Animationsobjekt der auslösenden CSS-Transition. null, wenn keine Animation zugeordnet ist, zum Beispiel bei einem selbst erzeugten Ereignis per new TransitionEvent().

Beispiele

Laufende Transition beim Start abfragen (mit Feature-Erkennung)

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

box.addEventListener('transitionstart', (event) => {
  if (!('animation' in TransitionEvent.prototype)) {
    console.log('TransitionEvent.animation wird nicht unterstützt');
    return;
  }
  const anim = event.animation;
  console.log(anim?.constructor.name, anim?.transitionProperty, anim?.playState);
});

// Transition auslösen (CSS: .box { transition: opacity 1s; })
requestAnimationFrame(() => { box.style.opacity = '0'; });

CSSTransition opacity running

Fallback über getAnimations(), falls die Eigenschaft fehlt

const getTransition = (event) => {
  if (event.animation) return event.animation;
  // Fallback: passende CSSTransition am Element suchen
  return event.target
    .getAnimations()
    .find((a) => a.transitionProperty === event.propertyName) ?? null;
};

const panel = document.querySelector('.panel');
panel.addEventListener('transitionrun', async (event) => {
  const anim = getTransition(event);
  if (!anim) return;
  await anim.finished; // wartet auf das Ende genau dieser Transition
  console.log(`${event.propertyName} fertig`);
});

transform fertig

Transition per on-Property verlangsamen

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

menu.ontransitionstart = (event) => {
  const anim = event.animation;
  if (anim && event.propertyName === 'transform') {
    anim.playbackRate = 0.5; // halbe Geschwindigkeit
    console.log('Wiedergaberate:', anim.playbackRate);
  }
};

menu.classList.add('open');

Wiedergaberate: 0.5

Selbst erzeugtes Ereignis hat keine Animation

const evt = new TransitionEvent('transitionend', { propertyName: 'opacity', elapsedTime: 0.3 });
console.log(evt.animation ?? null);

null

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft ist neu und nicht in allen Browsern verfügbar. Prüfen Sie die Unterstützung mit 'animation' in TransitionEvent.prototype und greifen Sie ersatzweise auf element.getAnimations() zurück. Wo die Eigenschaft fehlt, liefert sie undefined, nicht null.
Zeitpunkt beachten: Bei transitionend und transitioncancel ist die Transition schon beendet bzw. abgebrochen. Ein Aufruf von play() startet sie dort in der Regel nicht sinnvoll neu.
Ereignisse steigen auf: Transition-Ereignisse von Kindelementen steigen zum Elternelement auf (Bubbling). Prüfen Sie event.target, damit Sie nicht die Animation eines Kindelements steuern.
Kurzschrift-Eigenschaften: Bei transition: all oder Kurzschriften wie margin entsteht je Einzeleigenschaft eine eigene CSSTransition mit eigenem Ereignis.
Bei synthetischen Ereignissen, also per Konstruktor erzeugt, ist der Wert null, weil ihnen keine echte Animation zugrunde liegt.

Siehe auch

TransitionEvent TransitionEvent.propertyName TransitionEvent.elapsedTime CSSTransition Animation Element.getAnimations() AnimationEvent