Navigation API

Konzepte und Verwendung

In SPAs bleibt die Seitenschablone whrend der Nutzung normalerweise gleich, und der Inhalt wird dynamisch neu geschrieben, wenn der Benutzer verschiedene Seiten oder Funktionen besucht. Infolgedessen wird im Browser nur eine einzige, individuelle Seite geladen, was die erwartete Benutzererfahrung des Navigierens zwischen verschiedenen Positionen in der Verlaufshistorie strt. Dieses Problem kann bis zu einem gewissen Grad ber die History API gelst werden, aber sie ist nicht fr die Bedrfnisse von SPAs konzipiert. Die Navigation API soll diese Lcke schlieen.

Auf die API wird ber die Eigenschaft Window.navigation zugegriffen, die eine Referenz auf ein globales Navigation Objekt zurckgibt. Jedes window Objekt hat seine eigene entsprechende navigation Instanz.

Verwalten von Navigationsvorgngen

Die navigation Schnittstelle verfgt ber mehrere zugehrige Ereignisse, wobei das navigate Ereignis das bemerkenswerteste ist. Dies wird ausgelst, wenn jegliche Art von Navigation initiiert wird, was bedeutet, dass Sie alle Seitennavigationen von einem zentralen Punkt aus steuern knnen, ideal fr die Routing-Funktionalitt in SPA-Frameworks. (Dies ist nicht der Fall bei der History API, bei der es manchmal schwierig ist, alle Navigationsvorgnge zu erkennen und zu reagieren.) Der navigate Ereignis-Handler bekommt ein NavigateEvent Objekt bergeben, das detaillierte Informationen enthlt, einschlielich Details ber das Navigationsziel, Typ, ob es POST Formulardaten oder eine Download-Anfrage enthlt und mehr.

Das NavigateEvent Objekt bietet auch zwei Methoden:

• intercept() ermglicht es Ihnen, benutzerdefiniertes Verhalten fr Navigationen zu spezifizieren und kann die folgenden Argumente verwenden:
  • Callback-Handler-Funktionen, die es Ihnen erlauben zu spezifizieren, was geschieht, wenn die Navigation festgeschrieben wird und kurz bevor sie festgeschrieben wird. Zum Beispiel knnten Sie relevante neue Inhalte in die Benutzeroberflche basierend auf dem Navigationspfad laden, oder den Browser zu einer Anmeldeseite umleiten, wenn die URL auf eine eingeschrnkte Seite verweist und der Benutzer nicht angemeldet ist.
  • Eigenschaften, die es Ihnen ermglichen, das standardmige Fokus- und Scrollverhalten des Browsers nach der Navigation zu aktivieren oder zu deaktivieren.
• scroll() ermglicht es Ihnen, das Scrollverhalten des Browsers manuell zu initiieren (z. B. zu einem Fragmentbezeichner in der URL), wenn es fr Ihren Code sinnvoll ist, anstatt darauf zu warten, dass der Browser es automatisch behandelt.

Sobald eine Navigation initiiert wird und Ihr intercept() Handler aufgerufen wird, wird eine NavigationTransition Objektinstanz erstellt (zugnglich ber Navigation.transition), die verwendet werden kann, um den Vorgang der laufenden Navigation zu verfolgen.

Wenn die von den intercept() Handler-Funktionen zurckgegebenen Versprechen erfllt werden, wird das navigatesuccess Ereignis des Navigation Objekts ausgelst, was es Ihnen ermglicht, Bereinigungscode auszufhren, nachdem eine erfolgreiche Navigation abgeschlossen wurde. Wenn sie abgelehnt werden, bedeutet dies, dass die Navigation fehlgeschlagen ist, wird stattdessen navigateerror ausgelst, was es Ihnen ermglicht, den Fehlerfall elegant zu behandeln. Es gibt auch eine finished Eigenschaft im Rckgabewert der Navigationsmethoden (wie Navigation.navigate()), die sich gleichzeitig mit den oben genannten Ereignissen erfllt oder abgelehnt wird, was einen weiteren Pfad zur Behandlung der Erfolgs- und Fehlerflle bietet.

Programmgesteuertes Aktualisieren und Durchsuchen des Navigationsverlaufs

Whrend der Benutzer durch Ihre Anwendung navigiert, fhrt jede neue aufgerufene Position zur Erstellung eines Navigationseintrags in der Historie. Jeder Eintrag in der Historie wird durch ein separates NavigationHistoryEntry Objekt dargestellt. Diese enthalten mehrere Eigenschaften wie den Schlssel des Eintrags, die URL und Statusinformationen. Sie knnen den Eintrag abrufen, auf dem sich der Benutzer gerade befindet, indem Sie Navigation.currentEntry aufrufen, und ein Array aller vorhandenen Eintrge in der Historie mit Navigation.entries(). Jedes NavigationHistoryEntry Objekt hat ein dispose Ereignis, das ausgelst wird, wenn der Eintrag nicht mehr Teil der Browserverlaufshistorie ist. Zum Beispiel, wenn der Benutzer dreimal zurckgeht und dann woanders hin navigiert, werden diese drei Eintrge in der Historie entsorgt.

