NavigationDestination.sameDocument — Eigenschaft · JavaScript-Referenz

Signatur

NavigationDestination.sameDocument

Beschreibung

Die Eigenschaft sameDocument eines NavigationDestination-Objekts sagt, ob das Navigationsziel im aktuellen Dokument bleibt. Ist sie true, wird keine neue Seite geladen. Das ist zum Beispiel bei Fragment-Navigationen (#abschnitt), bei history.pushState()/replaceState() oder bei Traversierungen zu Verlaufseinträgen desselben Dokuments der Fall. Bei false würde der Browser ein neues Dokument laden.

An das Objekt kommt man meist über event.destination im navigate-Ereignis von window.navigation. Die Eigenschaft ist in Single-Page-Anwendungen nützlich: Damit kann ein Router Navigationen im selben Dokument (etwa Sprungmarken) vom Browser erledigen lassen und nur echte Seitenwechsel über event.intercept() abfangen.

Wichtig: sameDocument beschreibt, wie der Browser ohne Eingriff navigieren würde. Wenn du eine dokumentübergreifende Navigation mit intercept() abfängst, wird sie zwar zu einer Navigation im selben Dokument. Der Wert von destination.sameDocument bleibt dabei aber false.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Ziel im aktuellen Dokument liegt, sonst false. Nur lesbar.

Beispiele

Hash-Navigation erkennen

navigation.addEventListener('navigate', (event) => {
  const { url, sameDocument } = event.destination;
  console.log(`Ziel: ${url} – selbes Dokument: ${sameDocument}`);
});

// Löst eine Navigation im selben Dokument aus
location.hash = '#kontakt';

Ziel: https://example.com/#kontakt – selbes Dokument: true

SPA-Router: nur echte Seitenwechsel abfangen

const renderRoute = async (url) => {
  const res = await fetch(`/partials${url.pathname}`);
  document.querySelector('main').innerHTML = await res.text();
};

navigation.addEventListener('navigate', (event) => {
  // Sprungmarken & Co. dem Browser überlassen
  if (event.destination.sameDocument) return;
  if (!event.canIntercept || event.downloadRequest !== null) return;

  const url = new URL(event.destination.url);
  if (url.origin !== location.origin) return;

  event.intercept({
    handler: () => renderRoute(url),
  });
});

Traversierung (Zurück/Vor) auswerten

navigation.addEventListener('navigate', (event) => {
  if (event.navigationType !== 'traverse') return;

  const dest = event.destination;
  const art = dest.sameDocument ? 'im selben Dokument' : 'mit neuem Dokument';
  console.log(`Sprung zu Verlaufsindex ${dest.index} (${art})`);
});

Sprung zu Verlaufsindex 2 (im selben Dokument)

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen werden ignoriert und werfen im Strict Mode einen TypeError.
Nicht mit intercept() verwechseln: Wird eine dokumentübergreifende Navigation abgefangen, bleibt sameDocument trotzdem false. Ob die Navigation tatsächlich abgefangen wurde, musst du selbst mitverfolgen.
Gleiche URL heißt nicht automatisch gleiches Dokument: Ein Reload (navigationType === 'reload') auf dieselbe URL liefert false.
Browser-Kompatibilität: Die Navigation API gibt es in Chromium-Browsern seit Version 102, in Firefox seit 147 und in Safari seit 26.2. Für ältere Browser vorher prüfen, z. B. mit if ('navigation' in window), und sonst auf popstate/hashchange ausweichen.
Nur in sicheren Kontexten und im Fenster-Kontext verfügbar, nicht in Workern.

Siehe auch

Navigation NavigationDestination.index NavigationDestination.id NavigationDestination.key NavigationDestination.url