Signatur
Beschreibung
Die schreibgeschützte Eigenschaft key eines NavigationHistoryEntry-Objekts gibt einen vom Browser erzeugten, eindeutigen String zurück. Er steht für den Platz (Slot) des Eintrags in der Verlaufsliste und nicht für den Eintrag selbst. Ist das zugehörige Dokument nicht vollständig aktiv, zum Beispiel weil es aus einem entfernten iframe stammt, ist der Wert ein leerer String "".
Wichtig ist der Unterschied zu NavigationHistoryEntry.id. Ersetzt eine Navigation den aktuellen Eintrag (navigation.navigate(url, { history: "replace" }) oder history.replaceState()), bekommt der neue Eintrag eine neue id, behält aber denselben key. Mit key sprichst du also „diese Stelle im Verlauf“ an, egal was dort gerade liegt. Mit id sprichst du genau einen bestimmten Eintrag an.
In der Praxis brauchst du key vor allem für navigation.traverseTo(key). Damit kann eine Single-Page-Anwendung gezielt zu einem gemerkten Verlaufseintrag zurückspringen, etwa mit einem „Zurück zur Übersicht“-Button, ohne neue Einträge anzulegen. Außerdem eignet sich key gut als Schlüssel für Zustände pro Verlaufsplatz, zum Beispiel Scrollpositionen oder Formulardaten.
Rückgabewert
"". Der Wert ist nur lesbar.Beispiele
Schlüssel des aktuellen Eintrags auslesen
if ('navigation' in window) {
const entry = navigation.currentEntry;
console.log('key:', entry.key);
console.log('id: ', entry.id);
console.log('url:', entry.url);
} else {
console.log('Navigation API wird nicht unterstützt');
}Gezielt zur Übersichtsseite zurückspringen (traverseTo)
// Beim Aufruf der Übersicht den Verlaufsplatz merken
let overviewKey = null;
navigation.addEventListener('currententrychange', () => {
const { pathname } = new URL(navigation.currentEntry.url);
if (pathname === '/produkte') {
overviewKey = navigation.currentEntry.key;
}
});
document.querySelector('#back-to-overview').addEventListener('click', async () => {
const exists = navigation.entries().some((e) => e.key === overviewKey);
if (overviewKey && exists) {
// Springt im Verlauf zurück, ohne einen neuen Eintrag anzulegen
await navigation.traverseTo(overviewKey).finished;
} else {
await navigation.navigate('/produkte').finished;
}
});key bleibt bei replace gleich, id ändert sich
const before = navigation.currentEntry;
await navigation.navigate(location.href + '?sort=preis', {
history: 'replace'
}).finished;
const after = navigation.currentEntry;
console.log('gleicher key:', before.key === after.key);
console.log('gleiche id: ', before.id === after.id);Scrollposition pro Verlaufsplatz speichern
const scrollPositions = new Map();
navigation.addEventListener('navigate', () => {
// Position des Eintrags speichern, der gerade verlassen wird
scrollPositions.set(navigation.currentEntry.key, window.scrollY);
});
navigation.addEventListener('currententrychange', () => {
const y = scrollPositions.get(navigation.currentEntry.key) ?? 0;
window.scrollTo(0, y);
});// Wichtig · Fallstricke
- Browser-Unterstützung: Die Navigation API gibt es in Chromium-Browsern ab Version 102. Firefox und Safari haben sie erst in neueren Versionen eingeführt. Prüfe deshalb vorher mit
'navigation' in window, ob sie verfügbar ist, und falle sonst auf die History API zurück. keyundidnicht verwechseln: Nach einer Navigation mithistory: "replace"bleibtkeygleich,idändert sich. FürtraverseTo()brauchst du immer denkey.- Leerer String: Ein Eintrag aus einem nicht vollständig aktiven Dokument, etwa einem entfernten iframe, liefert
"". Prüfe den Wert, bevor du damit arbeitest. - Ungültige Schlüssel: Ein Schlüssel wird ungültig, wenn der zugehörige Eintrag aus dem Verlauf entfernt wird, zum Beispiel weil der Nutzer zurückgeht und danach neu navigiert. Dann wird das Promise von
navigation.traverseTo()mit einerInvalidStateError-DOMExceptionabgelehnt. Prüfe den Schlüssel vorher mitnavigation.entries(). - Der Wert ist ein undurchsichtiger String. Leite kein Format daraus ab und nutze ihn nur zum Vergleichen und Wiederfinden. Er gilt nur innerhalb derselben Origin und derselben Browsersitzung.