Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Visibilidad del documento: `Document.hidden` y `visibilitychange`

Lee el estado de visibilidad del documento con `document.hidden` y responde a sus cambios con `visibilitychange`, sin hacer consultas periódicas.

Versión: Current web platform; runtime support varies

Sintaxis

document.hidden
 document.visibilityState
 document.addEventListener("visibilitychange", listener)
 document.removeEventListener("visibilitychange", listener)

document.hidden es una propiedad booleana de solo lectura. Vale true si document.visibilityState es "hidden" y false si es "visible". Una pestaña en segundo plano o una ventana minimizada son casos habituales en los que el documento se considera oculto. Este estado no indica si la página tiene el foco, si un elemento concreto es visible ni si alguien está mirando la página.

El navegador emite visibilitychange en document después de un cambio de estado en cualquiera de los dos sentidos. Es un Event genérico que se propaga hacia arriba y no se puede cancelar. No contiene el estado nuevo: lee la propiedad dentro de la función de escucha. Registrar esa función no la ejecuta de inmediato; lee el estado inicial por separado. Para dejar de escuchar, pasa la misma función a removeEventListener.

Por ejemplo, puedes pausar las actualizaciones innecesarias de la interfaz mientras el documento esté oculto y reanudarlas cuando vuelva a ser visible. El paso a "hidden" no significa que la página se haya cerrado, ni debes contar con que el navegador dé tiempo al código para terminar su trabajo. Esta API pertenece a la plataforma web, no a ECMAScript. Su disponibilidad depende del entorno de ejecución.

Ejemplos

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

Ejecuta el código una vez en la consola del navegador de una página visible. Cambia a otra pestaña y vuelve. La salida indicada supone exactamente esos dos cambios tras la lectura inicial. Llama a `stopVisibilityLog()` para dejar de registrar los cambios. En Node.js, el ejemplo simula los cambios de visibilidad sin usar un documento del navegador.

Lecciones relacionadas

  • JavaScript · Lección 27 · Intermedio · Versión: 3
  • JavaScript · Lección 29 · Intermedio · Versión: 3
  • JavaScript · Lección 31 · Intermedio · Versión: 3

Fuentes