IntersectionObserver.delay — Eigenschaft · JavaScript-Referenz

Signatur

IntersectionObserver.delay

Beschreibung

Die Eigenschaft delay gehört zu Intersection Observer v2. Sie gibt an, wie viele Millisekunden mindestens zwischen zwei Benachrichtigungen desselben Observers für ein Ziel-Element vergehen müssen. Gesetzt wird der Wert einmalig über die Option delay im Konstruktor new IntersectionObserver(callback, { delay }). Danach lässt er sich nur noch lesen.

Wichtig ist die Eigenschaft vor allem zusammen mit trackVisibility: true. In diesem Modus prüft der Browser nicht nur, ob sich ein Element mit dem Viewport überschneidet, sondern auch, ob es tatsächlich sichtbar ist, also nicht verdeckt, transformiert, gefiltert oder transparent. Das ist deutlich aufwendiger. Deshalb schreibt die Spezifikation für diesen Fall eine Verzögerung von mindestens 100 ms vor. Wer einen kleineren Wert angibt, bekommt ihn auf 100 angehoben.

Typische Einsatzfälle sind das Messen, ob Werbung wirklich gesehen wurde, der Schutz vor Clickjacking bei eingebetteten Widgets (etwa Like- oder Bezahl-Buttons in iframes) und das gezielte Drosseln sehr häufiger Callbacks. Ohne trackVisibility ist der Standardwert 0, es gibt dann also keine zusätzliche Drosselung.

Rückgabewert

Typ

number

Beschreibung

Die minimale Verzögerung zwischen zwei Benachrichtigungen in Millisekunden. Standardwert ist 0. Bei trackVisibility: true ist der Wert mindestens 100. In Browsern ohne Unterstützung für v2 liefert die Eigenschaft undefined.

Beispiele

Verzögerung beim Erzeugen setzen und auslesen

const observer = new IntersectionObserver(
  (entries) => entries.forEach((e) => console.log(e.isIntersecting)),
  { threshold: 0.5, delay: 250 }
);

console.log(observer.delay);

250

Anhebung auf 100 ms bei trackVisibility

const observer = new IntersectionObserver(() => {}, {
  trackVisibility: true,
  delay: 20 // zu klein für die Sichtbarkeitsprüfung
});

console.log(observer.trackVisibility, observer.delay);

true 100

Sichtbarkeit einer Werbefläche messen, mit Prüfung auf Unterstützung

const ad = document.querySelector('#ad-banner');

const supportsV2 = 'isVisible' in IntersectionObserverEntry.prototype;

const observer = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    // Ohne v2-Unterstützung auf isIntersecting zurückfallen
    const seen = supportsV2 ? entry.isVisible : entry.isIntersecting;
    if (seen) {
      console.log(`Werbung sichtbar (Prüfintervall: ${observer.delay ?? 0} ms)`);
      observer.unobserve(entry.target);
    }
  }
}, {
  threshold: 1.0,
  trackVisibility: true,
  delay: 500
});

observer.observe(ad);

Werbung sichtbar (Prüfintervall: 500 ms)

Nachträgliches Zuweisen hat keine Wirkung

'use strict';
const observer = new IntersectionObserver(() => {}, { delay: 100 });

try {
  observer.delay = 1000; // Eigenschaft ist schreibgeschützt
} catch (err) {
  console.log(err instanceof TypeError);
}
console.log(observer.delay);

true 100

// Wichtig · Fallstricke

Browser-Kompatibilität: delay gehört zu Intersection Observer v2 und wird nur von Chromium-Browsern unterstützt (Chrome, Edge, Opera ab Version 74). Firefox und Safari ignorieren die Option. Dort ist observer.delay undefined. Prüfe die Unterstützung zum Beispiel mit 'delay' in IntersectionObserver.prototype.
Schreibgeschützt: Der Wert lässt sich nur im Konstruktor festlegen. Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus. Für einen anderen Wert muss ein neuer Observer erzeugt werden.
Mindestwert: Bei trackVisibility: true werden Werte unter 100 auf 100 ms angehoben. Ältere Chromium-Versionen haben hier stattdessen einen Fehler ausgelöst.
Performance: Die Sichtbarkeitsprüfung ist teuer. Wähle delay so groß, wie es der Anwendungsfall erlaubt (für Werbemessung sind 500–1000 ms üblich), und rufe unobserve() auf, sobald das Ergebnis feststeht.
Kein exakter Takt: delay ist eine Mindest-Verzögerung. Benachrichtigungen können später eintreffen, weil sie weiterhin an das Rendering gebunden sind.

Siehe auch

IntersectionObserver.root IntersectionObserver.thresholds IntersectionObserver.rootMargin IntersectionObserver.scrollMargin IntersectionObserver.trackVisibility