NavigationActivation — Schnittstelle · JavaScript-Referenz

Signatur

interface NavigationActivation

Beschreibung

NavigationActivation gehört zur Navigation API und beschreibt, wie das aktuelle Dokument erreicht wurde (bzw. bei pageswap: wohin das alte Dokument gleich verlassen wird). Anders als NavigateEvent, das nur Navigationen innerhalb desselben Dokuments abdeckt, geht es hier um echte Seitenwechsel, also dokumentübergreifende Navigationen.

Man erhält eine Instanz auf zwei Wegen:

navigation.activation im neuen Dokument, zum Beispiel im Handler von pagereveal oder beim Laden der Seite.
event.activation im Event pageswap des alten Dokuments, kurz bevor es entladen wird.

Das Interface hat drei schreibgeschützte Eigenschaften:

entry: ein NavigationHistoryEntry für das Ziel der Navigation.
from: ein NavigationHistoryEntry für das vorherige Dokument. Der Wert ist null, wenn das vorherige Dokument einen anderen Ursprung hatte (Cross-Origin) oder das anfängliche about:blank war.
navigationType: einer der Werte "push", "replace", "reload" oder "traverse".

Der wichtigste Einsatzfall sind dokumentübergreifende View Transitions. Je nach Herkunfts- und Ziel-URL oder je nach Richtung (vor oder zurück) kann man unterschiedliche Animationen wählen, etwa über Typen der View Transition oder über view-transition-name für bestimmte Elemente. Außerdem eignet sich das Interface für Analytics, zum Beispiel um Reloads von normalen Seitenaufrufen zu unterscheiden.

Rückgabewert

Typ

NavigationActivation

Beschreibung

Kein Konstruktor. Instanzen liefern navigation.activation und PageSwapEvent.activation. Eigenschaften: entry (NavigationHistoryEntry), from (NavigationHistoryEntry | null) und navigationType ("push" | "replace" | "reload" | "traverse").

Beispiele

Aktivierung beim Laden der Seite auslesen

if ('navigation' in window && navigation.activation) {
  const { entry, from, navigationType } = navigation.activation;
  console.log('Typ:', navigationType);
  console.log('Ziel:', new URL(entry.url).pathname);
  console.log('Herkunft:', from ? new URL(from.url).pathname : '(unbekannt / Cross-Origin)');
}

Typ: push Ziel: /produkte/42 Herkunft: /produkte

Richtungsabhängige View Transition im neuen Dokument (pagereveal)

window.addEventListener('pagereveal', (event) => {
  if (!event.viewTransition || !navigation.activation) return;

  const { from, entry, navigationType } = navigation.activation;
  // Zurücknavigation erkennen: Traverse zu einem früheren Eintrag
  const isBack = navigationType === 'traverse' && from && entry.index < from.index;

  event.viewTransition.types.add(isBack ? 'slide-back' : 'slide-forward');
});

Übergang im alten Dokument vorbereiten (pageswap)

window.addEventListener('pageswap', (event) => {
  if (!event.viewTransition || !event.activation) return;

  const targetUrl = new URL(event.activation.entry.url);
  const match = targetUrl.pathname.match(/^\/produkte\/(\d+)$/);
  if (!match) return;

  // Nur das angeklickte Vorschaubild bekommt einen gemeinsamen Namen
  const img = document.querySelector(`#produkt-${match[1]} img`);
  if (img) {
    img.style.viewTransitionName = 'produktbild';
    // Nach dem Snapshot wieder aufräumen (wichtig bei bfcache)
    event.viewTransition.finished.then(() => {
      img.style.viewTransitionName = '';
    });
  }
});

Reloads für Analytics herausfiltern

const type = navigation?.activation?.navigationType ?? 'unbekannt';
if (type !== 'reload') {
  navigator.sendBeacon('/analytics', JSON.stringify({
    page: location.pathname,
    navigationType: type,
  }));
}

// Wichtig · Fallstricke

Browser-Unterstützung: NavigationActivation gibt es in Chromium-Browsern ab Version 123. Firefox und Safari unterstützen es noch nicht vollständig. Prüfe die Verfügbarkeit daher immer mit 'navigation' in window und navigation.activation und plane einen Fallback ein.
from kann null sein: Das ist der Fall bei Cross-Origin-Herkunft (aus Datenschutzgründen) und beim anfänglichen about:blank. Der Code sollte diesen Fall immer abfangen.
navigation.activation kann null sein, zum Beispiel in Frames ohne passende Navigation oder in manchen Sonderfällen.
pageswap und event.activation: Hier ist der Wert null, wenn die Navigation Cross-Origin ist oder Weiterleitungen über einen fremden Ursprung laufen.
entry.index ist -1, wenn der Eintrag nicht in der aktuellen Verlaufsliste steht. Bei Richtungsvergleichen sollte das berücksichtigt werden.
bfcache: Nach der Wiederherstellung aus dem Back-Forward-Cache wird navigation.activation aktualisiert. Werte, die beim ersten Laden gespeichert wurden, können danach veraltet sein.
Das Interface ist schreibgeschützt und hat keinen Konstruktor. new NavigationActivation() wirft einen TypeError.

Siehe auch

Navigation NavigationDestination NavigationTransition AnimationTimeline NavigatorLogin