pushState i replaceState
Aktualizowanie adresu URL przeglądarki bez pełnego przeładowania strony
pushState i replaceState to bezpłatna lekcja HTML Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej HTML Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs HTML Academy zawiera 4 lekcji w sumie.
Interfejs History API
History API pozwala stronie zmienić adres URL wyświetlany na pasku adresu bez uruchamiania pełnej nawigacji. W połączeniu z renderowaniem po stronie klienta umożliwia tworzenie aplikacji jednostronicowych, które działają jak aplikacje natywne, nie tracąc możliwości tworzenia zakładek do adresów URL.
pushState
history.pushState(state, "", url) dodaje nowy wpis do historii przeglądarki. Adres URL na pasku adresu jest aktualizowany natychmiast, a żądanie sieciowe nie jest wysyłane. Użytkownik może wrócić do poprzedniego wpisu za pomocą przycisku Wstecz w przeglądarce.
history.pushState({ view: "settings" }, "", "/settings");Argument state
Pierwszy argument to dowolne dane możliwe do serializacji, dołączone do wpisu. Można je później odczytać za pomocą history.state lub w zdarzeniach popstate. Warto używać go do przekazywania stanu interfejsu (np. informacji o otwartej karcie lub pozycji przewijania), aby nawigacja wstecz mogła przywrócić dokładny widok.
Argument title
Drugi argument to tytuł wpisu. W praktyce wszystkie współczesne przeglądarki go ignorują — aby zmienić tytuł, należy bezpośrednio ustawić document.title = "...". Zgodnie z przyjętą konwencją należy przekazać pusty ciąg znaków; nie ma to żadnego efektu.
Argument url
Trzeci argument to nowy URL. Względne adresy URL są rozwiązywane względem bieżącej strony; nowy URL musi pochodzić z tego samego originu (w przeciwnym razie zostanie zgłoszony SecurityError). Przeglądarki nie pobierają tego adresu URL — pushState aktualizuje tylko pasek adresu i historię.
replaceState
history.replaceState(state, "", url) zastępuje bieżący wpis historii zamiast dodawać nowy. Należy użyć tej metody, gdy chcą Państwo zaktualizować URL bez tworzenia nowego kroku nawigacji wstecz (np. podczas aktualizowania parametrów zapytania filtra).
// Update query string in place
const url = new URL(location);
url.searchParams.set("filter", "open");
history.replaceState(null, "", url);Zastosowania pushState
Zmiany tras w SPA (kliknięcie odnośnika nawigacyjnego bez pełnego przeładowania), otwieranie modalu (aby przycisk Wstecz go zamykał), przechodzenie między krokami kreatora. Każdy istotny stan powinien być nowym wpisem historii, aby przycisk Wstecz działał zgodnie z oczekiwaniami użytkowników.
Zastosowania replaceState
Aktualizacje filtrów, sortowania i paginacji, które nie powinny zaśmiecać historii, przekierowanie po częściowym ukończeniu formularza, aktualizowanie parametrów śledzenia bez tworzenia wpisów dostępnych podczas nawigacji. Naciśnięcie przycisku Wstecz powoduje pominięcie tych „pośrednich” stanów.
Aktualizacja widoku po pushState
pushState zmienia tylko URL — kod musi osobno zaktualizować DOM. Schemat jest następujący: należy wyrenderować nową zawartość, a następnie wywołać pushState. Razem te dwie czynności zapewniają działanie SPA.
function navigate(path) {
renderPage(path);
history.pushState(null, "", path);
window.scrollTo(0, 0);
}Aktualizowanie tytułu i metadanych
Po nawigacji należy zaktualizować document.title oraz metatagi og:title, aby udostępnianie w mediach społecznościowych i tytuły kart przeglądarki odzwierciedlały bieżący widok. Pominięcie tego kroku powoduje pozostawienie pierwotnego tytułu przy kolejnych udostępnieniach — to subtelny, ale częsty błąd w SPA.
Początkowe pushState podczas wczytywania strony
Wywołanie pushState, zanim użytkownik wykona nawigację, nadpisuje początkowy wpis. Aby dołączyć stan do pierwszego wpisu strony, należy użyć replaceState — doda ono stan bez zmiany głębokości historii.
Ograniczenie bezpieczeństwa
Adresy URL przekazywane do pushState muszą pochodzić z tego samego originu. Próba wykonania pushState dla https://evil.com spowoduje zgłoszenie SecurityError. Zapobiega to fałszowaniu paska adresu przez strony w celu przekonania użytkowników, że znajdują się w innej witrynie.
Sprawdzenie wiedzy
Co robi history.replaceState, czego nie robi history.pushState?
Podsumowanie
pushState dodaje nowy wpis historii bez przeładowania strony — to podstawa routingu w SPA. replaceState aktualizuje bieżący wpis w miejscu, aby umożliwić kosmetyczne zmiany URL. Obie metody wymagają adresów URL z tego samego originu i ignorują argument title. Należy zawsze osobno aktualizować DOM oraz pamiętać o aktualizowaniu document.title i metatagów po nawigacji.
Często zadawane pytania
Czy lekcja „pushState i replaceState” jest bezpłatna?
Tak — pełny tekst „pushState i replaceState” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu HTML Academy, przejdź na CoddyKit PRO. Kurs HTML Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „pushState i replaceState”?
Aktualizowanie adresu URL przeglądarki bez pełnego przeładowania strony Ćwiczysz HTML Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć HTML Academy?
Nie wymagamy żadnego doświadczenia. HTML Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.
Ile czasu zajmuje lekcja „pushState i replaceState”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji HTML Academy?
Tak. Każda lekcja HTML Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- pushState i replaceState
- Zdarzenie popstate
- Routing oparty na haszu a routing oparty na ścieżce
- Navigation API w nowoczesnych przeglądarkach