Das Navigation Objekt enthlt alle Methoden, die Sie bentigen, um den Verlauf der Navigation zu aktualisieren und zu durchlaufen:

navigate()

Navigiert zu einer neuen URL und erstellt einen neuen Eintrag in der Navigation-Historie.

reload()

Ldt den aktuellen Navigationseintrag erneut.

back()

Navigiert zum vorherigen Eintrag in der Navigation-Historie, falls dies mglich ist.

forward()

Navigiert zum nchsten Eintrag in der Navigation-Historie, falls dies mglich ist.

traverseTo()

Navigiert zu einem spezifischen Navigationseintrag der Historie, der durch seinen Schlsselwert identifiziert wird, den Sie ber die entsprechende NavigationHistoryEntry.key Eigenschaft erhalten.

Jede der oben genannten Methoden gibt ein Objekt zurck, das zwei Versprechen enthlt { committed, finished }. Dies ermglicht es der aufrufenden Funktion, mit weiteren Aktionen zu warten bis:

• committed erfllt ist, was bedeutet, dass die sichtbare URL gendert wurde und ein neuer NavigationHistoryEntry erstellt wurde.
• finished erfllt ist, was bedeutet, dass alle Versprechen, die von Ihrem intercept() Handler zurckgegeben wurden, erfllt sind. Dies entspricht dem Erfllen des NavigationTransition.finished Versprechens, wenn das navigatesuccess Ereignis ausgelst wird, wie zuvor erwhnt.
• eines der beiden oben genannten Versprechen abgelehnt wird, was bedeutet, dass die Navigation aus einem bestimmten Grund fehlgeschlagen ist.

Status

Die Navigation API ermglicht es Ihnen, Status auf jedem Eintrag in der Historie zu speichern. Dabei handelt es sich um entwicklerdefinierte Informationen es kann alles sein, was Sie mchten. Zum Beispiel knnten Sie eine visitCount Eigenschaft speichern, die die Anzahl der Besuche einer Ansicht aufzeichnet, oder ein Objekt, das mehrere Eigenschaften des UI-Status enthlt, sodass der Status wiederhergestellt werden kann, wenn ein Benutzer zu dieser Ansicht zurckkehrt.

Um den Status eines NavigationHistoryEntry abzurufen, rufen Sie die getState() Methode auf. Sie ist anfangs undefined, aber wenn Statusinformationen auf dem Eintrag gesetzt werden, wird sie die zuvor gesetzten Statusinformationen zurckgeben.

Das Setzen des Status ist etwas nuancierter. Sie knnen den Wert des Status nicht abrufen und dann direkt aktualisieren die im Eintrag gespeicherte Kopie wird sich nicht ndern. Stattdessen aktualisieren Sie es, whrend Sie eine navigate() oder reload() ausfhren jede davon nimmt optional ein Optionsobjekt-Parameter, das eine state Eigenschaft enthlt, die den neuen Status enthlt, der auf den Historieneintrag gesetzt werden soll. Wenn diese Navigationen festgeschrieben werden, wird die Statusnderung automatisch bernommen.

In einigen Fllen erfolgt jedoch eine Statusnderung unabhngig von einer Navigation oder einem Neuladen zum Beispiel, wenn eine Seite ein erweiterbares/zusammenklappbares <details> Element enthlt. In diesem Fall mchten Sie mglicherweise den erweiterten/zusammengeklappten Zustand in Ihrem Historieneintrag speichern, sodass Sie diesen wiederherstellen knnen, wenn der Benutzer zur Seite zurckkehrt oder seinen Browser neu startet. Solche Flle werden mit Navigation.updateCurrentEntry() behandelt. Das currententrychange wird ausgelst, wenn die aktuelle Eintragsnderung abgeschlossen ist.

Einschrnkungen

Es gibt einige wahrgenommene Einschrnkungen bei der Navigation API:

1. Die aktuelle Spezifikation lst kein navigate Ereignis beim ersten Laden einer Seite aus. Dies knnte fr Websites, die Server-Side Rendering (SSR) verwenden, in Ordnung sein Ihr Server knnte den korrekten Startzustand zurckgeben, was der schnellste Weg ist, um Inhalte zu Ihren Benutzern zu bringen. Aber Sites, die clientseitigen Code verwenden, um ihre Seiten zu erstellen, bentigen mglicherweise eine zustzliche Funktion zur Initialisierung der Seite.
2. Die Navigation API funktioniert nur innerhalb eines einzelnen Frames der obersten Seite oder eines bestimmten <iframe>. Dies hat einige interessante Implikationen, die in der Spezifikation weiter dokumentiert sind, aber in der Praxis wird es Verwirrung bei Entwicklern reduzieren. Die vorherige History API hat mehrere verwirrende Randflle, wie etwa die Untersttzung fr Frames, die die Navigation API von Anfang an behandelt.
3. Sie knnen derzeit die Navigation API nicht verwenden, um die Historienliste programmgesteuert zu ndern oder umzustellen. Es knnte ntzlich sein, einen temporren Zustand zu haben, beispielsweise indem der Benutzer zu einem temporren Modal navigiert wird, das ihn nach einigen Informationen fragt, und dann zur vorherigen URL zurckkehrt. In diesem Fall mchten Sie den temporren Modal-Navigationseintrag lschen, damit der Benutzer den Anwendungsfluss nicht durcheinanderbringt, indem er die Vorwrts-Taste drckt und ihn erneut ffnet.

