CKTIS / JavaScript
Opcje IntersectionObserver: root, rootMargin i threshold
`root` wybiera obszar odniesienia, `rootMargin` zmienia jego granice na potrzeby obliczeń, a `threshold` określa progi udziału powierzchni celu, przy których obserwator wysyła powiadomienia.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: [0, 0.5, 1] })IntersectionObserver to interfejs API przeglądarki, a nie część ECMAScript. Opcja root wskazuje obszar odniesienia: pominięcie jej lub podanie null oznacza użycie obszaru widoku dokumentu najwyższego poziomu. Można jawnie wskazać Document lub Element, na przykład przewijany kontener. Gdy korzeniem jest element, cel musi być jego potomkiem w łańcuchu bloków zawierających układu.
rootMarginto ciąg od jednej do czterech wartości będących bezwzględnymi długościami CSS lub procentami, rozwijanych jak w CSSmargin: góra, prawo, dół, lewo. Zgodnie ze specyfikacją długości bezwzględne, na przykład wcm, są podczas parsowania przeliczane na piksele. Dla zgodności między przeglądarkami używajpxlub%, ponieważ niektóre przeglądarki odrzucają inne jednostki bezwzględne. Domyślnie wszystkie boki mają0px. Procenty odnoszą się do szerokości pierwotnego prostokąta korzenia, również dla góry i dołu. Wartości dodatnie rozszerzają prostokąt używany w obliczeniach, a ujemne go zwężają. Nie zmienia to układu ani nie znosi przycinania przez pośrednich przodków. Dla celów z innego źródła margines jest ignorowany, aentry.rootBoundsma wartośćnull.
thresholdprzyjmuje jedną liczbę lub tablicę liczb od0do1włącznie. Pominięcie opcji lub podanie pustej tablicy daje próg0. Opcja konstruktora tothreshold, a tylko do odczytu właściwośćobserver.thresholdszwraca tablicę posortowaną rosnąco liczbowo. Wartość poza zakresem powodujeRangeError, a nieprawidłowyrootMarginpowodujeDOMExceptiono nazwieSyntaxError.
Po
observe(target)funkcja zwrotna otrzymuje asynchronicznie wpis początkowy, nawet jeśli cel się nie przecina. Kolejne powiadomienia pojawiają się po przekroczeniu progu w dowolnym kierunku lub przy zmianieentry.isIntersecting, a nie przy każdej zmianie proporcji.0.5oznacza połowę powierzchni prostokąta ograniczającego cel, nie połowę powierzchni korzenia. Samo zetknięcie krawędzi może daćisIntersecting: trueprzyintersectionRatio: 0. Gdy prostokąt celu ma zerową powierzchnię, proporcja wynosi1, jeśliisIntersectingjest prawdziwe, a w przeciwnym razie0. Przecięcie geometryczne nie dowodzi, że użytkownik widzi cel.
Opcje są ustalane podczas tworzenia obserwatora. Aby je zmienić, utwórz nowy obserwator. Użyj
unobserve(target), aby przestać obserwować jeden cel, albodisconnect(), aby zakończyć obserwowanie wszystkich celów. Sprawdź obsługę API w środowisku, w którym będzie działał kod.
Przykłady
<!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>Wynik
root matches: true rootMargin: 0px 0px 40px 0px thresholds: [0,0.5,1] isIntersecting: true intersectionRatio: 0.5
Zapisz przykład jako plik HTML, otwórz go w aktywnej karcie przeglądarki i sprawdź wynik w konsoli deweloperskiej. Cel zaczyna się 20 px poniżej dolnej krawędzi korzenia. Margines dolny 40 px obejmuje połowę jego wysokości na całej szerokości, więc pierwszy wpis podaje `intersectionRatio: 0.5`. Kod kończy obserwację i usuwa elementy demonstracyjne.
Powiązane lekcje
- JavaScript · Lekcja 30 · Średniozaawansowany · Wersja: 3
Źródła
- 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