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

CKTIS / JavaScript

hashchange — alterações do fragmento do URL em Window

O evento hashchange em window informa de uma alteração do fragmento do URL durante a navegação no mesmo documento. Disponibiliza os URLs anterior e novo, mas chamar pushState() ou replaceState() não o desencadeia por si só.

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

window.addEventListener("hashchange", handler);
window.removeEventListener("hashchange", handler);

hashchange é um evento da API Web em window, não faz parte do próprio ECMAScript. Informa de uma alteração do fragmento do URL durante a navegação no mesmo documento, por exemplo, depois de atribuir um valor diferente a location.hash, seguir uma ligação com fragmento ou recuar/avançar entre entradas relevantes do histórico.

Regista uma função com window.addEventListener("hashchange", handler). O respetivo HashChangeEvent tem as propriedades oldURL e newURL, que contêm os URLs completos antes e depois da alteração. O evento é enviado de forma assíncrona. Lê estas propriedades quando precisares dos URLs dessa alteração específica.

Chamar history.pushState() ou history.replaceState() não desencadeia por si só hashchange, mesmo que altere o fragmento. Voltar a definir o mesmo fragmento também não constitui uma alteração. Não encares este evento como uma notificação de todas as alterações do URL nem como a inicialização da vista no primeiro carregamento da página.

O exemplo escolhe um fragmento diferente e aguarda apenas um evento através de { once: true }. Compara os fragmentos obtidos a partir dos URLs do evento, pelo que os resultados esperados não dependem do URL inicial da página. Requer um ambiente de navegador; a versão de Node.js do repositório não comprova o suporte desta API.

Exemplos

(() => {
  const target = location.hash === "#cktis-a" ? "#cktis-b" : "#cktis-a";

  window.addEventListener("hashchange", (event) => {
    const before = new URL(event.oldURL);
    const after = new URL(event.newURL);
    console.log(before.hash !== after.hash);
    console.log(after.hash === target);
  }, { once: true });

  location.hash = target;
})();

Resultado

true
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