Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

history.replaceState — aktualizacja bieżącego wpisu historii

history.replaceState aktualizuje stan i opcjonalnie URL bieżącego wpisu historii bez przeładowania strony. Nie dodaje wpisu, więc nie tworzy dodatkowego kroku dla przycisku Wstecz.

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.replaceState(data, unused)
history.replaceState(data, unused, url)

history.replaceState(data, unused, url) zastępuje stan bieżącego wpisu; history.pushState dodaje wpis. Jest to przeglądarkowe API standardu HTML, a nie funkcja konkretnej edycji ECMAScript. Obecność Node 24 nie potwierdza jego dostępności w przeglądarce.

Przekaż "" jako wymagany, historyczny argument unused; nie ustawia on tytułu. Pominięcie url zachowuje adres. Metoda zwraca undefined. Nie przeładowuje dokumentu i sama nie wywołuje popstate ani hashchange.

data podlega klonowaniu strukturalnemu do przechowywania, nie serializacji JSON. Odczytaj zapis przez history.state; późniejsza zmiana obiektu wejściowego nie zmienia zapisu. Funkcje i węzły DOM nie nadają się do takiego zapisu i powodują DataCloneError.

Reguły przepisywania adresu porównują proponowany URL z bieżącym URL-em dokumentu, a nie z jego pochodzeniem (origin). Na przykład dokument pod adresem about:blank może zmienić fragment tego URL-a, nawet jeśli dziedziczy swoje pochodzenie. Niedozwolony URL, nieaktywny w pełni dokument lub ograniczenie częstotliwości wywołań mogą spowodować SecurityError. Używaj metody do korekty bieżącego widoku, nie do tworzenia nowego kroku nawigacji.

Przykłady

(() => {
  const previousState = history.state;
  const previousURL = location.href;
  const previousLength = history.length;
  const data = { tab: "details" };
  const url = new URL(location.href);
  url.hash = "details";

  try {
    history.replaceState(data, "", url.href);
    data.tab = "changed";
    console.log(history.state.tab);
    console.log(location.hash);
    console.log(history.length === previousLength);
  } finally {
    history.replaceState(previousState, "", previousURL);
  }
})();

Wynik

details
#details
true

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

Źródła