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

CKTIS / JavaScript

IntersectionObserverEntry: isIntersecting, intersectionRatio y target

Consulta si el elemento observado se cruza con la zona de referencia, qué proporción de su área coincide con ella y por qué eso no equivale a cruzar un umbral.

Versión: Current web platform; runtime support varies

Sintaxis

entry.isIntersecting     // boolean
entry.intersectionRatio // number in [0, 1]
entry.target            // Element

Un IntersectionObserverEntry registra el estado de un objetivo en el momento de la medición. La función de retorno de llamada del observador recibe las entradas de forma asíncrona y puede recibir varias a la vez. entry.target es el mismo Element que se pasó a observe(), no root. Las tres propiedades son de solo lectura, pero el elemento en sí se puede modificar. Esta API forma parte de la plataforma web, no de ECMAScript 2024.

entry.isIntersecting es un booleano que indica si el objetivo intersecta la zona de referencia del observador en esa medición. Con el valor predeterminado root: null, esa zona es el área de visualización del documento de nivel superior, no la del iframe que contiene el objetivo. Aun así, el área de visualización del iframe puede limitar la intersección calculada. true describe un estado, no necesariamente una transición a ese estado. Según la especificación, dos bordes que apenas se tocan pueden contar como intersección aunque su área sea cero.

entry.intersectionRatio es un número entre 0 y 1: el área de intersectionRect dividida por el área de boundingClientRect del objetivo, no por la de la zona de referencia. Si el rectángulo del objetivo tiene área cero, el resultado es 1 cuando isIntersecting es true y 0 en caso contrario. La medición predeterminada es geométrica: no demuestra que otro elemento no esté tapando el objetivo.

Tras llamar a observe(), recibes una entrada inicial aunque el objetivo esté fuera de la zona de referencia. Puedes recibir nuevas entradas al cruzar un umbral en cualquier dirección o cuando cambia isIntersecting, pero no cada vez que cambia la proporción. threshold: 0.5 fija un umbral de notificación; entry.intersectionRatio >= 0.5 comprueba el valor de una entrada concreta.

Ejemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IntersectionObserverEntry example</title>
</head>
<body>
<script>
(() => {
  const root = document.createElement('div');
  root.style.cssText = 'position:relative;overflow:hidden;width:100px;height:100px';
  const target = document.createElement('div');
  target.style.cssText = 'position:absolute;left:0;top:50px;width:100px;height:100px;background:royalblue';
  root.append(target);
  document.body.append(root);

  let moved = false;
  const observer = new IntersectionObserver((entries) => {
    for (const entry of entries) {
      console.log(`${entry.isIntersecting} ${entry.intersectionRatio} ${entry.target === target}`);
      if (!moved) {
        moved = true;
        target.style.top = '150px';
      } else {
        observer.disconnect();
        root.remove();
      }
    }
  }, { root, threshold: 0.5 });
  observer.observe(target);
})();
</script>
</body>
</html>

Resultado

true 0.5 true
false 0 true

Guarda el ejemplo como archivo HTML y ábrelo en su propia pestaña en un navegador compatible con la API. Abre la consola de desarrollo y recarga la página. La primera entrada muestra que la intersección abarca la mitad del área del objetivo. El código desplaza el objetivo completamente fuera de la zona de referencia y la segunda entrada ya no muestra intersección. Ambas entradas hacen referencia al mismo elemento; después de la segunda, el código deja de observarlo y elimina la zona de referencia.

Lecciones relacionadas

  • JavaScript · Lección 37 · Avanzado · Versión: 4

Fuentes