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

CKTIS / JavaScript

Options d’IntersectionObserver : root, rootMargin et threshold

`root` choisit la zone de référence, `rootMargin` ajuste ses limites pour le calcul et `threshold` fixe les fractions de la surface de la cible qui déclenchent des notifications.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: [0, 0.5, 1] })

IntersectionObserver est une API du navigateur, pas une fonctionnalité d’ECMAScript. root choisit la zone de référence : si l’option est omise ou vaut null, c’est la zone d’affichage du document de niveau supérieur qui est utilisée. Une racine explicite peut être un Document ou un Element, par exemple un conteneur défilant. Une racine de type élément doit être un ancêtre de la cible dans la chaîne des blocs englobants de la mise en page.

rootMargin est une chaîne contenant une à quatre longueurs CSS absolues ou valeurs en pourcentage, réparties comme pour margin en CSS : haut, droite, bas, gauche. La spécification prévoit de convertir les longueurs absolues, par exemple en cm, en pixels lors de l’analyse de la chaîne. Pour assurer la compatibilité entre navigateurs, utilisez px ou % : certains navigateurs rejettent les autres unités absolues. Chaque côté vaut 0px par défaut. Les pourcentages se rapportent à la largeur du rectangle initial de la racine, même en haut et en bas. Les valeurs positives agrandissent le rectangle utilisé pour le calcul, les négatives le réduisent. Cela ne change pas la mise en page et n’annule pas le rognage par les ancêtres intermédiaires. Pour une cible d’origine différente, la marge est ignorée et entry.rootBounds vaut null.

threshold accepte un nombre ou un tableau de nombres compris entre 0 et 1 inclus. Une option omise ou un tableau vide donne un seuil de 0. L’option du constructeur s’appelle threshold ; la propriété en lecture seule observer.thresholds renvoie un tableau trié par ordre numérique croissant. Une valeur hors limites déclenche une RangeError ; un rootMargin invalide déclenche une DOMException nommée SyntaxError.

Après observe(target), la fonction de rappel reçoit une première entrée de façon asynchrone, même sans intersection. D’autres entrées sont mises en file quand un seuil est franchi dans un sens ou dans l’autre, ou quand entry.isIntersecting change, et non à chaque variation du rapport. 0.5 signifie la moitié de la surface du rectangle englobant de la cible, pas de la racine. Un contact entre bords peut donner isIntersecting: true avec intersectionRatio: 0. Si le rectangle de la cible est de surface nulle, le rapport vaut 1 si isIntersecting est vrai, sinon 0. Une intersection géométrique ne prouve pas que l’utilisateur voit la cible.

Les options sont fixées à la construction. Pour les modifier, créez un nouvel observateur. unobserve(target) arrête l’observation d’une cible, et disconnect() celle de toutes les cibles. Vérifiez que l’environnement d’exécution prend en charge l’API.

Exemples

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

Résultat

root matches: true
rootMargin: 0px 0px 40px 0px
thresholds: [0,0.5,1]
isIntersecting: true
intersectionRatio: 0.5

Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un onglet actif du navigateur et consultez la sortie dans la console de développement. La cible commence 20 px sous le bord inférieur de la racine. La marge inférieure de 40 px englobe la moitié de la hauteur de la cible sur toute sa largeur. La première entrée indique donc `intersectionRatio: 0.5`. Le code déconnecte l’observateur et retire les éléments de démonstration.

Leçons associées

  • JavaScript · Leçon 30 · Intermédiaire · Version : 3

Sources