IntersectionObserver.thresholds — Eigenschaft · JavaScript-Referenz

Signatur

IntersectionObserver.thresholds

Beschreibung

Die Eigenschaft thresholds eines IntersectionObserver gibt die Liste der Schwellenwerte zurück, die beim Erzeugen über die Option threshold festgelegt wurden. Jeder Wert steht für einen Anteil der sichtbaren Fläche des beobachteten Elements (intersectionRatio) zwischen 0.0 (gar nicht sichtbar) und 1.0 (vollständig sichtbar). Überschreitet oder unterschreitet das Verhältnis einen dieser Werte, ruft der Browser den Callback auf.

Der Browser normalisiert die übergebene Option: Eine einzelne Zahl wird zu einem Array mit einem Element, die Werte werden aufsteigend sortiert, und fehlt die Option ganz, enthält thresholds den Wert [0]. So sehen Sie immer die tatsächlich verwendete Konfiguration und nicht die ursprüngliche Eingabe.

Nützlich ist die Eigenschaft vor allem beim Debuggen, in wiederverwendbaren Hilfsfunktionen, die einen fremden Observer entgegennehmen, oder wenn Sie im Callback prüfen wollen, welcher Schwellenwert gerade überschritten wurde. Die Eigenschaft ist schreibgeschützt: Wollen Sie andere Schwellenwerte, müssen Sie einen neuen Observer anlegen.

Rückgabewert

Typ

ReadonlyArray<number>

Beschreibung

Ein eingefrorenes, aufsteigend sortiertes Array von Zahlen zwischen 0.0 und 1.0. Wurde keine threshold-Option angegeben, ist der Wert [0].

Beispiele

Normalisierte Schwellenwerte auslesen

const callback = (entries) => {};

// Unsortiert übergeben – der Browser sortiert
const observer = new IntersectionObserver(callback, {
  threshold: [1, 0.25, 0.5, 0]
});
console.log(observer.thresholds);

// Einzelwert wird zum Array
const single = new IntersectionObserver(callback, { threshold: 0.75 });
console.log(single.thresholds);

// Ohne Option: Standardwert
const standard = new IntersectionObserver(callback);
console.log(standard.thresholds);

[0, 0.25, 0.5, 1] [0.75] [0]

Überschrittenen Schwellenwert im Callback ermitteln

const box = document.querySelector('#teaser');

const observer = new IntersectionObserver((entries, obs) => {
  for (const entry of entries) {
    // Größten Schwellenwert finden, der erreicht ist
    const reached = obs.thresholds
      .filter((t) => entry.intersectionRatio >= t)
      .at(-1) ?? 0;
    console.log(`Sichtbar zu mindestens ${reached * 100} %`);
  }
}, { threshold: [0, 0.5, 1] });

observer.observe(box);

Sichtbar zu mindestens 50 %

Feine Abstufung für Fortschrittsanzeige

// 101 Schwellenwerte: 0, 0.01, … 1
const steps = Array.from({ length: 101 }, (_, i) => i / 100);
const bar = document.querySelector('#progress');

const observer = new IntersectionObserver(([entry]) => {
  bar.style.width = `${Math.round(entry.intersectionRatio * 100)}%`;
}, { threshold: steps });

console.log(observer.thresholds.length);
observer.observe(document.querySelector('#artikel'));

101

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie observer.thresholds = [0.5] wird ignoriert (im Strict Mode TypeError). Das Array ist eingefroren; auch push() schlägt fehl. Für andere Werte einen neuen Observer erstellen.
Ungültige Werte: Liegt ein Wert der threshold-Option außerhalb von 0–1 oder ist er keine Zahl, wirft bereits der Konstruktor einen RangeError.
Kein exaktes Treffen: Der Callback feuert, wenn ein Schwellenwert überschritten wird – intersectionRatio entspricht dabei selten exakt dem Schwellenwert. Vergleichen Sie daher mit >= statt ===.
Performance: Sehr viele Schwellenwerte (z. B. 1000) erhöhen die Zahl der Callback-Aufrufe beim Scrollen; halten Sie den Callback schlank.
Kompatibilität: Unterstützt in allen modernen Browsern (Chrome 51+, Firefox 55+, Safari 12.1+, Edge 15+). Nicht im Internet Explorer; dort ist ein Polyfill nötig. Außerhalb von Browsern (z. B. Node.js) nicht verfügbar.

Siehe auch

IntersectionObserver.delay IntersectionObserver.root IntersectionObserver.rootMargin IntersectionObserver.scrollMargin IntersectionObserver.trackVisibility