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

CKTIS / JavaScript

IntersectionObserverEntry : isIntersecting, intersectionRatio et target

Identifiez l’élément observé, vérifiez s’il intersecte la zone de référence et mesurez la proportion de sa surface concernée, sans confondre état et franchissement d’un seuil.

Version : Current web platform; runtime support varies

Syntaxe

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

Un objet IntersectionObserverEntry enregistre l’état d’une cible au moment de la mesure. La fonction de rappel de l’observateur reçoit les entrées de façon asynchrone et peut en recevoir plusieurs à la fois. entry.target est le même Element que celui passé à observe(), et non root. Les trois propriétés sont en lecture seule, mais l’élément lui-même reste modifiable. Cette API appartient à la plateforme web, pas à ECMAScript 2024.

entry.isIntersecting est un booléen qui indique si, lors de la mesure, la cible intersecte la zone de référence de l’observateur. Avec la valeur par défaut root: null, cette zone correspond à la fenêtre d’affichage du document de premier niveau, et non à celle de l’iframe qui contient la cible. La fenêtre d’affichage de l’iframe peut néanmoins limiter l’intersection calculée. true décrit un état, pas nécessairement le passage à cet état. Selon la spécification, des bords qui se touchent peuvent compter comme une intersection même si son aire est nulle.

entry.intersectionRatio est un nombre compris entre 0 et 1 : l’aire de intersectionRect divisée par celle de boundingClientRect de la cible, et non par l’aire de la zone de référence. Si le rectangle de la cible a une aire nulle, le résultat vaut 1 lorsque isIntersecting vaut true, et 0 sinon. La mesure par défaut est géométrique et ne prouve pas qu’aucun autre élément ne masque la cible.

Après observe(), vous recevez une première entrée même si la cible se trouve hors de la zone de référence. Les entrées suivantes peuvent résulter d’un franchissement de seuil dans un sens ou dans l’autre, ou d’un changement de isIntersecting. Une variation du rapport ne déclenche pas toujours une entrée. threshold: 0.5 fixe un seuil de notification, tandis que entry.intersectionRatio >= 0.5 teste la valeur d’une entrée précise.

Exemples

<!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>

Résultat

true 0.5 true
false 0 true

Enregistrez l’exemple dans un fichier HTML et ouvrez-le dans son propre onglet, dans un navigateur qui prend en charge cette API. Ouvrez la console de développement et rechargez la page. La première entrée montre que l’intersection couvre la moitié de la surface de la cible. Le code déplace la cible entièrement hors de la zone de référence ; la seconde entrée indique qu’il n’y a plus d’intersection. Les deux entrées désignent le même élément. Après la seconde, le code arrête l’observation et retire la zone de référence.

Leçons associées

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

Sources