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

CKTIS / JavaScript

visibilitychange — alterações da visibilidade do documento

O evento visibilitychange indica uma alteração na visibilidade do documento. Pode consultar o estado atual através de document.visibilityState.

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

document.addEventListener("visibilitychange", handler);

visibilitychange é um evento de document, acionado depois de o respetivo estado de visibilidade mudar. document.visibilityState devolve "visible" ou "hidden"; document.hidden é o equivalente booleano do segundo valor.

O navegador determina a visibilidade, por exemplo, quando se muda de separador ou se minimiza uma janela. O evento propaga-se para cima. Pode utilizá-lo para reduzir trabalho desnecessário numa página oculta.

O exemplo usa dispatchEvent para disparar um único evento sintético visibilitychange, sem mudar de separador nem alterar a visibilidade do documento. A função que trata o evento é executada apenas uma vez, pois é registada com once: true. Na consola, identifica o evento como synthetic e apresenta o resultado booleano (true) da verificação de que document.visibilityState tem um dos valores "visible" ou "hidden", não o próprio estado de visibilidade.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Testing a visibilitychange listener</title>
</head>
<body>
<script>
  document.addEventListener('visibilitychange', (event) => {
    // In normal use, read the current state when the browser fires this event.
    const state = document.visibilityState;
    const valid = state === 'visible' || state === 'hidden';
    console.log(`${event.type} (${event.isTrusted ? 'browser' : 'synthetic'}): valid visibilityState = ${valid}`);
  }, { once: true });

  // Exercise the listener without switching tabs or changing visibility.
  document.dispatchEvent(new Event('visibilitychange'));
</script>
</body>
</html>

Resultado

visibilitychange (synthetic): valid visibilityState = 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