Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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.

rootMargin to ciąg od jednej do czterech wartości będących bezwzględnymi długościami CSS lub procentami, rozwijanych jak w CSS margin: góra, prawo, dół, lewo. Zgodnie ze specyfikacją długości bezwzględne, na przykład w cm, są podczas parsowania przeliczane na piksele. Dla zgodności między przeglądarkami używaj px lub %, 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, a entry.rootBounds ma wartość null.

threshold przyjmuje jedną liczbę lub tablicę liczb od 0 do 1 włącznie. Pominięcie opcji lub podanie pustej tablicy daje próg 0. Opcja konstruktora to threshold, a tylko do odczytu właściwość observer.thresholds zwraca tablicę posortowaną rosnąco liczbowo. Wartość poza zakresem powoduje RangeError, a nieprawidłowy rootMargin powoduje DOMException o nazwie SyntaxError.

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 zmianie entry.isIntersecting, a nie przy każdej zmianie proporcji. 0.5 oznacza połowę powierzchni prostokąta ograniczającego cel, nie połowę powierzchni korzenia. Samo zetknięcie krawędzi może dać isIntersecting: true przy intersectionRatio: 0. Gdy prostokąt celu ma zerową powierzchnię, proporcja wynosi 1, jeśli isIntersecting jest prawdziwe, a w przeciwnym razie 0. 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, albo disconnect(), 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