CKTIS / JavaScript
IntersectionObserverEntry: isIntersecting, intersectionRatio e target
Leggi lo stato di intersezione, la frazione di area interessata e l’elemento osservato. Distingui lo stato di intersezione dall’attraversamento di una soglia.
Versione: Current web platform; runtime support varies
Sintassi
entry.isIntersecting // boolean
entry.intersectionRatio // number in [0, 1]
entry.target // ElementUn oggetto IntersectionObserverEntry registra lo stato di un elemento al momento della misurazione. La funzione di callback dell’osservatore riceve le voci in modo asincrono e può riceverne più di una alla volta. entry.target è lo stesso Element passato a observe(), non root. Le tre proprietà sono di sola lettura, ma l’elemento stesso si può modificare. Questa API appartiene alla piattaforma web, non a ECMAScript 2024.
entry.isIntersecting è un booleano che indica se, al momento della misurazione, l’elemento interseca l’area di riferimento dell’osservatore. Con il valore predefinito root: null, l’area di riferimento è la finestra di visualizzazione del documento di primo livello, non quella dell’iframe che contiene l’elemento. La finestra di visualizzazione dell’iframe può comunque limitare l’intersezione calcolata. true descrive uno stato, non necessariamente una transizione verso quello stato. Secondo la specifica, anche bordi che si toccano appena possono contare come intersezione, pur con area di intersezione pari a zero.
entry.intersectionRatio è un numero da 0 a 1: l’area di intersectionRect divisa per quella di boundingClientRect dell’elemento osservato, non per l’area di riferimento. Se il rettangolo dell’elemento ha area zero, il risultato è 1 quando isIntersecting vale true e 0 altrimenti. La misurazione predefinita è geometrica e non dimostra che l’elemento non sia coperto da un altro.
Dopo observe() ricevi una voce iniziale anche se l’elemento è fuori dall’area di riferimento. Le voci successive possono derivare dall’attraversamento di una soglia in entrambe le direzioni o da un cambiamento di isIntersecting. Non tutte le variazioni del rapporto generano una voce. threshold: 0.5 imposta la soglia di notifica, mentre entry.intersectionRatio >= 0.5 controlla il valore di una singola voce.
Esempi
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IntersectionObserverEntry example</title>
</head>
<body>
<script>
(() => {
const root = document.createElement('div');
root.style.cssText = 'position:relative;overflow:hidden;width:100px;height:100px';
const target = document.createElement('div');
target.style.cssText = 'position:absolute;left:0;top:50px;width:100px;height:100px;background:royalblue';
root.append(target);
document.body.append(root);
let moved = false;
const observer = new IntersectionObserver((entries) => {
for (const entry of entries) {
console.log(`${entry.isIntersecting} ${entry.intersectionRatio} ${entry.target === target}`);
if (!moved) {
moved = true;
target.style.top = '150px';
} else {
observer.disconnect();
root.remove();
}
}
}, { root, threshold: 0.5 });
observer.observe(target);
})();
</script>
</body>
</html>Risultato
true 0.5 true false 0 true
Salva l’esempio come file HTML e aprilo in una scheda separata di un browser che supporta l’API. Apri la console per sviluppatori e ricarica la pagina. La prima voce mostra che metà dell’area dell’elemento interseca l’area di riferimento. Il codice sposta l’elemento completamente al di fuori di quell’area; la seconda voce non mostra alcuna intersezione. Entrambe si riferiscono allo stesso elemento. Dopo la seconda, il codice termina l’osservazione e rimuove l’area di riferimento.
Lezioni correlate
- JavaScript · Lezione 37 · Avanzato · Versione: 4
Fonti
- IntersectionObserverEntry: isIntersecting property
- IntersectionObserverEntry: intersectionRatio property
- IntersectionObserverEntry: target property
- IntersectionObserver: observe() method
- IntersectionObserver: IntersectionObserver() constructor
- HTML Standard — Web application APIs
- Intersection Observer specification — intersection geometry