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

CKTIS / HTML

onpopstate — tratar alterações na entrada ativa do histórico

O atributo onpopstate de body define o processador do evento popstate do objeto Window. Permite que uma página reaja à navegação pelo histórico da sessão, por exemplo com Anterior e Seguinte, e leia o estado da entrada de destino.

Versão: WHATWG HTML Living Standard; index snapshot date recorded separately

Sintaxe

<body onpopstate="handleState(event)">
window.onpopstate = handleState;

onpopstate é um atributo de processamento de eventos disponível em body, não um atributo global para elementos arbitrários. Expõe o processador popstate do objeto Window. A atribuição window.onpopstate = handleState define esse mesmo processador; não cria um segundo listener independente.

popstate está associado à navegação pelo histórico da sessão, por exemplo através de Anterior, Seguinte ou history.back(). Chamar apenas history.pushState() ou history.replaceState() não desencadeia o evento. No processador, event.state contém o estado restaurado da entrada de destino. Pode ser null, pelo que deves ter isso em conta antes de aceder às suas propriedades.

Uma atribuição posterior a window.onpopstate substitui o processador anterior, e atribuir null remove-o. Para processadores independentes, utiliza window.addEventListener('popstate', handleState). Não trates popstate como uma forma de cancelar a navegação.

O exemplo desencadeia deliberadamente um evento sintético PopStateEvent com um estado fixo. Verifica a ligação do atributo a Window, mas não altera o histórico nem testa a navegação efetiva pelo histórico. A CSP de uma aplicação pode bloquear atributos de processamento inline; nesse caso, regista o processador num script permitido.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>onpopstate demo</title>
</head>
<body onpopstate="document.getElementById('result').textContent = 'step=' + event.state.step">
  <button id="test" type="button">Test</button>
  <output id="result">Ready</output>
  <script>
    document.getElementById('test').addEventListener('click', () => {
      window.dispatchEvent(new PopStateEvent('popstate', {
        state: { step: 1 }
      }));
    });
  </script>
</body>
</html>

Resultado

step=1

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