CKTIS / JavaScript
history.pushState() — uma entrada no histórico sem recarregar
history.pushState() normalmente adiciona uma entrada ao histórico da sessão, guarda um estado e altera opcionalmente o URL sem carregar um novo documento. A atualização da interface fica a teu cargo.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
history.pushState(state, unused[, url]);history.pushState() é uma API do browser definida por HTML, não por ECMAScript; os motores de browser atuais suportam-na. A disponibilidade do Node 24 não demonstra que esta API esteja disponível nesse ambiente. O método normalmente adiciona uma entrada ao histórico da sessão, mas num documento about:blank inicial substitui a entrada atual em vez de adicionar uma nova. Em ambos os casos, devolve undefined sem carregar um novo documento. Já history.replaceState() atualiza a entrada atual sem adicionar uma nova.
state é serializado e não mantido como referência; podes lê-lo através de history.state. As funções não podem ser guardadas desta forma e provocam DataCloneError. O parâmetro obrigatório unused recebe normalmente ''; não define o título da página.
O argumento opcional url pode ser relativo; se for omitido, o endereço mantém-se. Em páginas HTTP(S), tem de conservar a mesma origem: esquema, anfitrião e porta. Um URL não permitido, um documento que não esteja totalmente ativo ou chamadas demasiado frequentes podem provocar SecurityError.
A chamada não dispara popstate nem hashchange, mesmo que o fragmento se altere. Atualiza a interface por tua conta; para a navegação Anterior/Seguinte, trata popstate e event.state. O exemplo mostra que uma alteração posterior ao objeto de entrada não modifica o estado guardado.
Exemplos
(() => {
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
}));
})();Resultado
{"page":2,"hash":"#cktis-page-2","returnsUndefined":true}O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.