Intersection Observer API

Baseline

Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis mars 2019.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

Voir la compatibilité complète
En savoir plus

Expérimental: Il s'agit d'une technologie expérimentale.
Vérifiez attentivement le tableau de compatibilité des navigateurs avant de l'utiliser en production.

L'API Intersection Observer permet d'observer de manière asynchrone l'évolution de l'intersection d'un élément cible avec un élément ancêtre ou avec la zone d'affichage d'un document de niveau supérieur.

Historiquement, détecter la visibilité d'un élément, ou la visibilité relative de deux éléments l'un par rapport à l'autre, a été une tache difficile, résolue de manière peu rigoureuse et pouvant nuire à la fluidité de la page consultée. Malheureusement, avec la maturation de la toile, ce genre d'information se révèle de plus en plus nécessaire. La donnée de l'intersection est requise pour de nombreuses raisons, telles que:

Le chargement paresseux d'images ou d'autres types de contenus au fur et à mesure que la page défile.
L'implantation de « défilement infini », où de plus en plus de contenu est chargé tandis que l'utilisateur défile, afin qu'il n'ait pas à changer de page.
Le signalement de la visibilité pour les publicités afin de calculer les revenus publicitaires.
La décision d'exécuter ou non une tâche ou une animation selon que l'utilisateur va en voir le résultat ou non.

De par le passé, l'implantation de la détection d'intersection impliquait des gestionnaires d'évènements et des boucles appelant des méthodes telles que Element.getBoundingClientRect() afin de générer les informations nécessaires pour chaque élément concerné. Comme la totalité du code est exécuté dans le thread principal, même une seule de ces boucles peut causer des problèmes de performance. Si un site est rempli de ces tests, les choses peuvent vite devenir très moches.

Prenons une page qui utilise un défilement infini. Mettons qu'elle utilise une bibliothèque fournie par un éditeur afin de gérer les publicités placées périodiquement le long de la page, qu'elle a des graphiques animés ici et là, et qu'elle utilise une bibliothèque personnalisée pour dessiner des cases de notifications et ce genre de choses. Chacune de ces choses a ses propres procédures de détection d'intersection, toutes exécutées dans le thread principal. L'auteur du site ne le réalise peut-être même pas, puisqu'il utilise deux bibliothèques dont il ne connaît pas forcément les détails de fonctionnement. Quand l'utilisateur navigue sur la page, ces procédures de détection d'intersection réagissent constamment pendant l'exécution du code de défilement, rendant l'expérience frustrante pour l'utilisateur vis-à-vis de son navigateur, du site Internet et de son ordinateur.

L'API Intersection Observer permet d'intégrer une fonction callback qui est exécutée quand un élément qu'on souhaite surveiller entre ou sort d'un autre élément (ou du viewport (zone d'affichage)), ou quand la taille de leur intersection varie d'une quantité prédéterminée. Ainsi, les sites n'ont plus besoin de faire quoi que ce soit sur le thread principal pour surveiller ce genre d'intersection d'éléments, et le navigateur est libre de gérer la détection d'intersection comme bon lui semble.

Il y a une chose sur laquelle l'API Intersection Observer ne peut pas vous renseigner : le nombre de pixels qui intersectent, ou bien desquels il s'agit précisément; par contre elle permet d'ordonner des actions souvent utiles telles que « si ils s'intersectent de plus de N%, alors faire ceci ».

Concepts et utilisation de l'observateur d'intersections

L'API Intersection Observer permet de mettre en place une fonction callback qui est appelée quand un élément, appelé la cible, intersecte ou bien le viewport (la zone d'affichage) ou bien un élément prédéfini ; dans le cadre de cette API, nous l'appellerons l'élément racine ou la racine. Typiquement, on voudra observer les variations de l'intersection par rapport à la zone d'affichage du document (ce qui est fait en passant l'argument null au moment de désigner l'élément racine). Que vous utilisiez la zone d'affichage ou un autre élément comme racine, l'API fonctionne de la même façon, en exécutant une fonction callback, fournie au préalable, lorsque la visibilité de l'élément cible change de telle sorte qu'il atteint la quantité voulue d'intersection avec l'élément racine.

Le degré d'intersection entre l'élément cible et sa racine est le ratio d'intersection. C'est une représentation du pourcentage de l'élément cible qui est visible, exprimée sous la forme d'un nombre compris entre 0.0 et 1.0.

Création d'un observateur d'intersection

Créez l'observateur d'intersection en appelant son constructeur et en lui passant la référence d'une fonction callback. Cette fonction sera exécutée quand un palier est franchi dans un sens ou dans un autre :

var options = {
  root: document.querySelector("#scrollArea"),
  rootMargin: "0px",
  threshold: 1.0,
};

var observer = new IntersectionObserver(callback, options);

Un palier de 1.0 signifie que lorsque 100% de la cible est visible dans l'élément désigné par l'option root (l'élément racine), la fonction callback est invoquée.

Options de l'observateur d'intersection

L'objet options qui est passé dans le constructeur IntersectionObserver() permet de contrôler les circonstances selon lesquelles la fonction callback de l'observateur est invoquée. Il possède les champs suivants :

root: L'élément qui est utilisé comme zone d'affichage au moment d'évaluer la visibilité de la cible. Il doit être un ancêtre de la cible. S'il n'est pas spécifié ou s'il prend la valeur null, sa valeur par défaut est la zone d'affichage (le viewport) du navigateur.
rootMargin: La marge autour de la racine. Peut prendre des valeurs similaires à la propriété CSS margin par exemple "10px 20px 30px 40px" (top, right, bottom, left). Si l'élément root a été spécifié, les valeurs peuvent être exprimées en pourcentages. Cet ensemble de valeur sert à agrandir ou à réduire chaque coté du cadre délimitant l'élément racine avant d'évaluer les intersections. Par défaut, toutes les valeurs prennent la valeur zéro.
threshold: Soit un nombre, soit un tableau de nombre qui indique à quel pourcentage de la visibilité de la cible la fonction callback de la cible doit être exécuté. Si vous souhaitez seulement détecter quand la visibilité franchit la barre des 50%, vous pouvez entrer la valeur 0.5. Si vous voulez que le callback soit exécuté chaque fois que la visibilité varie de 25% de plus, il faudra spécifier le tableau [0, 0.25, 0.5, 0.75, 1]. La valeur par défaut est 0 (ce qui signifie que dés qu'un seul pixel sera visible, la fonction callback sera exécutée). Une valeur de 1.0 signifie que le palier n'est considéré comme franchi qu'une fois que tous les pixels sont visibles.

Choisir un élément à observer

Une fois l'observateur créé, il faut lui donner un élément cible à observer :

var target = document.querySelector("#listItem");
observer.observe(target);

Lorsque la cible franchit un palier spécifié indiqué dans l'objet IntersectionObserver, la fonction callback est appelée. Le callback reçoit une liste d'objets IntersectionObserverEntry ainsi que l'observateur :