Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Trouver un élément par son ID et réagir à la visibilité du document

Trouvez un élément avec `getElementById()`, lisez l’état de visibilité via `document.hidden` et actualisez l’interface lors de `visibilitychange`.

Version : Current web platform; runtime support varies

Syntaxe

// 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) prend la valeur de l’identifiant sans préfixe # et distingue les majuscules des minuscules. La méthode renvoie un Element correspondant dans l’arbre du document, ou null s’il n’y en a pas. Les identifiants doivent être uniques ; en cas de doublon, le premier élément dans l’ordre de l’arbre l’emporte. Attendez que l’élément soit inséré et vérifiez le résultat avant tout accès à une propriété : lire une propriété de null déclenche une TypeError.

document.hidden est un booléen en lecture seule, équivalent à document.visibilityState === "hidden". L’état du document vaut "hidden" ou "visible" et peut changer, par exemple, lors d’un changement d’onglet. Il n’indique ni si un élément précis est dans la zone d’affichage ni si la page a le focus. HTMLElement.hidden concerne un seul élément et ne modifie pas l’état de visibilité du document.

Le navigateur déclenche visibilitychange sur document après le changement d’état. Cet Event n’est pas annulable et ne contient pas le nouvel état ; lisez-le sur le document dans le gestionnaire. Enregistrez le gestionnaire, puis appelez-le une fois pour initialiser l’interface. Au démontage d’un composant, retirez l’écouteur du même document avec la même fonction et le même réglage capture.

Suspendez les tâches inutiles quand le document est masqué, mais n’en déduisez pas que la page a été quittée, que l’utilisateur est attentif ou qu’il est autorisé à agir. Ces API relèvent de la plateforme web, pas d’ECMAScript 2024. Sans DOM de navigateur, document peut être absent, et la prise en charge varie selon l’environnement d’exécution.

Exemples

(() => {
  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);
})();

Résultat

ready
hidden
visible

Collez le code une seule fois dans la console d’un nouvel onglet actif `about:blank`. Repérez `ready`, changez d’onglet, attendez un instant et revenez. Si le navigateur signale les deux transitions, la console affiche `hidden`, puis `visible`, et le paragraphe affiche de nouveau `visible`. Rechargez l’onglet pour réinitialiser l’exemple. Pour vérifier le gestionnaire dans Node.js, enregistrez le code dans `main.js` et exécutez `node main.js` ; un document de test simule les deux transitions.

Leçons associées

  • JavaScript · Leçon 13 · Avancé · Version : 4

Sources