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.
rootMargines una cadena de uno a cuatro valores de longitud absoluta de CSS o de porcentaje que se distribuyen como enmarginde CSS: arriba, derecha, abajo e izquierda. Según la especificación, al analizar la cadena, las longitudes absolutas, como las expresadas encm, se convierten en píxeles. Para mantener la compatibilidad entre navegadores, usapxo%, ya que algunos rechazan otras unidades absolutas. Cada lado vale0pxde 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 yentry.rootBoundsesnull.
thresholdacepta un número o un arreglo de números entre0y1, ambos incluidos. Omitirlo o pasar un arreglo vacío equivale a usar un umbral de0. La opción del constructor esthreshold; la propiedad de solo lecturaobserver.thresholdsdevuelve un arreglo ordenado numéricamente de menor a mayor. Un umbral fuera del intervalo lanza unRangeError; unrootMarginno válido lanza unaDOMExceptionllamadaSyntaxError.
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 cambiarentry.isIntersecting, no cada vez que cambia la proporción.0.5significa la mitad del área del rectángulo delimitador del objetivo, no la de la raíz. El contacto entre bordes puede darisIntersecting: trueconintersectionRatio: 0. Si el rectángulo del objetivo tiene área cero, la proporción es1siisIntersectinges verdadero, y0en 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 odisconnect()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
- IntersectionObserver: IntersectionObserver() constructor
- Intersection Observer API
- IntersectionObserver: rootMargin property
- Intersection Observer specification — Parse a margin
- IntersectionObserver: thresholds property
- IntersectionObserver: observe() method
- IntersectionObserverEntry: intersectionRatio property
- IntersectionObserverEntry: isIntersecting property
- IntersectionObserver: disconnect() method
- HTML Standard — Update the rendering