Schnittstellen

NavigateEvent

Ereignisobjekt fr das navigate Ereignis, das ausgelst wird, wenn jede Art von Navigation initiiert wird. Es bietet Zugriff auf Informationen ber diese Navigation und insbesondere auf intercept(), das es Ihnen ermglicht zu steuern, was passiert, wenn die Navigation initiiert wird.

Navigation

Ermglicht die Kontrolle ber alle Navigationsaktionen fr das aktuelle window an einem zentralen Ort, einschlielich der programmgesteuerten Initialisierung von Navigationen, der Untersuchung von Navigationseintrgen der Historie und der Verwaltung von Navigationen, wie sie stattfinden.

NavigationActivation

Reprsentiert eine krzliche Navigation ber Dokumentengrenzen hinweg. Es enthlt den Navigationstyp sowie die Historieneintrge des aktuellen und des Ziel-Dokuments.

NavigationCurrentEntryChangeEvent

Ereignisobjekt fr das currententrychange Ereignis, das ausgelst wird, wenn sich Navigation.currentEntry gendert hat. Es bietet Zugang zum Navigationstyp und zum vorherigen Historieneintrag, von dem die Navigation ausging.

NavigationDestination

Reprsentiert das Ziel, zu dem in der aktuellen Navigation navigiert wird.

NavigationHistoryEntry

Reprsentiert einen einzelnen Navigationseintrag der Historie.

NavigationPrecommitController

Definiert das Umleitungsverhalten fr einen Prcommit-Handler bei einer Navigation, wenn er in den precommitHandler Callback eines NavigateEvent.intercept() Methodeaufrufs bergeben wird.

NavigationTransition

Reprsentiert eine laufende Navigation.

Erweiterungen zu anderen Schnittstellen

Window.navigation Schreibgeschtzt

Gibt das mit dem aktuellen window verbundene Navigation Objekt zurck. Dies ist der Einstiegspunkt fr die Navigation API.

Beispiele

Umgang mit einer Navigation mittels intercept()

navigation.addEventListener("navigate", (event) => {
  // We can't intercept some navigations, e.g. cross-origin navigations.
  // Return early and let the browser handle them normally.
  if (!event.canIntercept) {
    return;
  }

  // We shouldn't intercept fragment navigations or downloads.
  if (event.hashChange || event.downloadRequest !== null) {
    return;
  }

  const url = new URL(event.destination.url);

  if (url.pathname.startsWith("/articles/")) {
    event.intercept({
      async handler() {
        // The URL has already changed, so show a placeholder while
        // fetching the new content, such as a spinner or loading page
        renderArticlePagePlaceholder();

        // Fetch the new content and display when ready
        const articleContent = await getArticleContent(url.pathname);
        renderArticlePage(articleContent);
      },
    });
  }
});

Umgang mit dem Scrollen mittels scroll()

In diesem Beispiel des Abfangens einer Navigation beginnt die handler() Funktion damit, einige Artikelinhalte abzurufen und darzustellen, um dann danach einige Sekundrinhalte abzurufen und darzustellen. Es macht Sinn, die Seite zu den Hauptartikelinhalten zu scrollen, sobald diese verfgbar sind, damit der Benutzer mit ihnen interagieren kann, statt darauf zu warten, dass auch die Sekundrinhalte gerendert werden. Um dies zu erreichen, haben wir einen scroll() Aufruf zwischen den beiden hinzugefgt.

navigation.addEventListener("navigate", (event) => {
  // Return early if we can't/shouldn't intercept
  if (
    !event.canIntercept ||
    event.hashChange ||
    event.downloadRequest !== null
  ) {
    return;
  }

  const url = new URL(event.destination.url);

  if (url.pathname.startsWith("/articles/")) {
    event.intercept({
      async handler() {
        const articleContent = await getArticleContent(url.pathname);
        renderArticlePage(articleContent);

        event.scroll();

        const secondaryContent = await getSecondaryContent(url.pathname);
        addSecondaryContent(secondaryContent);
      },
    });
  }
});

Durchlaufen zu einem spezifischen Eintrag der Historie

// On JS startup, get the key of the first loaded page
// so the user can always go back there.
const { key } = navigation.currentEntry;
backToHomeButton.onclick = () => navigation.traverseTo(key);

// Navigate away, but the button will always work.
await navigation.navigate("/another_url").finished;

Aktualisieren des Status

navigation.navigate(url, { state: newState });

Oder

navigation.reload({ state: newState });

Oder falls der Status unabhngig von einer Navigation oder einem Neuladen ist:

navigation.updateCurrentEntry({ state: newState });

Spezifikationen

Browser-Kompatibilitt

api.Navigation

api.NavigationDestination

api.NavigationHistoryEntry

api.NavigationTransition

Siehe auch

• Modern client-side routing: the Navigation API
• Explanation der Navigation API