Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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.

Fontes