La Navigation API nei browser moderni

La Navigation API è un'alternativa più recente e potente alla History API. Considera le navigazioni come oggetti di prima classe che è possibile intercettare, annullare e attendere: un modello più vicino al modo in cui le SPA devono effettivamente gestire il routing nel 2024.

window.navigation espone l'elenco delle voci, la voce corrente e l'evento navigate. navigation.entries() restituisce tutte le voci della cronologia corrente; navigation.currentEntry è quella attiva. Rispetto alla History API, offre un'alternativa alla proprietà length opaca e allo stato non leggibile.

Ascolti navigation.addEventListener("navigate", handler) per intercettare ogni navigazione nello stesso documento: clic sui link, invii di moduli, navigazione avanti o indietro e navigazione programmatica. Un singolo hook sostituisce l'insieme frammentario di intercettazione dei clic, popstate e listener per l'invio dei moduli.

Chiamare e.intercept({ handler }) prende in carico la navigazione. L'handler restituisce una promise; finché è in sospeso, la navigazione è «in corso» e l'URL è già aggiornato. In questo modo si risolve il problema storico della gara tra il cambio dell'URL e il rendering della vista.

Non tutte le navigazioni possono essere intercettate, ad esempio quelle verso un'altra origine o i download. Verifichi e.canIntercept prima di chiamare intercept. Questa protezione difensiva, composta da una sola riga, distingue la navigazione della SPA dai reali allontanamenti verso un'altra origine.

navigation.navigate(url, options) attiva una navigazione programmaticamente, in modo equivalente a un clic. L'oggetto restituito contiene le promise committed e finished, che consentono di attendere il cambio dell'URL o il completamento dell'intero handler.

Ogni voce della navigazione ha una key stabile, anche dopo i ricaricamenti, e un id valido per la sessione. Utilizzi la key per lo stato persistente, come le posizioni di scorrimento salvate e le bozze dei moduli, e l'id per lo stato temporaneo. L'unico stato offerto dalla History API era un blocco di dati opaco.

navigation.back() e navigation.forward() sono wrapper di comodità per traverseTo. Restituiscono la stessa coppia di promise { committed, finished }, quindi può attendere la navigazione all'indietro prima di eseguire le operazioni successive.

Se l'utente fa clic su un secondo link mentre il primo è ancora in fase di rendering, la navigazione in corso può essere annullata. Il gestore riceve un AbortSignal tramite e.signal; lo passi alle chiamate fetch, in modo che il lavoro obsoleto venga annullato quando inizia la nuova navigazione.

La History API funziona, ma presenta diversi inconvenienti: le modifiche allo stato e il rendering della vista sono disaccoppiati, la gestione dei clic è manuale, il coordinamento tra più listener è fragile e il ripristino dello scorrimento è incompleto. La Navigation API è stata progettata fin dall'inizio per le esigenze delle SPA e risolve ciascuno di questi problemi.

Chrome ed Edge supportano la Navigation API. Safari e Firefox sono in ritardo (all'inizio del 2026); implementi il rilevamento delle funzionalità ("navigation" in window) e utilizzi History + popstate come fallback quando la funzionalità non è disponibile. Framework come SvelteKit e TanStack Router includono già un wrapper per questo rilevamento.

Per i nuovi progetti destinati principalmente a utenti Chromium, la adotti ora e accetti il fallback basato su History. Per i siti pubblici rivolti a un'ampia platea, attenda il supporto di Safari e Firefox (oppure utilizzi una libreria di routing che astragga entrambe le soluzioni). La semplicità di questa API vale l'attesa.

Qual è il principale vantaggio dell'evento navigate della Navigation API rispetto alla combinazione di popstate e intercettazione manuale dei clic prevista dalla History API?

La Navigation API unifica la navigazione delle SPA sotto un singolo evento navigate, con semantica di intercettazione e annullamento, chiavi stabili per ogni voce e attesa asincrona dei gestori. Sostituisce l'insieme disorganico di History, popstate e intercettazione dei clic. Oggi è supportata dai browser Chromium; per il codice compatibile tra browser, rilevi la funzionalità e utilizzi History come fallback finché Safari e Firefox non recupereranno il ritardo.