CKTIS / JavaScript
history.replaceState — atualizar a entrada atual do histórico
history.replaceState atualiza o estado e, opcionalmente, o URL da entrada atual do histórico sem recarregar a página. Não adiciona uma entrada, pelo que não cria um passo adicional para o botão Voltar.
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.replaceState(data, unused)
history.replaceState(data, unused, url)history.replaceState(data, unused, url) substitui o estado da entrada atual; history.pushState adiciona uma entrada. Esta é uma API do browser definida por HTML, não uma funcionalidade de uma edição específica do ECMAScript. A presença do Node 24 não comprova a sua disponibilidade no browser.
Passe "" como argumento histórico obrigatório unused; não define o título. Se omitir url, o endereço mantém-se. O método devolve undefined. Não recarrega o documento nem dispara, por si só, popstate ou hashchange.
data é clonado estruturalmente para armazenamento, não serializado como JSON. Leia o valor armazenado através de history.state; alterar posteriormente o objeto de entrada não altera o valor armazenado. As funções e os nós DOM não podem ser armazenados desta forma e causam DataCloneError.
As regras de reescrita comparam o URL proposto com o URL atual do documento, não com a sua origem. Por exemplo, um documento no endereço about:blank pode alterar o fragmento do seu URL mesmo que herde a sua origem. Um URL não permitido, um documento que não esteja totalmente ativo ou restrições à frequência das chamadas podem causar SecurityError. Utilize este método para corrigir a vista atual, não para criar um novo passo de navegação.
Exemplos
(() => {
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);
}
})();Resultado
details #details 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.