Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

history.replaceState — aggiornare la voce corrente della cronologia

history.replaceState aggiorna lo stato e, facoltativamente, l’URL della voce corrente della cronologia senza ricaricare la pagina. Non aggiunge una voce e quindi non crea un passaggio aggiuntivo per il pulsante Indietro.

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

Sintassi

history.replaceState(data, unused)
history.replaceState(data, unused, url)

history.replaceState(data, unused, url) sostituisce lo stato della voce corrente; history.pushState aggiunge una voce. È un’API del browser definita da HTML, non una funzionalità di una particolare edizione di ECMAScript. La presenza di Node 24 non dimostra che sia disponibile nel browser.

Passa "" come argomento storico obbligatorio unused; non imposta il titolo. Se url viene omesso, l’indirizzo resta invariato. Il metodo restituisce undefined. Non ricarica il documento e non attiva autonomamente popstate né hashchange.

data viene sottoposto a clonazione strutturata per essere memorizzato, non a serializzazione JSON. Leggi il valore memorizzato tramite history.state; modificare in seguito l’oggetto di input non modifica il valore memorizzato. Funzioni e nodi DOM non possono essere memorizzati in questo modo e causano DataCloneError.

Le regole di riscrittura confrontano l’URL proposto con l’URL corrente del documento, non con la sua origine. Ad esempio, un documento all’indirizzo about:blank può modificare il frammento del proprio URL anche se eredita la propria origine. Un URL non consentito, un documento non completamente attivo o le limitazioni alla frequenza delle chiamate possono causare SecurityError. Usa questo metodo per correggere la vista corrente, non per creare un nuovo passaggio di navigazione.

Esempi

(() => {
  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);
  }
})();

Risultato

details
#details
true

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti