WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

IntersectionObserverEntry: isIntersecting, intersectionRatio und target

Lies den Schnittzustand, den Flächenanteil und das beobachtete Element aus. Unterscheide den Schnittzustand vom Überqueren eines Schwellenwerts.

Version: Current web platform; runtime support varies

Syntax

entry.isIntersecting     // boolean
entry.intersectionRatio // number in [0, 1]
entry.target            // Element

Ein IntersectionObserverEntry hält den Zustand eines Ziels zum Messzeitpunkt fest. Die Callback-Funktion des Observers erhält die Einträge asynchron und kann mehrere auf einmal erhalten. entry.target ist dasselbe Element, das an observe() übergeben wurde, nicht root. Alle drei Eigenschaften sind schreibgeschützt, das Element selbst lässt sich aber weiterhin ändern. Die API gehört zur Webplattform, nicht zu ECMAScript 2024.

entry.isIntersecting ist ein boolescher Wert, der angibt, ob das Ziel bei dieser Messung den Bezugsbereich des Observers schneidet. Bei der Standardeinstellung root: null ist der Bezugsbereich der Viewport des obersten Dokuments, nicht der Viewport des iframe, in dem sich das Ziel befindet. Der Viewport des iframe kann die berechnete Schnittfläche dennoch begrenzen. true beschreibt einen Zustand, nicht unbedingt den Übergang in diesen Zustand. Laut Spezifikation kann auch eine bloße Kantenberührung bei einer Schnittfläche von null als Schnitt gelten.

entry.intersectionRatio ist eine Zahl von 0 bis 1: die Fläche von intersectionRect, geteilt durch die Fläche von boundingClientRect des Ziels, nicht durch die Fläche des Bezugsbereichs. Hat das Zielrechteck die Fläche null, lautet das Ergebnis bei isIntersecting gleich true 1, sonst 0. Standardmäßig wird nur die Geometrie gemessen. Das Ergebnis beweist nicht, dass kein anderes Element das Ziel verdeckt.

Nach observe() erhältst du auch dann einen ersten Eintrag, wenn das Ziel außerhalb des Bezugsbereichs liegt. Weitere Einträge können entstehen, wenn ein Schwellenwert in einer der beiden Richtungen überquert wird oder sich isIntersecting ändert. Nicht jede Änderung des Anteils erzeugt einen Eintrag. threshold: 0.5 setzt eine Benachrichtigungsschwelle; entry.intersectionRatio >= 0.5 prüft dagegen den Wert eines konkreten Eintrags.

Beispiele

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IntersectionObserverEntry example</title>
</head>
<body>
<script>
(() => {
  const root = document.createElement('div');
  root.style.cssText = 'position:relative;overflow:hidden;width:100px;height:100px';
  const target = document.createElement('div');
  target.style.cssText = 'position:absolute;left:0;top:50px;width:100px;height:100px;background:royalblue';
  root.append(target);
  document.body.append(root);

  let moved = false;
  const observer = new IntersectionObserver((entries) => {
    for (const entry of entries) {
      console.log(`${entry.isIntersecting} ${entry.intersectionRatio} ${entry.target === target}`);
      if (!moved) {
        moved = true;
        target.style.top = '150px';
      } else {
        observer.disconnect();
        root.remove();
      }
    }
  }, { root, threshold: 0.5 });
  observer.observe(target);
})();
</script>
</body>
</html>

Ergebnis

true 0.5 true
false 0 true

Speichere das Beispiel als HTML-Datei und öffne es in einem eigenen Tab in einem Browser, der die API unterstützt. Öffne die Entwicklerkonsole und lade die Seite neu. Der erste Eintrag zeigt, dass die Hälfte der Zielfläche im Bezugsbereich liegt. Der Code verschiebt das Ziel vollständig aus dem Bereich; der zweite Eintrag zeigt keinen Schnitt mehr. Beide Einträge beziehen sich auf dasselbe Element. Nach dem zweiten beendet der Code die Beobachtung und entfernt den Bezugsbereich.

Zugehörige Lektionen

  • JavaScript · Lektion 37 · Fortgeschritten · Version: 4

Quellen