CKTIS / JavaScript
IntersectionObserver: obserwowanie przecięcia elementów
IntersectionObserver asynchronicznie zgłasza geometryczne przecięcie elementu z obszarem odniesienia. Poznaj opcje root, rootMargin i threshold oraz różnicę między przecięciem a rzeczywistą widocznością.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: 0 })IntersectionObserver to przeglądarkowe Web API, nie funkcja ECMAScript. Dostępność Node 24 nie potwierdza obsługi w przeglądarce; sprawdzaj ją w środowisku docelowym.
root określa obszar odniesienia; domyślne null oznacza viewport. rootMargin rozszerza lub zwęża jego granice, przyjmując 1–4 wartości w pikselach lub procentach. Te przesunięcia dotyczą tylko elementów docelowych o tej samej domenie pochodzenia (same-origin-domain); w przypadku elementów o innej domenie pochodzenia (cross-origin-domain) są ignorowane. threshold przyjmuje liczbę lub tablicę z zakresu [0, 1]; domyślnie wynosi 0. Odczyt przez thresholds zwraca posortowane progi udziału pola elementu.
Po rozpoczęciu obserwacji callback zwykle otrzymuje początkowy wpis dla danego elementu, ale nie jest to gwarantowane. Obserwacja może zakończyć się, zanim wpis powstanie, a takeRecords() może pobrać wpis z kolejki, zanim trafi on do callbacku. Kolejne wpisy trafiają do kolejki przy przekroczeniu progów lub zmianie isIntersecting. Przecięcie geometryczne nie dowodzi faktycznej widoczności; styk krawędzi może dać isIntersecting === true przy zerowym polu przecięcia.
observe(target) rozpoczyna obserwację, unobserve(target) kończy ją dla jednego elementu, a disconnect() dla wszystkich. Przykład sprawdza początkowe pełne przecięcie i sprząta zasoby.
Przykłady
(() => {
if (!("IntersectionObserver" in window)) {
throw new Error("IntersectionObserver unavailable");
}
const root = document.createElement("div");
root.style.cssText = "position:fixed;top:0;left:0;width:100px;height:100px;overflow:hidden;padding:0;border:0;";
const target = document.createElement("div");
target.style.cssText = "width:20px;height:20px;margin:0;";
root.append(target);
document.body.append(root);
const observer = new IntersectionObserver((entries) => {
console.log(entries[0].intersectionRatio === 1);
observer.disconnect();
root.remove();
}, { root, rootMargin: "0px", threshold: [0, 1] });
observer.observe(target);
})();Wynik
true
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.