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

CKTIS / JavaScript

Encontrar um elemento por ID e reagir à visibilidade do documento

Encontra um elemento com `getElementById()`, consulta a visibilidade através de `document.hidden` e atualiza a interface ao receber `visibilitychange`.

Versão: Current web platform; runtime support varies

Sintaxe

// Browser DOM and HTML APIs; support depends on the browser, not on the ECMAScript edition.
document.getElementById(id) // Element | null
// Read-only visibility properties:
document.hidden // boolean
document.visibilityState // "hidden" | "visible"
// Register and later remove the same listener:
document.addEventListener("visibilitychange", handler)
document.removeEventListener("visibilitychange", handler)

document.getElementById(id) recebe o valor do ID sem o prefixo # e distingue maiúsculas de minúsculas. Devolve o Element correspondente na árvore do documento ou null se não o encontrar. Os ID devem ser únicos; quando há duplicados, é devolvido o primeiro na ordem da árvore. Procura o elemento depois de o inserires e verifica o resultado antes de acederes às propriedades: ler uma propriedade de null provoca um TypeError.

document.hidden é uma propriedade booleana só de leitura, equivalente a document.visibilityState === "hidden". O estado do documento é "hidden" ou "visible" e pode mudar, por exemplo, quando mudas de separador. Não indica se um determinado elemento está na área visível nem se a página tem o foco. HTMLElement.hidden aplica-se a um único elemento e não altera o estado de visibilidade do documento.

O navegador dispara visibilitychange em document após a mudança de estado. É um Event que não pode ser cancelado e não inclui o novo estado; lê-o no documento dentro da função de tratamento. Regista essa função e chama-a uma vez para inicializar a interface. Ao desmontares um componente, remove o ouvinte do mesmo documento com a mesma função e o mesmo valor de capture.

Suspende tarefas desnecessárias enquanto o documento estiver oculto, mas não uses esse estado como prova de que a página foi abandonada, de que o utilizador está atento ou de que tem autorização. Estas API são da plataforma Web, não do ECMAScript 2024. Um ambiente sem DOM de navegador pode não disponibilizar document; o suporte varia consoante o ambiente de execução.

Exemplos

(() => {
  function mount(document) {
    const id = "cktis-page-visibility-status";
    const status = document.createElement("p");
    status.id = id;
    document.body.append(status);

    function render(event) {
      const element = document.getElementById(id);
      if (element === null) return;

      element.textContent = document.hidden ? "hidden" : "visible";
      if (event) console.log(element.textContent);
    }

    document.addEventListener("visibilitychange", render);
    render();
    console.log("ready");
  }

  if (typeof document !== "undefined") {
    mount(document);
    return;
  }

  // Node.js fixture: model only the document operations used above.
  class TestDocument extends EventTarget {
    #elements = [];
    #hidden = false;

    body = { append: (element) => this.#elements.push(element) };

    createElement(tagName) {
      return { tagName, id: "", textContent: "" };
    }

    getElementById(id) {
      return this.#elements.find((element) => element.id === id) ?? null;
    }

    get hidden() {
      return this.#hidden;
    }

    setHidden(hidden) {
      if (this.#hidden === hidden) return;
      this.#hidden = hidden;
      this.dispatchEvent(new Event("visibilitychange"));
    }
  }

  const testDocument = new TestDocument();
  mount(testDocument);
  testDocument.setHidden(true);
  testDocument.setHidden(false);
})();

Resultado

ready
hidden
visible

Cola o código uma vez na consola de um novo separador ativo com `about:blank`. Confirma que aparece `ready`, muda de separador, espera um instante e volta. Se o navegador comunicar ambas as transições, a consola mostra `hidden` e depois `visible`, e o parágrafo volta a mostrar `visible`. Recarrega o separador para repor o exemplo. Para verificares a função de tratamento em Node.js, guarda o código como `main.js` e executa `node main.js`; um documento de teste simula ambas as transições.

Lições relacionadas

  • JavaScript · Lição 13 · Avançado · Versão: 4

Fontes