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

CKTIS / JavaScript

Ciclo de vida da página: visibilidade, saída e regresso

Distingue um separador oculto, uma tentativa de sair da página e um restauro a partir da cache de navegação, para guardar, avisar ou retomar tarefas no momento certo.

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

Sintaxe

document.addEventListener('visibilitychange', onVisibilityChange); // Read document.visibilityState or document.hidden.
window.addEventListener('beforeunload', onBeforeUnload); // Register only while unsaved changes exist.
window.removeEventListener('beforeunload', onBeforeUnload); // Remove the same listener once changes are saved or discarded.
window.addEventListener('pagehide', onPageHide); // Read event.persisted.
window.addEventListener('pageshow', onPageShow); // Read event.persisted.

Estes quatro eventos pertencem à plataforma Web, não ao ECMAScript 2024. O suporte e o comportamento variam consoante o navegador e a situação. Não pressuponhas que os quatro eventos vão ocorrer numa ordem fixa.

Escuta visibilitychange em document. Este evento não é cancelável. Lê document.visibilityState (visible ou hidden) ou o booleano document.hidden. Mudar de separador pode ocultar a página sem a abandonar. Guarda o estado à medida que o trabalho avança e usa a transição para hidden como o melhor sinal para uma última gravação ou para suspender tarefas, não como prova de que a sessão terminou.

Em window, beforeunload é um BeforeUnloadEvent cancelável associado a uma tentativa de sair da página, recarregá-la ou fechá-la. Para pedir confirmação, chama event.preventDefault() e atribui uma cadeia não vazia a event.returnValue para compatibilidade com navegadores antigos. Devolver um valor na função de tratamento só funciona com onbeforeunload, não com addEventListener(). A caixa de diálogo exige uma interação prévia adequada do utilizador (sticky activation); o navegador pode suprimi-la e escolhe o texto. Regista a função de escuta apenas enquanto houver alterações por guardar e remove-a depois de as guardar ou descartar: pode impedir a utilização da bfcache, nomeadamente no Firefox.

pagehide e pageshow são eventos PageTransitionEvent não canceláveis em window. Ao sair, pagehide com event.persisted === true indica que o navegador pretende manter o documento em memória para a navegação para trás ou para a frente (bfcache), mas não garante o restauro. false indica que não pretende mantê-lo. Usa pagehide para suspender recursos, não para guardar dados críticos: tanto este evento como beforeunload podem não ocorrer, por exemplo se um sistema operativo móvel terminar o navegador em segundo plano.

No carregamento inicial, pageshow ocorre depois de load e tem persisted === false. O valor true indica que o mesmo documento foi realmente restaurado a partir da bfcache: retoma as tarefas suspensas e atualiza dados que possam estar desatualizados. pageshow não significa que o utilizador veja a página; pode ocorrer num separador em segundo plano.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Page lifecycle events</title>
</head>
<body>
  <label><input id="dirty" type="checkbox" autocomplete="off"> Simulate unsaved changes</label>
  <script>
    const dirty = document.getElementById('dirty');

    function warn(event) {
      console.log('beforeunload');
      event.preventDefault();
      event.returnValue = 'unsaved'; // Legacy compatibility, not dialog text.
    }

    dirty.addEventListener('change', () => {
      if (dirty.checked) {
        window.addEventListener('beforeunload', warn);
      } else {
        window.removeEventListener('beforeunload', warn);
      }
    });

    document.addEventListener('visibilitychange', () => {
      console.log(`visibilitychange: ${document.visibilityState}`);
    });
    for (const type of ['pagehide', 'pageshow']) {
      window.addEventListener(type, (event) => {
        console.log(`${type}: persisted=${event.persisted}`);
      });
    }
    console.log('ready');
  </script>
</body>
</html>

Resultado

ready

Then, for example, after switching away from the tab and back:
visibilitychange: hidden
visibilitychange: visible

Other lines (not guaranteed and not in a fixed cross-event order):
beforeunload
pagehide: persisted=true
pageshow: persisted=true

A dispatched page transition event can also report persisted=false.

Abre o exemplo como página HTML no navegador e consulta a consola. `ready` aparece logo; as mensagens seguintes dependem das tuas ações e do navegador. A caixa de seleção simula alterações por guardar, mas não guarda nada.

Lições relacionadas

  • JavaScript · Lição 35 · Avançado · Versão: 4

Fontes