Navigation API w nowoczesnych przeglądarkach

Navigation API to nowszy i bardziej rozbudowany zamiennik History API. Traktuje nawigacje jako obiekty pierwszej klasy, które można przechwytywać, anulować i obsługiwać za pomocą await — jest bliższe temu, jak SPA rzeczywiście muszą obsługiwać routing w 2024 roku.

window.navigation udostępnia listę wpisów, bieżący wpis oraz zdarzenie navigate. navigation.entries() zwraca każdy wpis w bieżącej historii; navigation.currentEntry to aktywny wpis. Dla porównania History API udostępnia nieprzejrzystą długość oraz nieodczytany stan.

Należy nasłuchiwać zdarzenia navigation.addEventListener("navigate", handler), aby przechwytywać każdą nawigację w obrębie tego samego dokumentu — kliknięcia odnośników, wysyłanie formularzy, nawigację wstecz i do przodu oraz nawigację programową. Jeden punkt obsługi zastępuje niespójny zestaw przechwytywania kliknięć, popstate i detektorów wysyłania formularzy.

Wywołanie e.intercept({ handler }) przejmuje obsługę nawigacji. Handler zwraca promise; dopóki oczekuje on na rozstrzygnięcie, nawigacja jest „w toku”, a URL został już zaktualizowany. Rozwiązuje to problem wyścigu między zmianą URL a renderowaniem widoku, który wcześniej trzeba było obsługiwać osobno.

Nie wszystkie nawigacje można przechwycić (np. nawigacji między różnymi originami ani pobierania plików). Przed wywołaniem intercept należy sprawdzić e.canIntercept. Ta ochronna kontrola w jednym wierszu odróżnia nawigację SPA od rzeczywistego opuszczenia witryny na rzecz innego originu.

navigation.navigate(url, options) programowo wywołuje nawigację, tak jak kliknięcie. Zwracany obiekt zawiera promisy committed i finished, dzięki czemu można zaczekać na zmianę URL albo na pełne ukończenie handlera.

Każdy wpis nawigacji ma stabilny key (zachowywany między przeładowaniami) oraz id (unikatowy w ramach sesji). Klucza należy używać dla stanu trwałego (zapisanych pozycji przewinięcia i wersji roboczych formularzy), a id dla stanu tymczasowego. Jedyne, co History API udostępniało, było nieprzejrzystym blokiem danych.

navigation.back() i navigation.forward() to pomocnicze opakowania wokół traverseTo. Zwracają tę samą parę promisów { committed, finished }, dzięki czemu można zaczekać na zakończenie nawigacji wstecz przed wykonaniem kolejnych czynności.

Jeśli użytkownik kliknie drugi odsyłacz, gdy pierwszy jest jeszcze renderowany, trwającą nawigację można przerwać. Procedura obsługi otrzymuje obiekt AbortSignal za pośrednictwem e.signal; należy przekazać go do wywołań fetch, aby nieaktualne operacje zostały anulowane wraz z rozpoczęciem nowej nawigacji.

History API działa, ale jest niewygodne: zmiany stanu i renderowanie widoku są rozdzielone, obsługę kliknięć trzeba implementować ręcznie, koordynacja wielu odbiorników jest zawodna, a przywracanie pozycji przewijania jest niepełne. Navigation API od początku projektowano z myślą o potrzebach SPA i rozwiązuje każdy z tych problemów.

Chrome i Edge obsługują Navigation API. Safari i Firefox pozostają w tyle (na początku 2026 roku); należy dostarczać kod, który wykrywa funkcję ("navigation" in window) i w razie jej braku korzysta z History oraz popstate. Frameworki takie jak SvelteKit i TanStack Router już opakowują to wykrywanie.

W nowych projektach kierowanych przede wszystkim do użytkowników Chromium warto wdrożyć to rozwiązanie już teraz i zaakceptować fallback oparty na History. W publicznych witrynach przeznaczonych dla szerokiego grona odbiorców lepiej poczekać na obsługę w Safari i Firefoxie (albo użyć biblioteki routera, która abstrahuje oba rozwiązania). Prostota tego API jest warta oczekiwania.

Navigation API ujednolica nawigację SPA za pomocą pojedynczego zdarzenia navigate, oferując semantykę przechwytywania i przerywania, stabilne klucze poszczególnych wpisów oraz oczekiwanie na asynchroniczne procedury obsługi. Zastępuje połączenie History, popstate i ręcznego przechwytywania kliknięć. Obecnie jest obsługiwane w przeglądarkach Chromium; do czasu nadrobienia zaległości przez Safari i Firefox należy wykrywać dostępność funkcji i stosować fallback oparty na History w kodzie wieloprzeglądarkowym.