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.