Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

history.pushState() — wpis historii bez przeładowania

history.pushState() zwykle dodaje wpis historii sesji, zapisuje stan i opcjonalnie zmienia URL bez ładowania nowego dokumentu. Interfejs trzeba aktualizować osobno.

Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Składnia

history.pushState(state, unused[, url]);

history.pushState() to przeglądarkowe API standardu HTML, nie ECMAScript; obsługują je współczesne silniki przeglądarek. Dostępność Node 24 nie dowodzi jego obsługi. Metoda zwykle dodaje wpis historii sesji, ale w początkowym dokumencie about:blank zastępuje bieżący wpis zamiast dodawać nowy. W obu przypadkach nie ładuje nowego dokumentu i zwraca undefined. Natomiast history.replaceState() aktualizuje bieżący wpis, nie dodając nowego.

state jest serializowany, a nie zachowywany jako odwołanie; odczytasz go przez history.state. Funkcje nie mogą być tak zapisane i powodują DataCloneError. Wymagany parametr unused zwyczajowo ma wartość ''; nie ustawia tytułu strony.

Opcjonalny url może być względny; bez niego adres pozostaje niezmieniony. Na stronach HTTP(S) musi zachować pochodzenie: schemat, host i port. Niedozwolony URL, nie w pełni aktywny dokument lub zbyt częste wywołania mogą spowodować SecurityError.

Wywołanie nie emituje popstate ani hashchange, nawet przy zmianie fragmentu. Interfejs aktualizuj samodzielnie; przy przechodzeniu Wstecz/Dalej obsługuj popstate i event.state. Przykład pokazuje, że późniejsza zmiana obiektu wejściowego nie zmienia zapisanego stanu.

Przykłady

(() => {
  const state = { page: 2 };
  const url = new URL(location.href);
  url.hash = 'cktis-page-2';

  const result = history.pushState(state, '', url.href);
  state.page = 99;

  console.log(JSON.stringify({
    page: history.state.page,
    hash: location.hash,
    returnsUndefined: result === undefined
  }));
})();

Wynik

{"page":2,"hash":"#cktis-page-2","returnsUndefined":true}

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła