PerformanceNavigation — Schnittstelle · JavaScript-Referenz

Signatur

interface PerformanceNavigation

Beschreibung

PerformanceNavigation stammt aus der ersten Version der Navigation Timing-Spezifikation. Eine Instanz erhält man ausschließlich über die schreibgeschützte Eigenschaft window.performance.navigation, einen eigenen Konstruktor gibt es nicht. Das Objekt hat zwei Eigenschaften:

type – eine Zahl, die die Art der Navigation beschreibt: 0 (TYPE_NAVIGATE, normaler Aufruf über Link, Adresszeile, Formular oder Skript), 1 (TYPE_RELOAD, Neuladen), 2 (TYPE_BACK_FORWARD, Vor-/Zurück-Navigation im Verlauf) und 255 (TYPE_RESERVED, sonstige Fälle).
redirectCount – die Anzahl der Weiterleitungen (Redirects) bis zum aktuellen Dokument. Weiterleitungen über fremde Origins werden hier nicht mitgezählt (Wert dann 0).

Zusätzlich gibt es die Methode toJSON(), die ein einfaches Objekt mit type und redirectCount liefert.

Typische Anwendungsfälle waren das Erkennen von Seiten-Neuladevorgängen (z. B. um Formularzustände zurückzusetzen oder Analytics-Daten zu bereinigen) und das Messen von Weiterleitungsketten. Für neuen Code sollte stattdessen PerformanceNavigationTiming verwendet werden, das über performance.getEntriesByType("navigation") abgerufen wird und type als lesbaren String ("navigate", "reload", "back_forward", "prerender") liefert.

Rückgabewert

Typ

PerformanceNavigation

Beschreibung

Über performance.navigation erhält man das (einzige) PerformanceNavigation-Objekt des aktuellen Dokuments mit den Eigenschaften type (number) und redirectCount (number).

Beispiele

Instanz abrufen und Eigenschaften lesen

// Kein Konstruktor – Zugriff nur über performance.navigation
const nav = performance.navigation;

console.log(nav instanceof PerformanceNavigation);
console.log('Typ:', nav.type);
console.log('Weiterleitungen:', nav.redirectCount);
console.log(JSON.stringify(nav.toJSON()));

true Typ: 0 Weiterleitungen: 0 {"type":0,"redirectCount":0}

Neuladen der Seite erkennen (Legacy-Variante)

const describeNavigation = (type) => {
  switch (type) {
    case PerformanceNavigation.TYPE_NAVIGATE: return 'Normale Navigation';
    case PerformanceNavigation.TYPE_RELOAD: return 'Seite neu geladen';
    case PerformanceNavigation.TYPE_BACK_FORWARD: return 'Vor/Zurück im Verlauf';
    default: return 'Unbekannt';
  }
};

console.log(describeNavigation(performance.navigation.type));

Seite neu geladen // nach F5

Moderner Ersatz mit Fallback

const getNavigationType = () => {
  const [entry] = performance.getEntriesByType('navigation');
  if (entry) return entry.type; // 'navigate' | 'reload' | 'back_forward' | 'prerender'

  // Fallback für sehr alte Browser
  const legacy = performance.navigation;
  if (!legacy) return 'unbekannt';
  return ['navigate', 'reload', 'back_forward'][legacy.type] ?? 'unbekannt';
};

if (getNavigationType() === 'reload') {
  console.log('Formular-Entwurf aus sessionStorage wiederherstellen');
}

Formular-Entwurf aus sessionStorage wiederherstellen // bei Neuladen

// Wichtig · Fallstricke

Veraltet: Das Interface ist in Navigation Timing Level 2 als deprecated markiert. Browser unterstützen es aus Kompatibilitätsgründen noch, es kann aber künftig entfernt werden. Verwende PerformanceNavigationTiming.
type ist eine Zahl, kein String – Vergleiche wie type === 'reload' schlagen stillschweigend fehl. Nutze die Konstanten wie PerformanceNavigation.TYPE_RELOAD.
redirectCount zählt nur Weiterleitungen innerhalb derselben Origin; bei Cross-Origin-Redirects ist der Wert 0.
Ein Wiederherstellen aus dem Back/Forward-Cache (bfcache) löst keine neue Navigation aus – die Werte bleiben unverändert. Für bfcache-Erkennung das pageshow-Event mit event.persisted verwenden.
In Web Workern ist performance.navigation nicht verfügbar.

Siehe auch

Performance PerformanceSoftNavigation PerformanceTimingConfidence PerformanceNavigationTiming PerformancePaintTiming