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

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

Fontes