new IntersectionObserverEntry() — Methode · JavaScript-Referenz

Signatur

new IntersectionObserverEntry(intersectionObserverEntryInit)

Beschreibung

Der Konstruktor IntersectionObserverEntry() ist in der Intersection-Observer-Spezifikation beschrieben und soll aus einem Init-Objekt einen Eintrag erzeugen. Der Eintrag beschreibt, wie sich ein Zielelement zu einem bestimmten Zeitpunkt mit dem Root-Element (oder dem Viewport) überschneidet. Normalerweise legt man solche Objekte nie selbst an: Der Browser erzeugt sie und übergibt sie als Array an den Callback eines IntersectionObserver.

Einen eigenen Konstruktoraufruf bräuchte man höchstens für Unit-Tests, Polyfills oder Simulationen, also immer dann, wenn man Callback-Logik ohne echtes Scrollen und Layout prüfen will. In der Praxis werfen aktuelle Browser beim direkten Aufruf allerdings meist einen TypeError („Illegal constructor“). Für Tests nimmt man deshalb in der Regel einfache Objekte, die dieselbe Form haben (Duck Typing).

Die Felder des Init-Objekts entsprechen den schreibgeschützten Eigenschaften des Eintrags: time, rootBounds, boundingClientRect, intersectionRect, isIntersecting, intersectionRatio und target.

Parameter

Name	Typ	Default	Beschreibung
$intersectionObserverEntryInit Pflicht	Object		Init-Dictionary mit den folgenden Feldern: `time` (`number`): Zeitstempel als `DOMHighResTimeStamp`, gemessen ab dem Zeitursprung des Dokuments. `rootBounds` (`DOMRectInit \| null`): Rechteck des Root-Bereichs. `boundingClientRect` (`DOMRectInit`): Begrenzungsrechteck des Zielelements. `intersectionRect` (`DOMRectInit`): sichtbarer Überschneidungsbereich. `isIntersecting` (`boolean`): ob sich Ziel und Root überschneiden. `intersectionRatio` (`number`): sichtbarer Anteil von `0` bis `1`. `target` (`Element`): das beobachtete Element.

Rückgabewert

Typ

IntersectionObserverEntry

Beschreibung

Ein neues IntersectionObserverEntry-Objekt mit den übergebenen Werten, sofern der Browser den Konstruktor unterstützt. Andernfalls wird ein TypeError geworfen.

Beispiele

Konstruktor aufrufen und prüfen, ob er unterstützt wird

const target = document.createElement('div');

const init = {
  time: performance.now(),
  rootBounds: { x: 0, y: 0, width: 1024, height: 768 },
  boundingClientRect: { x: 0, y: 700, width: 200, height: 100 },
  intersectionRect: { x: 0, y: 700, width: 200, height: 68 },
  isIntersecting: true,
  intersectionRatio: 0.68,
  target
};

try {
  const entry = new IntersectionObserverEntry(init);
  console.log(entry.isIntersecting, entry.intersectionRatio);
} catch (err) {
  // In den meisten Browsern landet man hier
  console.log(`Nicht unterstützt: ${err.name}`);
}

Nicht unterstützt: TypeError

Test-Attrappe für Callback-Logik (Lazy Loading)

// Callback, die man testen möchte
const onIntersect = (entries, observer) => {
  for (const entry of entries) {
    if (entry.isIntersecting) {
      entry.target.src = entry.target.dataset.src;
      observer.unobserve(entry.target);
    }
  }
};

// Eintrag mit gleicher Form wie ein echter IntersectionObserverEntry
const createFakeEntry = (target, ratio) => ({
  time: performance.now(),
  rootBounds: new DOMRectReadOnly(0, 0, 1024, 768),
  boundingClientRect: target.getBoundingClientRect(),
  intersectionRect: new DOMRectReadOnly(0, 0, 100 * ratio, 100),
  isIntersecting: ratio > 0,
  intersectionRatio: ratio,
  target
});

const img = document.createElement('img');
img.dataset.src = 'https://example.com/bild.jpg';

const fakeObserver = { unobserve: (el) => console.log('unobserve', el.tagName) };
onIntersect([createFakeEntry(img, 0.5)], fakeObserver);
console.log(img.src);

unobserve IMG https://example.com/bild.jpg

Der übliche Weg: Einträge vom Browser erhalten

const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    console.log(entry instanceof IntersectionObserverEntry); // true
    console.log(`${entry.target.id}: ${Math.round(entry.intersectionRatio * 100)} % sichtbar`);
  });
}, { threshold: [0, 0.5, 1] });

observer.observe(document.querySelector('#footer'));

true footer: 0 % sichtbar

// Wichtig · Fallstricke

Kaum nutzbar: Obwohl die Spezifikation den Konstruktor beschreibt, werfen Chrome, Firefox und Safari beim direkten Aufruf meist TypeError: Illegal constructor. Den Aufruf daher immer mit try…catch absichern oder ganz vermeiden.
Für Tests: Nimm einfache Objekte mit denselben Eigenschaften (siehe Beispiel). Beachte aber, dass eine solche Attrappe instanceof IntersectionObserverEntry nicht besteht. Prüft dein Code auf den Typ, brauchst du einen Mock der Klasse, zum Beispiel in Jest oder jsdom, wo IntersectionObserver ohnehin fehlt.
Echte Einträge sind schreibgeschützt. Ihre Rechtecke sind DOMRectReadOnly-Objekte, und rootBounds kann bei Iframes mit anderem Ursprung null sein.
time ist relativ zu performance.timeOrigin und kein Unix-Zeitstempel.

Siehe auch

new GPUInternalError() new IntersectionObserver() new MutationObserver() new InterestEvent() new FileSystemObserver()