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

CKTIS / JavaScript

Opciones de IntersectionObserver: root, rootMargin y threshold

`root` elige el área de referencia, `rootMargin` ajusta sus límites para el cálculo y `threshold` define qué proporciones del área del objetivo activan las notificaciones.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: [0, 0.5, 1] })

IntersectionObserver es una API del navegador, no una función de ECMAScript. root elige el área de referencia: si se omite o se pasa null, se usa el área de visualización del documento de nivel superior. La raíz explícita puede ser un Document o un Element, como un contenedor desplazable. Si es un elemento, el objetivo debe descender de él en la cadena de bloques contenedores del diseño.

rootMargin es una cadena de uno a cuatro valores de longitud absoluta de CSS o de porcentaje que se distribuyen como en margin de CSS: arriba, derecha, abajo e izquierda. Según la especificación, al analizar la cadena, las longitudes absolutas, como las expresadas en cm, se convierten en píxeles. Para mantener la compatibilidad entre navegadores, usa px o %, ya que algunos rechazan otras unidades absolutas. Cada lado vale 0px de forma predeterminada. Los porcentajes se calculan respecto al ancho del rectángulo original de la raíz, incluso arriba y abajo. Los valores positivos amplían el rectángulo del cálculo y los negativos lo reducen. Esto no cambia el diseño ni anula los recortes de los antecesores intermedios. Para objetivos de otro origen, el margen se ignora y entry.rootBounds es null.

threshold acepta un número o un arreglo de números entre 0 y 1, ambos incluidos. Omitirlo o pasar un arreglo vacío equivale a usar un umbral de 0. La opción del constructor es threshold; la propiedad de solo lectura observer.thresholds devuelve un arreglo ordenado numéricamente de menor a mayor. Un umbral fuera del intervalo lanza un RangeError; un rootMargin no válido lanza una DOMException llamada SyntaxError.

Tras observe(target), la función que se pasa al constructor del observador (callback) recibe de forma asíncrona una entrada inicial, aunque no haya intersección. Se encolan más entradas al cruzar un umbral en cualquier dirección o al cambiar entry.isIntersecting, no cada vez que cambia la proporción. 0.5 significa la mitad del área del rectángulo delimitador del objetivo, no la de la raíz. El contacto entre bordes puede dar isIntersecting: true con intersectionRatio: 0. Si el rectángulo del objetivo tiene área cero, la proporción es 1 si isIntersecting es verdadero, y 0 en caso contrario. Una intersección geométrica no demuestra que el usuario vea el objetivo.

Las opciones quedan fijas al construir el observador. Para cambiarlas, crea otro. Usa unobserve(target) para dejar de observar un objetivo o disconnect() para dejar de observarlos todos. Comprueba que el entorno de ejecución admita la API.

Ejemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IntersectionObserver options</title>
</head>
<body>
<script>
{
  const root = document.createElement("div");
  const spacer = document.createElement("div");
  const target = document.createElement("div");
  root.style.cssText = "width: 120px; height: 100px; overflow: hidden";
  spacer.style.height = "120px";
  target.style.cssText = "height: 40px; background: teal";
  root.append(spacer, target);
  document.body.append(root);

  const observer = new IntersectionObserver(([entry], observer) => {
    console.log(`root matches: ${observer.root === root}`);
    console.log(`rootMargin: ${observer.rootMargin}`);
    console.log(`thresholds: ${JSON.stringify(observer.thresholds)}`);
    console.log(`isIntersecting: ${entry.isIntersecting}`);
    console.log(`intersectionRatio: ${entry.intersectionRatio}`);
    observer.disconnect();
    root.remove();
  }, {
    root,
    rootMargin: "0px 0px 40px",
    threshold: [1, 0, 0.5],
  });
  observer.observe(target);
}
</script>
</body>
</html>

Resultado

root matches: true
rootMargin: 0px 0px 40px 0px
thresholds: [0,0.5,1]
isIntersecting: true
intersectionRatio: 0.5

Guarda el ejemplo como archivo HTML, ábrelo en una pestaña activa del navegador y consulta la salida en la consola de desarrollo. El objetivo empieza 20 px por debajo del borde inferior de la raíz. El margen inferior de 40 px incluye la mitad de la altura del objetivo en todo su ancho. Por eso la primera entrada indica `intersectionRatio: 0.5`. El código desconecta el observador y elimina los elementos de la demostración.

Lecciones relacionadas

  • JavaScript · Lección 30 · Intermedio · Versión: 3

Fuentes