Element.activeViewTransition — Eigenschaft · JavaScript-Referenz

Signatur

Element.activeViewTransition

Beschreibung

Element.activeViewTransition gehört zu den elementbezogenen View-Transitions (Scoped View Transitions). Dabei startet man mit element.startViewTransition() eine Transition, die nur einen Teilbaum des DOM betrifft und nicht das ganze Dokument. Die Eigenschaft gibt das zugehörige ViewTransition-Objekt zurück, solange diese Transition auf dem Element aktiv ist. Sonst ist der Wert null.

Nützlich ist die Eigenschaft vor allem dann, wenn Sie keine eigene Referenz auf das Objekt behalten haben, das startViewTransition() zurückgibt. Das kommt z. B. vor, wenn verschiedene Komponenten oder Module Transitionen auf demselben Container auslösen. Über activeViewTransition können Sie dann prüfen, ob gerade eine Animation läuft, mit skipTransition() abbrechen, auf finished warten oder über types die Transition-Typen anpassen.

Das Gegenstück auf Dokumentebene ist Document.activeViewTransition. Es liefert die Transition, die mit document.startViewTransition() gestartet wurde. Beide Eigenschaften sind nur lesbar. Eine Zuweisung wird ignoriert und wirft im Strict Mode einen TypeError.

Rückgabewert

Typ

ViewTransition | null

Beschreibung

Das ViewTransition-Objekt der View-Transition, die gerade auf diesem Element läuft, oder null, wenn keine aktiv ist.

Beispiele

Aktive Transition eines Containers abfragen

const liste = document.querySelector('#produktliste');

if ('startViewTransition' in Element.prototype) {
  liste.startViewTransition(() => {
    liste.append(...[...liste.children].reverse());
  });

  // Direkt danach ist die Transition aktiv
  console.log(liste.activeViewTransition instanceof ViewTransition);

  await liste.activeViewTransition.finished;
  console.log(liste.activeViewTransition);
}

true null

Laufende Transition vor einer neuen überspringen

const panel = document.querySelector('.tab-panel');

const zeigeTab = (html) => {
  // Eine noch laufende Transition sofort beenden, damit sich nichts überlagert
  panel.activeViewTransition?.skipTransition();

  if (!panel.startViewTransition) {
    panel.innerHTML = html; // Fallback ohne Animation
    return;
  }
  panel.startViewTransition(() => {
    panel.innerHTML = html;
  });
};

document.querySelectorAll('[data-tab]').forEach((btn) => {
  btn.addEventListener('click', () => {
    zeigeTab(`<p>Inhalt von ${btn.dataset.tab}</p>`);
  });
});

Auf das Ende warten, ohne die Referenz weiterzugeben

// Modul A startet die Transition
const karte = document.querySelector('#karte');
karte.startViewTransition?.(() => karte.classList.toggle('erweitert'));

// Modul B hat keine Referenz, reagiert aber trotzdem auf das Ende
const warteAufTransition = async (el) => {
  const vt = el.activeViewTransition;
  if (!vt) return 'keine Transition aktiv';
  try {
    await vt.finished;
    return 'Transition abgeschlossen';
  } catch {
    return 'Transition abgebrochen';
  }
};

console.log(await warteAufTransition(karte));

Transition abgeschlossen

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft ist experimentell und bisher nur in Chromium-basierten Browsern verfügbar. Prüfen Sie die Unterstützung vorher, z. B. mit 'activeViewTransition' in Element.prototype, und nutzen Sie optionale Verkettung (el.activeViewTransition?.skipTransition()).
Der Wert gehört zu genau dem Element, auf dem startViewTransition() aufgerufen wurde. Auf Kind- oder Elternelementen liefert die Eigenschaft null. Transitionen des ganzen Dokuments finden Sie über document.activeViewTransition.
Startet man auf demselben Element eine neue Transition, wird die laufende abgebrochen. Deren finished-Promise wird trotzdem erfüllt, ready kann dagegen abgelehnt werden. Fangen Sie Ablehnungen deshalb mit try/catch ab.
Sobald die Transition endet, ist der Wert wieder null. Wenn Sie das Objekt länger brauchen, speichern Sie es in einer Variablen.
Eine Transition läuft nur, wenn das Element gerendert wird, also nicht bei display: none. Außerdem sollte der Bereich einen eigenen Stapelkontext haben. Sonst wird die Transition eventuell sofort übersprungen.

Siehe auch

Element.startViewTransition() Document.activeViewTransition Document.startViewTransition() ViewTransition ViewTransition.skipTransition() ViewTransition.finished ElementInternals.ariaOrientation