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

CKTIS / JavaScript

IntersectionObserverEntry — lire l’intersection d’un élément

IntersectionObserverEntry décrit l’intersection d’un élément observé avec sa racine à un instant donné. Ses propriétés isIntersecting, target et intersectionRatio indiquent l’état de l’intersection, l’élément concerné et la fraction de sa surface qui est en intersection.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

entry.isIntersecting
entry.target
entry.intersectionRatio

IntersectionObserverEntry est un instantané géométrique, et non un objet mis à jour en continu. Le navigateur transmet les entrées de manière asynchrone à une fonction de rappel IntersectionObserver ; les entrées en attente peuvent aussi être récupérées avec takeRecords(). La fonction de rappel doit traiter tout le tableau entries, et pas seulement sa première entrée.

IntersectionObserverEntry.target référence l’Element observé. IntersectionObserverEntry.isIntersecting est un booléen qui indique s’il y a intersection avec la racine. IntersectionObserverEntry.intersectionRatio est un nombre compris entre 0 et 1 : la surface de intersectionRect divisée par celle de boundingClientRect. Pour une cible de surface nulle, sa valeur est 1 si isIntersecting vaut true, et 0 sinon ; ne considère pas ces deux propriétés comme équivalentes.

La première notification décrit l’état initial après observe(). Les notifications suivantes dépendent, entre autres, du franchissement des valeurs threshold configurées ; elles ne signalent pas chaque pixel de défilement. Pour réagir lorsque la moitié de la surface est en intersection, inclus le seuil 0.5 et teste entry.isIntersecting && entry.intersectionRatio >= 0.5. Une observation géométrique ordinaire ne prouve pas qu’un autre élément ne recouvre pas la cible.

Il s’agit d’une API Web de navigateur, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. MDN indique que l’interface de base est largement disponible depuis mars 2019 ; les fonctionnalités supplémentaires peuvent être prises en charge différemment. La présence de Node 24 dans un dépôt ne permet pas de conclure que l’API est disponible. L’exemple place une cible de 100px de haut dans une racine de découpage de 50px de haut, puis arrête l’observation.

Exemples

(() => {
  const root = document.createElement('div');
  root.style.cssText = 'all:initial;position:fixed;top:0;left:0;width:100px;height:50px;overflow:hidden;';
  const target = document.createElement('div');
  target.style.cssText = 'all:initial;display:block;width:100px;height:100px;';
  root.append(target);
  document.body.append(root);

  const observer = new IntersectionObserver((entries) => {
    for (const entry of entries) {
      console.log(
        entry.isIntersecting,
        entry.target === target,
        entry.intersectionRatio.toFixed(2)
      );
    }
    observer.disconnect();
    root.remove();
  }, { root, threshold: [0, 0.5, 1] });

  observer.observe(target);
})();

Résultat

true true 0.50

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources