CKTIS / JavaScript
Visibilidade do documento: `Document.hidden` e `visibilitychange`
Consulta a visibilidade atual do documento com `document.hidden` e reage às alterações com `visibilitychange`, sem fazer verificações periódicas.
Versão: Current web platform; runtime support varies
Sintaxe
document.hidden
document.visibilityState
document.addEventListener("visibilitychange", listener)
document.removeEventListener("visibilitychange", listener)document.hidden é uma propriedade booleana só de leitura. Tem o valor true quando document.visibilityState é "hidden" e false quando é "visible". Um separador em segundo plano ou uma janela minimizada são situações comuns em que o documento é considerado oculto. O estado não indica se a página tem o foco, se um elemento específico está visível ou se alguém está a olhar para a página.
O navegador dispara visibilitychange em document depois de o estado mudar em qualquer um dos sentidos. É um Event genérico que se propaga para cima e não pode ser cancelado. Não contém o novo estado: lê a propriedade na função que escuta o evento. Registar a função não a executa logo; lê o estado inicial separadamente. Para deixar de escutar o evento, passa a mesma função a removeEventListener.
Podes, por exemplo, suspender atualizações desnecessárias da interface enquanto o documento está oculto e retomá-las quando voltar a estar visível. A passagem a "hidden" não significa que a página foi fechada, nem deves contar com tempo suficiente para o código concluir o trabalho. Esta API faz parte da plataforma Web, não do ECMAScript. A sua disponibilidade depende do ambiente de execução.
Exemplos
const stopVisibilityLog = (() => {
const hasDocument = typeof document !== "undefined";
const page = hasDocument ? document : new EventTarget();
let simulatedHidden = false;
if (!hasDocument) {
// Node.js fixture: simulate visibility without a browser document.
Object.defineProperty(page, "hidden", { get: () => simulatedHidden });
}
const logVisibility = () => {
console.log(page.hidden ? "hidden" : "visible");
};
page.addEventListener("visibilitychange", logVisibility);
logVisibility();
const stop = () => {
page.removeEventListener("visibilitychange", logVisibility);
};
if (!hasDocument) {
const changeVisibility = (hidden) => {
simulatedHidden = hidden;
page.dispatchEvent(new Event("visibilitychange", { bubbles: true }));
};
changeVisibility(true);
changeVisibility(false);
stop();
changeVisibility(true); // No log after removing the listener.
}
return stop;
})();Resultado
visible hidden visible
Executa o código uma vez na consola do navegador com a página visível. Muda para outro separador e volta ao primeiro. O resultado apresentado pressupõe exatamente estas duas alterações após a leitura inicial. Chama `stopVisibilityLog()` para parar o registo. Em Node.js, o exemplo simula as alterações de visibilidade sem recorrer a um documento do navegador.
Lições relacionadas
- JavaScript · Lição 27 · Intermédio · Versão: 3
- JavaScript · Lição 29 · Intermédio · Versão: 3
- JavaScript · Lição 31 · Intermédio · Versão: 3