CKTIS / JavaScript
Opzioni di IntersectionObserver: root, rootMargin e threshold
`root` sceglie l’area di riferimento, `rootMargin` ne modifica i limiti ai fini del calcolo e `threshold` stabilisce a quali frazioni dell’area del bersaglio inviare notifiche.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: [0, 0.5, 1] })IntersectionObserver è un’API del browser, non una funzionalità di ECMAScript. root sceglie l’area di riferimento: se lo ometti o passi null, si usa la viewport del documento di livello superiore. Una radice esplicita può essere un Document o un Element, per esempio un contenitore scorrevole. Se la radice è un elemento, il bersaglio deve esserne un discendente nella catena dei blocchi contenitori del layout.
rootMarginè una stringa che contiene da uno a quattro valori, espressi come lunghezze CSS assolute o percentuali e distribuiti come permarginin CSS: alto, destra, basso, sinistra. La specifica prevede che le lunghezze assolute, per esempio quelle incm, vengano convertite in pixel durante l’analisi della stringa. Per la compatibilità tra browser, usapxo%, perché alcuni browser rifiutano le altre unità assolute. Il valore predefinito è0pxsu ogni lato. Le percentuali si riferiscono alla larghezza del rettangolo originario della radice, anche in alto e in basso. I valori positivi ampliano il rettangolo usato nel calcolo, quelli negativi lo restringono. Il layout non cambia e il ritaglio imposto dagli antenati intermedi resta in vigore. Per bersagli di origine diversa, il margine viene ignorato eentry.rootBoundsènull.
thresholdaccetta un numero o un array di numeri tra0e1inclusi. Omettere l’opzione o passare un array vuoto imposta la soglia a0. L’opzione del costruttore si chiamathreshold; la proprietà di sola letturaobserver.thresholdsrestituisce un array ordinato numericamente in ordine crescente. Un valore fuori intervallo genera unRangeError; unrootMarginnon valido genera unaDOMExceptionchiamataSyntaxError.
Dopo
observe(target), la funzione di callback riceve in modo asincrono una prima voce, anche senza intersezione. Altre voci vengono accodate quando si oltrepassa una soglia in uno dei due sensi o cambiaentry.isIntersecting, non a ogni variazione del rapporto.0.5indica metà dell’area del rettangolo di delimitazione del bersaglio, non della radice. Il contatto tra bordi può dareisIntersecting: trueconintersectionRatio: 0. Se il rettangolo del bersaglio ha area zero, il rapporto vale1seisIntersectingè vero e0altrimenti. Un’intersezione geometrica non dimostra che l’utente veda il bersaglio.
Le opzioni sono fissate al momento della costruzione. Per cambiarle, crea un nuovo osservatore. Usa
unobserve(target)per smettere di osservare un bersaglio oppuredisconnect()per smettere di osservarli tutti. Verifica che l’ambiente di esecuzione supporti l’API.
Esempi
<!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>Risultato
root matches: true rootMargin: 0px 0px 40px 0px thresholds: [0,0.5,1] isIntersecting: true intersectionRatio: 0.5
Salva l’esempio come file HTML, aprilo in una scheda attiva del browser e controlla l’output nella console di sviluppo. Il bersaglio inizia 20 px sotto il bordo inferiore della radice. Il margine inferiore di 40 px comprende metà dell’altezza del bersaglio per tutta la sua larghezza. La prima voce riporta quindi `intersectionRatio: 0.5`. Il codice disconnette l’osservatore e rimuove gli elementi dimostrativi.
Lezioni correlate
- JavaScript · Lezione 30 · Intermedio · Versione: 3
Fonti
- 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