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

CKTIS / JavaScript

Eventos de `Window`: `popstate` e `hashchange`

Usa `popstate` para ler o estado da entrada do histórico ativada e `hashchange` para detetar alterações ao fragmento do URL no mesmo documento.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

window.addEventListener("popstate", handlePopState); // PopStateEvent: event.state
window.addEventListener("hashchange", handleHashChange); // HashChangeEvent: event.oldURL, event.newURL

// Alternative: assign one handler per property.
window.onpopstate = handlePopState;
window.onhashchange = handleHashChange;

popstate e hashchange são dois eventos distintos de Window, definidos pela plataforma Web, não pelo ECMAScript. Escuta-os com window.addEventListener(). Em alternativa, usa window.onpopstate e window.onhashchange: atribuir um novo handler a uma propriedade substitui o que lhe estava anteriormente atribuído.

popstate sinaliza a ativação de outra entrada do histórico da sessão, por exemplo ao recuar ou avançar dentro do mesmo documento. PopStateEvent.state contém o valor restaurado da entrada de destino, ou null se não tiver sido guardado qualquer estado. A navegação para um fragmento no mesmo documento também pode disparar popstate. Não dependas deste evento para inicializar a vista: o navegador pode não o disparar até o utilizador interagir com a página.

hashchange sinaliza uma alteração ao fragmento do URL no mesmo documento, por exemplo ao seguir uma ligação para #details ou ao atribuir um novo fragmento a location.hash. HashChangeEvent.oldURL e HashChangeEvent.newURL são URLs completos, não apenas fragmentos. Se a mesma operação disparar os dois eventos, popstate ocorre primeiro.

history.pushState() adiciona uma entrada e history.replaceState() atualiza a entrada atual. Nenhuma destas chamadas dispara, por si só, qualquer um dos dois eventos, mesmo que altere o fragmento. Apresenta a vista inicial e atualiza-a diretamente após uma alteração bem-sucedida ao histórico no teu código. Se escutares ambos os eventos, evita aplicar duas vezes a mesma atualização.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>History events demo</title>
</head>
<body>
  <button id="run-history-demo" type="button">Run history demo</button>
  <script>
    (() => {
      const button = document.getElementById("run-history-demo");
      button.addEventListener("click", () => {
        button.remove();

        window.addEventListener("popstate", (event) => {
          console.log(`popstate: ${JSON.stringify(event.state)}`);
        }, { once: true });

        window.addEventListener("hashchange", (event) => {
          const from = new URL(event.oldURL).hash;
          const to = new URL(event.newURL).hash;
          console.log(`hashchange: ${from} -> ${to}`);
        }, { once: true });

        history.replaceState({ view: "overview" }, "", "#overview");
        history.pushState({ view: "details" }, "", "#details");
        console.log(`after writes: ${location.hash}`);
        history.back();
      }, { once: true });
    })();
  </script>
</body>
</html>

Resultado

after writes: #details
popstate: {"view":"overview"}
hashchange: #details -> #overview

Guarda o exemplo como `index.html`, serve-o por HTTP(S) e abre-o num separador de teste: o exemplo altera entradas do histórico. Abre a consola das ferramentas de programador e clica em «Run history demo» na página. As duas escritas no histórico não disparam nenhum dos eventos; no regresso assíncrono, a consola mostra o estado `overview` e a alteração do fragmento.

Lições relacionadas

  • JavaScript · Lição 36 · Intermédio · Versão: 3
  • JavaScript · Lição 37 · Intermédio · Versão: 3

Fontes