Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

history.pushState() — una voce della cronologia senza ricaricare

history.pushState() di norma aggiunge una voce alla cronologia della sessione, salva uno stato e modifica facoltativamente l’URL senza caricare un nuovo documento. L’aggiornamento dell’interfaccia resta a tuo carico.

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.pushState(state, unused[, url]);

history.pushState() è un’API del browser definita da HTML, non da ECMAScript; i motori dei browser attuali la supportano. La disponibilità di Node 24 non dimostra che l’API sia disponibile anche lì. Di norma il metodo aggiunge una voce alla cronologia della sessione, ma in un documento about:blank iniziale sostituisce la voce corrente anziché aggiungerne una nuova. In entrambi i casi restituisce undefined senza caricare un nuovo documento. history.replaceState(), invece, aggiorna la voce corrente senza aggiungerne una nuova.

state viene serializzato e non mantenuto come riferimento; puoi leggerlo tramite history.state. Le funzioni non possono essere salvate in questo modo e causano DataCloneError. Il parametro obbligatorio unused riceve normalmente ''; non imposta il titolo della pagina.

L’argomento facoltativo url può essere relativo; se lo ometti, l’indirizzo resta invariato. Nelle pagine HTTP(S) deve mantenere la stessa origine: schema, host e porta. Un URL non consentito, un documento non completamente attivo o chiamate troppo frequenti possono causare SecurityError.

La chiamata non attiva né popstate né hashchange, anche quando cambia il frammento. Aggiorna l’interfaccia autonomamente; per la navigazione Indietro/Avanti gestisci popstate e event.state. L’esempio mostra che una modifica successiva all’oggetto di input non cambia lo stato salvato.

Esempi

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

Risultato

{"page":2,"hash":"#cktis-page-2","returnsUndefined":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