PopStateEvent.hasUAVisualTransition — Eigenschaft · JavaScript-Referenz

Signatur

PopStateEvent.hasUAVisualTransition

Beschreibung

Die Eigenschaft hasUAVisualTransition des PopStateEvent-Interfaces ist true, wenn der User Agent (also der Browser) die Navigation schon selbst animiert hat, bevor das popstate-Ereignis ausgelöst wurde. Typisch ist die Wisch-Geste für „Zurück“ oder „Vorwärts“ auf Mobilgeräten oder Trackpads: Der Browser zeigt dabei eine Vorschau der vorherigen Seite und schiebt sie ins Bild.

Nützlich ist das vor allem für Single-Page-Anwendungen, die Seitenwechsel selbst animieren, zum Beispiel mit der View Transitions API. Hat der Browser schon animiert, würde eine zweite, eigene Animation doppelt oder ruckelig wirken. Mit hasUAVisualTransition kann die Anwendung ihre eigene Transition dann auslassen und den DOM-Zustand sofort aktualisieren.

Der Wert ist schreibgeschützt. Bei synthetischen Ereignissen legt man ihn über das Init-Dictionary des Konstruktors new PopStateEvent(type, { hasUAVisualTransition }) fest. Wird er dort nicht angegeben, ist er false.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Browser für diese Navigation bereits eine visuelle Transition gezeigt hat, sonst false. In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Eigene View Transition nur zeigen, wenn der Browser nicht animiert hat

const renderRoute = (state) => {
  document.querySelector('#app').textContent = `Seite: ${state?.page ?? 'start'}`;
};

window.addEventListener('popstate', (event) => {
  // Browser hat schon animiert (z. B. Wisch-Geste) → sofort aktualisieren
  if (event.hasUAVisualTransition || !document.startViewTransition) {
    renderRoute(event.state);
    return;
  }
  // Sonst eigene Animation über die View Transitions API
  document.startViewTransition(() => renderRoute(event.state));
});

Wert beim Zurück-Navigieren protokollieren

window.onpopstate = (event) => {
  console.log('State:', event.state);
  console.log('Browser-Transition:', event.hasUAVisualTransition);
};

history.pushState({ page: 'details' }, '', '?page=details');
history.back(); // programmatisch, ohne Geste

State: null Browser-Transition: false

Synthetisches Ereignis mit Init-Dictionary (z. B. für Tests)

const event = new PopStateEvent('popstate', {
  state: { page: 'profil' },
  hasUAVisualTransition: true
});

console.log(event.hasUAVisualTransition);
console.log(event.state.page);

true profil

Unterstützung prüfen

const supported = 'hasUAVisualTransition' in PopStateEvent.prototype;
console.log(supported ? 'Wird unterstützt' : 'Nicht verfügbar – Fallback auf false');

Wird unterstützt

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser (ab 123) und Safari unterstützen die Eigenschaft, Firefox bislang nicht. Dort ist der Wert undefined, verhält sich in Bedingungen also wie false. Bauen Sie die Logik deshalb als schrittweise Verbesserung auf.
Bei programmatischen Aufrufen wie history.back() oder history.go() ist der Wert normalerweise false. true kommt vor allem bei Gesten-Navigation vor, die der Browser selbst animiert.
Der Wert sagt nur aus, ob animiert wurde, nicht wie. Die Art der Browser-Animation lässt sich nicht auslesen.
Eigenschaften mit gleichem Namen gibt es auch in der Navigation API (NavigateEvent.hasUAVisualTransition). In modernen Routern ist das oft der bessere Ansatzpunkt.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung auf einem vorhandenen Ereignis wird stillschweigend ignoriert, im Strict Mode wirft sie einen TypeError.

Siehe auch

PopStateEvent PopStateEvent.state Document.startViewTransition() NavigateEvent.hasUAVisualTransition History.pushState() PageRevealEvent.viewTransition