WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

IntersectionObserver: Elementüberschneidungen beobachten

IntersectionObserver meldet asynchron die geometrische Überschneidung eines Elements mit einem Bezugsbereich. Lerne die Optionen root, rootMargin und threshold kennen und unterscheide eine Überschneidung von tatsächlicher Sichtbarkeit.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

new IntersectionObserver(callback, { root: null, rootMargin: "0px", threshold: 0 })

IntersectionObserver ist eine Web-API des Browsers, kein ECMAScript-Feature. Dass die API in Node 24 verfügbar ist, belegt nicht ihre Unterstützung im Browser; prüfe die Zielumgebung.

root legt den Bezugsbereich fest; der Standardwert null bedeutet den Viewport. rootMargin erweitert oder verkleinert dessen Grenzen mit 1–4 Werten in Pixeln oder Prozent. Diese Abstände werden nur für Ziele mit derselben Ursprungsdomäne (same-origin-domain) angewendet; bei Zielen mit einer anderen Ursprungsdomäne (cross-origin-domain) werden sie ignoriert. threshold akzeptiert eine Zahl oder ein Array im Bereich [0, 1] und hat standardmäßig den Wert 0. Die schreibgeschützte Eigenschaft thresholds liefert sortierte Schwellenwerte für den Flächenanteil des Elements.

Nach Beginn der Beobachtung erhält der Callback normalerweise einen ersten Eintrag für das Zielelement, aber die Zustellung ist nicht garantiert. Die Beobachtung kann enden, bevor der Eintrag erzeugt wird, und takeRecords() kann den Eintrag aus der Warteschlange entfernen, bevor er den Callback erreicht. Weitere Einträge werden in die Warteschlange gestellt, wenn Schwellenwerte überschritten werden oder sich isIntersecting ändert. Eine geometrische Überschneidung beweist keine tatsächliche Sichtbarkeit; sich berührende Kanten können isIntersecting === true ergeben, obwohl die Überschneidungsfläche null ist.

observe(target) startet die Beobachtung, unobserve(target) beendet sie für ein einzelnes Element und disconnect() für alle. Das Beispiel prüft die anfängliche vollständige Überschneidung und räumt anschließend auf.

Beispiele

(() => {
  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);
})();

Ergebnis

true

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen