L’API Navigation des navigateurs modernes

L’API de navigation est un remplacement plus récent et plus puissant de l’API d’historique. Elle traite les navigations comme des objets de premier ordre que vous pouvez intercepter, annuler et attendre — ce qui correspond davantage à la façon dont les SPA doivent gérer le routage en 2024.

window.navigation expose la liste des entrées, l’entrée actuelle et l’événement de navigation. navigation.entries() renvoie chaque entrée de l’historique actuel ; navigation.currentEntry désigne l’entrée active. Comparez cela à la longueur opaque et à l’état illisible de l’API d’historique.

Écoutez navigation.addEventListener("navigate", handler) pour intercepter toute navigation au sein du même document — clics sur les liens, envois de formulaires, navigations arrière ou avant et navigations programmatiques. Un seul point d’accroche remplace l’assemblage disparate de l’interception des clics, de l’événement de navigation dans l’historique et des écouteurs d’envoi de formulaires.

L’appel à e.intercept({ handler }) prend en charge la navigation. Le gestionnaire renvoie une promesse ; pendant qu’elle est en attente, la navigation est « en cours » et l’URL est déjà mise à jour. Cela résout la course traditionnelle entre le changement d’URL et l’affichage de la vue.

Toutes les navigations ne peuvent pas être interceptées (navigations inter-origines, téléchargements). Vérifiez e.canIntercept avant d’appeler intercept. Cette protection préventive tient en une ligne et distingue une navigation de SPA d’un véritable départ vers une autre origine.

navigation.navigate(url, options) déclenche programmatiquement une navigation, comme le ferait un clic. L’objet renvoyé contient les promesses committed et finished, ce qui vous permet d’attendre la modification de l’URL ou la fin complète du gestionnaire.

Chaque entrée de navigation possède une key stable (qui persiste entre les rechargements) et un id propre à la session. Utilisez la clé pour l’état persistant (positions de défilement enregistrées, brouillons de formulaires) et l’identifiant pour l’état transitoire. Le seul état de l’API d’historique était un bloc opaque.

navigation.back() et navigation.forward() sont des enveloppes pratiques autour de traverseTo. Elles renvoient la même paire de promesses (navigation validée et terminée), ce qui vous permet d’attendre la navigation arrière avant d’effectuer le travail suivant.

Si l’utilisateur clique sur un deuxième lien alors que le premier est encore en cours d’affichage, la navigation en cours peut être annulée. Le gestionnaire reçoit un AbortSignal via e.signal ; transmettez-le aux appels de récupération afin que le travail obsolète soit annulé au début de la nouvelle navigation.

L’API d’historique fonctionne, mais elle est peu pratique : les changements d’état et le rendu de la vue sont découplés, la gestion des clics est manuelle, la coordination de plusieurs écouteurs est fragile et la restauration du défilement est incomplète. L’API de navigation a été conçue dès le départ pour les besoins des SPA et répond à chacun de ces problèmes.

Chrome et Edge prennent en charge l’API de navigation. Safari et Firefox sont en retard (début 2026) ; déployez un code qui détecte la fonctionnalité ("navigation" in window) et utilise une solution de repli fondée sur l’historique et les changements d’état lorsqu’elle est indisponible. Des frameworks comme SvelteKit et TanStack Router encapsulent déjà cette détection.

Pour les nouveaux projets destinés en priorité aux utilisateurs de Chromium, adoptez-la dès maintenant et acceptez la solution de repli fondée sur l’historique. Pour les sites publics destinés à un large public, attendez la prise en charge par Safari et Firefox (ou utilisez une bibliothèque de routage qui masque les différences). La simplicité de cette API justifie l’attente.

Quel est le principal avantage de l’événement de navigation de l’API de navigation par rapport à la combinaison de l’événement de changement d’état et de l’interception manuelle des clics utilisée avec l’API d’historique ?

L’API de navigation unifie la navigation des SPA autour d’un unique événement de navigation, avec la sémantique d’interception et d’annulation, des clés stables par entrée et l’attente asynchrone du gestionnaire. Elle remplace l’assemblage disparate entre historique, changements d’état et interception des clics. Elle est prise en charge aujourd’hui par les navigateurs Chromium ; détectez la fonctionnalité et utilisez l’historique comme solution de repli pour le code compatible avec plusieurs navigateurs, jusqu’à ce que Safari et Firefox rattrapent leur retard.