Introdução à API de Visibilidade da Página

A API de Visibilidade da Página é um recurso JavaScript que permite verificar se uma aba do navegador está ativa ou oculta para o usuário. Quando a aba é minimizada ou o usuário muda para outra aba, o evento visibilitychange é acionado. Isso possibilita otimizar o desempenho, por exemplo, pausando enimações, vídeos ou requisições de polling quando a página não está visível, reduzindo consumo de recursos.

Casos de Uso Típicos

• Sliders ou carrosséis que devem avançar somente quando a página está visível.
• Aplicações de dashboard que precisam evitar atualizações de servidor em tempo real durante inatividade da aba.
• Detectar pré-renderização para cálculos precisos de visualização de páginas.

Antigamente, desenvolvedores usavam eventos onblur e onfocus para checar atividade, mas isso não indicava se a página estava oculta ao usuário. A API de Visibilidade resolve isso de forma mais confiável.

Suporte em Navegadores

A API é amplamente suportada em navegadores modernos. Versões antigas podem requerer prefixos. Exemplos de compatibilidade:

• Chrome: suporte sem prefixo desde a versão 33; anterior usa webkit.
• Firefox: suporte nativo desde a versão 18; anterior usa moz.
• Internet Explorer 10 usa prefixo ms.
• Opera 12.10+ e Safari 7+ suportam nativamente.

Propriedades do Documento

O objeto document expõe propriedades somente leitura para verificar a visibilidade:

• document.hidden: booleano que indica se a página está oculta.
• document.visibilityState: string com valores possíveis como visible (página pelo menos parcialmente visível), hidden (oculta, por exemplo, em aba de fundo), prerender (em pré-renderização) ou unloaded (descarregada).

Na maioria dos casos, document.hidden é suficiente. Para navegadores legados, é necessário tratar prefixos.

Exemplo de Código: Verificação Cross-Browser

A função abaixo localiza a propriedade hidden com suporte a prefixos:

function acharPropriedadeOculta() {
  var sufixos = ['webkit', 'moz', 'ms', 'o'];
  if ('hidden' in document) return 'hidden';
  for (var idx = 0; idx < sufixos.length; idx++) {
    var propComPrefixo = sufixos[idx] + 'Hidden';
    if (propComPrefixo in document) return propComPrefixo;
  }
  return null;
}

De forma semelhante, para visibilityState:

function obterEstadoVisibilidade() {
  var prefixos = ['webkit', 'moz', 'ms', 'o'];
  if ('visibilityState' in document) return 'visibilityState';
  for (var cont = 0; cont < prefixos.length; cont++) {
    var nomeProp = prefixos[cont] + 'VisibilityState';
    if (nomeProp in document) return nomeProp;
  }
  return null;
}

Combinando essas funções, é possível criar uma verificação segura:

function paginaEstaOculta() {
  var propriedade = acharPropriedadeOculta();
  if (!propriedade) return false;
  return document[propriedade];
}

Escutando o Evento visibilitychange

Para reagir a mudanças de visibilidade, adicione um listener ao evento visibilitychange. Um exemplo prático pausa um vídeo quando a aba fica oculta:

document.addEventListener('visibilitychange', function() {
  var video = document.getElementById('meuVideo');
  if (paginaEstaOculta()) {
    video.pause();
  } else {
    video.play();
  }
});