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.
rootMarginest une chaîne contenant une à quatre longueurs CSS absolues ou valeurs en pourcentage, réparties comme pourmarginen CSS : haut, droite, bas, gauche. La spécification prévoit de convertir les longueurs absolues, par exemple encm, en pixels lors de l’analyse de la chaîne. Pour assurer la compatibilité entre navigateurs, utilisezpxou%: certains navigateurs rejettent les autres unités absolues. Chaque côté vaut0pxpar 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 etentry.rootBoundsvautnull.
thresholdaccepte un nombre ou un tableau de nombres compris entre0et1inclus. Une option omise ou un tableau vide donne un seuil de0. L’option du constructeur s’appellethreshold; la propriété en lecture seuleobserver.thresholdsrenvoie un tableau trié par ordre numérique croissant. Une valeur hors limites déclenche uneRangeError; unrootMargininvalide déclenche uneDOMExceptionnomméeSyntaxError.
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 quandentry.isIntersectingchange, et non à chaque variation du rapport.0.5signifie la moitié de la surface du rectangle englobant de la cible, pas de la racine. Un contact entre bords peut donnerisIntersecting: trueavecintersectionRatio: 0. Si le rectangle de la cible est de surface nulle, le rapport vaut1siisIntersectingest vrai, sinon0. 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, etdisconnect()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
- IntersectionObserver: IntersectionObserver() constructor
- Intersection Observer API
- IntersectionObserver: rootMargin property
- Intersection Observer specification — Parse a margin
- IntersectionObserver: thresholds property
- IntersectionObserver: observe() method
- IntersectionObserverEntry: intersectionRatio property
- IntersectionObserverEntry: isIntersecting property
- IntersectionObserver: disconnect() method
- HTML Standard — Update the rendering