Navigation: navigate() Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die navigate() Methode der Navigation-Schnittstelle navigiert zu einer bestimmten URL und aktualisiert dabei gegebenenfalls den Zustand in der Liste der Verlaufseinträge.

Syntax

js
navigate(url)
navigate(url, options)

Parameter

url

Die Ziel-URL, zu der navigiert werden soll. Beachten Sie, dass, wenn navigate() für das navigation-Objekt eines anderen Fensters aufgerufen wird, die URL relativ zur URL des Ziel-Fensters und nicht relativ zur URL des aufrufenden Fensters aufgelöst wird. Dies entspricht dem Verhalten der History API, jedoch nicht dem Verhalten der Location API.

options Optional

Ein Optionsobjekt mit den folgenden Eigenschaften:

state Optional

Vom Entwickler definierte Informationen, die im zugehörigen NavigationHistoryEntry gespeichert werden, sobald die Navigation abgeschlossen ist, abrufbar über getState(). Dies kann jeder Datentyp sein. Sie könnten beispielsweise die Anzahl der Seitenbesuche für Analysezwecke speichern oder UI-Zustandsdetails speichern, damit die Ansicht genau so angezeigt werden kann, wie der Nutzer sie zuletzt verlassen hat. Alle im state gespeicherten Daten müssen strukturklonierbar sein.

info Optional

Vom Entwickler definierte Informationen, die an das navigate Ereignis übergeben werden, verfügbar in NavigateEvent.info. Dies kann jeder Datentyp sein. Sie könnten zum Beispiel neu navigierte Inhalte mit einer anderen Animation je nach Navigationsweise anzeigen (links wischen, rechts wischen oder nach Hause gehen). Eine Zeichenkette, die angibt, welche Animation verwendet werden soll, könnte als info übergeben werden.

history Optional

Ein enumerierter Wert, der das Verlaufverhalten dieser Navigation festlegt. Die verfügbaren Werte sind:

  • auto: Der Standardwert; wird normalerweise eine push-Navigation durchführen, kann jedoch unter besonderen Umständen eine replace-Navigation ausführen (siehe die Beschreibung des NotSupportedError unten).
  • push: Fügt einen neuen NavigationHistoryEntry zur Eintragsliste hinzu oder schlägt unter besonderen Umständen fehl (siehe die Beschreibung des NotSupportedError unten).
  • replace: Ersetzt den aktuellen NavigationHistoryEntry.

Rückgabewert

Ein Objekt mit den folgenden Eigenschaften:

committed

Ein Promise, das erfüllt wird, wenn sich die sichtbare URL geändert hat und ein neuer NavigationHistoryEntry erstellt wurde.

finished

Ein Promise, das erfüllt wird, wenn alle von dem intercept() Handler zurückgegebenen Promises erfüllt sind. Dies ist gleichbedeutend mit der Erfüllung des NavigationTransition.finished Promises, wenn das navigatesuccess Ereignis ausgelöst wird.

Eines dieser Promises wird verworfen, wenn die Navigation aus irgendeinem Grund fehlgeschlagen ist.

Ausnahmen

DataCloneError DOMException

Wird ausgelöst, wenn der state Parameter nicht strukturklonierbare Werte enthält.

SyntaxError DOMException

Wird ausgelöst, wenn der url Parameter keine gültige URL ist.

NotSupportedError DOMException

Wird ausgelöst, wenn die history Option auf push gesetzt ist und eine der folgenden speziellen Umstände zutrifft:

  • Der Browser zeigt derzeit das anfängliche about:blank Dokument an.
  • Das Schema der url ist javascript.

Beispiele

Home-Button einrichten

js
function initHomeBtn() {
  // Get the key of the first loaded entry
  // so the user can always go back to this view.
  const { key } = navigation.currentEntry;
  backToHomeButton.onclick = () => {
    navigation.traverseTo(key);
  };
}
// Intercept navigate events, such as link clicks, and
// replace them with single-page navigations
navigation.addEventListener("navigate", (event) => {
  event.intercept({
    async handler() {
      // Navigate to a different view,
      // but the "home" button will always work.
    },
  });
});

Ein intelligenter Zurück-Button

Ein von der Seite bereitgestellter "Zurück"-Button kann Sie sogar nach einem Neuladen zurückbringen, indem er die vorherigen Verlaufseinträge untersucht:

js
backButtonEl.addEventListener("click", () => {
  if (
    navigation.entries()[navigation.currentEntry.index - 1]?.url ===
    "/product-listing"
  ) {
    navigation.back();
  } else {
    // If the user arrived here in some other way
    // e.g. by typing the URL directly:
    navigation.navigate("/product-listing", { history: "replace" });
  }
});

Verwendung von info und state

js
async function navigateHandler() {
  await navigation.navigate(url, {
    info: { animation: "swipe-right" },
    state: { infoPaneOpen: true },
  }).finished;

  // Update application state
  // …
}

Spezifikationen

Specification
HTML
# dom-navigation-navigate-dev

Browser-Kompatibilität

Siehe auch