WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

IntersectionObserver-Optionen: root, rootMargin und threshold

`root` wählt den Bezugsbereich, `rootMargin` passt seine Grenzen für die Berechnung an, und `threshold` legt fest, bei welchen Flächenanteilen des Ziels Benachrichtigungen ausgelöst werden.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

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

IntersectionObserver ist eine Browser-API und kein Bestandteil von ECMAScript. root legt den Bezugsbereich fest: Ohne Angabe oder mit null gilt der Viewport des obersten Dokuments. Als explizite Wurzel kann ein Document oder ein Element dienen, etwa ein Scrollcontainer. Bei einer Elementwurzel muss das Ziel in der Kette der umschließenden Layoutblöcke von ihr abstammen.

rootMargin ist eine Zeichenkette mit einem bis vier Werten, die absolute CSS-Längen oder Prozentangaben sind und wie bei CSS margin auf oben, rechts, unten und links verteilt werden. Laut Spezifikation werden absolute Längenangaben, etwa in cm, beim Parsen in Pixel umgerechnet. Verwende für browserübergreifende Kompatibilität px oder %, da manche Browser andere absolute Einheiten ablehnen. Jede Seite hat standardmäßig 0px. Prozentwerte beziehen sich auch oben und unten auf die Breite des ursprünglichen Wurzelrechtecks. Positive Werte vergrößern das Rechteck für die Berechnung, negative verkleinern es. Das Layout und das Abschneiden durch dazwischenliegende Vorfahren bleiben unverändert. Bei Zielen anderen Ursprungs wird der Rand ignoriert und entry.rootBounds ist null.

threshold akzeptiert eine Zahl oder ein Array mit Zahlen von 0 bis einschließlich 1. Ohne Angabe oder bei einem leeren Array gilt 0. Die Konstruktoroption heißt threshold; die schreibgeschützte Eigenschaft observer.thresholds liefert ein numerisch aufsteigend sortiertes Array. Ein Wert außerhalb des Bereichs löst einen RangeError aus, ein ungültiger rootMargin eine DOMException namens SyntaxError.

Nach observe(target) erhält die Callback-Funktion asynchron einen ersten Eintrag, selbst wenn keine Überschneidung vorliegt. Weitere Einträge werden eingereiht, wenn ein Schwellenwert in eine der beiden Richtungen überschritten wird oder sich entry.isIntersecting ändert, nicht bei jeder Änderung des Verhältnisses. 0.5 meint die Hälfte der Fläche des Begrenzungsrechtecks des Ziels, nicht der Wurzel. Kantenspitzen oder Kanten können sich berühren, sodass isIntersecting: true bei intersectionRatio: 0 möglich ist. Hat das Zielrechteck keine Fläche, ist das Verhältnis bei wahrem isIntersecting gleich 1, sonst 0. Geometrische Überschneidung belegt nicht, dass das Ziel für den Nutzer sichtbar ist.

Die Optionen stehen nach der Konstruktion fest. Erstelle einen neuen Observer, um sie zu ändern. unobserve(target) beendet die Beobachtung eines Ziels, disconnect() die aller Ziele. Prüfe, ob die Ausführungsumgebung die API unterstützt.

Beispiele

<!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>

Ergebnis

root matches: true
rootMargin: 0px 0px 40px 0px
thresholds: [0,0.5,1]
isIntersecting: true
intersectionRatio: 0.5

Speichere das Beispiel als HTML-Datei, öffne sie in einem aktiven Browsertab und prüfe die Ausgabe in der Entwicklerkonsole. Das Ziel beginnt 20 px unter dem unteren Rand der Wurzel. Der untere Zusatzrand von 40 px erfasst die halbe Zielhöhe über die gesamte Breite. Der erste Eintrag meldet daher `intersectionRatio: 0.5`. Der Code beendet die Beobachtung und entfernt die Demo-Elemente.

Zugehörige Lektionen

  • JavaScript · Lektion 30 · Mittlere Stufe · Version: 3

Quellen