Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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 per margin in CSS: alto, destra, basso, sinistra. La specifica prevede che le lunghezze assolute, per esempio quelle in cm, vengano convertite in pixel durante l’analisi della stringa. Per la compatibilità tra browser, usa px o %, perché alcuni browser rifiutano le altre unità assolute. Il valore predefinito è 0px su 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 e entry.rootBounds è null.

threshold accetta un numero o un array di numeri tra 0 e 1 inclusi. Omettere l’opzione o passare un array vuoto imposta la soglia a 0. L’opzione del costruttore si chiama threshold; la proprietà di sola lettura observer.thresholds restituisce un array ordinato numericamente in ordine crescente. Un valore fuori intervallo genera un RangeError; un rootMargin non valido genera una DOMException chiamata SyntaxError.

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 cambia entry.isIntersecting, non a ogni variazione del rapporto. 0.5 indica metà dell’area del rettangolo di delimitazione del bersaglio, non della radice. Il contatto tra bordi può dare isIntersecting: true con intersectionRatio: 0. Se il rettangolo del bersaglio ha area zero, il rapporto vale 1 se isIntersecting è vero e 0 altrimenti. 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 oppure disconnect() 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