Navigation : méthode navigate()

Syntaxe

navigate(url)
navigate(url, options)

Paramètres

url

L'URL de destination vers laquelle naviguer. Notez que lorsque vous appelez navigate() sur l'objet navigation d'une autre fenêtre, l'URL est résolue par rapport à l'URL de la fenêtre cible, et non par rapport à l'URL de la fenêtre appelante. Cela correspond au comportement de l'API History, mais pas au comportement de l'API Location. Notez également que les URL javascript: ne sont pas autorisées pour des raisons de sécurité.

options Facultatif

Un objet d'options contenant les propriétés suivantes :

state Facultatif

L'information définie par le·la développeur·euse à stocker dans l'entrée d'historique associée NavigationHistoryEntry une fois la navigation terminée, récupérable par getState(). Cela peut être de n'importe quel type de données. Par exemple, vous pouvez souhaiter stocker un compteur de visites de page à des fins d'analyse, ou stocker les détails de l'état de l'interface utilisateur afin que la vue puisse être affichée exactement comme l'utilisateur·ice l'a laissée. Toutes les données stockées dans state doivent être structurées et clonables.

info Facultatif

L'information définie par le·la développeur·euse à transmettre à l'évènement navigate, rendue disponible dans NavigateEvent.info. Cela peut être de n'importe quel type de données. Par exemple, vous pouvez souhaiter afficher le contenu nouvellement navigué avec une animation différente selon la manière dont il a été navigué (glisser vers la gauche, glisser vers la droite ou aller à l'accueil). Une chaîne de caractères indiquant quelle animation utiliser peut être transmise dans info.

history Facultatif

Une valeur énumérée qui définit le comportement de l'historique pour cette navigation. Les valeurs disponibles sont :

• auto : La valeur par défaut ; effectue généralement une navigation push mais effectue une navigation replace dans des circonstances particulières (voir la description de NotSupportedError ci-dessous).
• push : ajoute une nouvelle NavigationHistoryEntry à la liste des entrées, ou échoue dans des circonstances particulières (voir la description de NotSupportedError ci-dessous).
• replace : remplace l'actuelle NavigationHistoryEntry.

Valeur de retour

Un objet avec les propriétés suivantes :

committed

Une promesse (Promise qui est complétée lorsque l'URL visible a changé et qu'une nouvelle NavigationHistoryEntry a été créée.

finished

Une promesse (Promise) qui est complétée lorsque toutes les promesses retournées par le gestionnaire intercept() sont complétées. Cela équivaut à la promesse NavigationTransition.finished se complétant, lorsque l'évènement navigatesuccess se déclenche.

Chaque promesse se rompt si la navigation a échoué pour une raison quelconque.

Exceptions

DataCloneError DOMException

Levé si le paramètre state contient des valeurs qui ne sont pas clonables de manière structurée.

InvalidStateError DOMException

Levé si le document n'est pas actuellement actif.

SyntaxError DOMException

Levé si le paramètre url n'est pas une URL valide.

NotSupportedError DOMException

Levé si :

• L'option history est définie sur push, et le navigateur affiche actuellement le document initial about:blank.
• Le schéma de l'URL est javascript.

Exemples

Configurer le bouton d'accueil

function initBoutonAccueil() {
  // Obtient la clé de la première entrée chargée
  // alors l'utilisateur·ice peut toujours revenir en arrière de cette
  // vue.
  const { key } = navigation.currentEntry;
  backToHomeButton.onclick = () => {
    navigation.traverseTo(key);
  };
}
// Intercepte les évènements de navigation, tels que les clics sur les
// liens, et les remplace par des navigations sur une seule page
navigation.addEventListener("navigate", (event) => {
  event.intercept({
    async handler() {
      // Navigue à une vue différente,
      // mais le bouton « accueil » fonctionne toujours.
    },
  });
});

Bouton de retour intelligent

Un bouton « retour » fourni par la page peut vous ramener en arrière, même après un rechargement, en inspectant les entrées d'historique précédentes :

backButtonEl.addEventListener("click", () => {
  if (
    navigation.entries()[navigation.currentEntry.index - 1]?.url ===
    "/product-listing"
  ) {
    navigation.back();
  } else {
    // Si l'utilisateur·ice est arrivé·e ici d'une autre manière
    // par exemple en tapant l'URL directement :
    navigation.navigate("/product-listing", { history: "replace" });
  }
});

Utiliser l'information et l'état

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

  // Met à jour l'état de l'application
  // …
}

Spécifications

Compatibilité des navigateurs

Voir aussi

• Routage moderne côté client : l'API Navigation ^(angl.)
• Présentation de l'API Navigation ^(angl.)