IntersectionObserver: IntersectionObserver() Konstruktor
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2019.
Der IntersectionObserver()
Konstruktor erstellt und gibt ein neues IntersectionObserver
-Objekt zurück.
Syntax
new IntersectionObserver(callback)
new IntersectionObserver(callback, options)
Parameter
callback
-
Eine Funktion, die aufgerufen wird, wenn der Prozentsatz des sichtbaren Bereichs des Ziel-Elements einen Schwellenwert überschreitet. Der Callback erhält zwei Eingabeparameter:
entries
-
Ein Array von
IntersectionObserverEntry
-Objekten, die jeweils einen Schwellenwert repräsentieren, der überschritten wurde, indem der sichtbare Anteil entweder größer oder kleiner als der durch den Schwellenwert angegebene Prozentsatz wird. Sie sollten nicht von der Anzahl der Einträge ausgehen, denn mehrere Schwellenwert-Überschreitungen können in einem einzigen Callback-Aufruf gemeldet werden. Die Einträge werden über eine Warteschlange verteilt, daher sollten sie nach der Zeit geordnet sein, zu der sie erstellt wurden. Es ist jedoch empfehlenswert,IntersectionObserverEntry.time
zu verwenden, um sie korrekt zu ordnen. observer
-
Der
IntersectionObserver
, für den der Callback aufgerufen wird.
options
Optional-
Ein optionales Objekt, das den Beobachter anpasst.
Sie können jede Kombination (oder keine) der folgenden Optionen bereitstellen:
delay
-
Eine Zahl, die die minimale erlaubte Verzögerung zwischen Benachrichtigungen des Beobachters in Millisekunden angibt.
Die Verzögerung wird verwendet, um die Häufigkeit der Benachrichtigungen zu begrenzen, wenn die Sichtbarkeit verfolgt wird, da dies eine rechnerintensive Operation ist. Die Empfehlung beim Verfolgen der Sichtbarkeit ist, die Verzögerung auf den größtmöglichen akzeptablen Wert einzustellen.
Wenn
trackVisibility
true
ist, beträgt der Mindestwert 100. Der Browser setzt den Wert auf 100, wenn ein kleinerer Wert verwendet wird oder der Wert nicht angegeben ist. Der Standardwert ist 0. root
-
Ein
Element
- oderDocument
-Objekt, das ein Vorfahre des vorgesehenen Ziels ist und dessen Begrenzungsrechteck als Ansichtfenster betrachtet wird. Jede nicht im sichtbaren Bereich desroot
sichtbare Teile des Ziels werden als nicht sichtbar betrachtet. Falls nicht angegeben, verwendet der Beobachter das Ansichtsfenster des Dokuments als root, ohne Rand, und einen Schwellenwert von 0 % (was bedeutet, dass sogar eine Änderung um einen Pixel ausreicht, um einen Callback auszulösen). rootMargin
-
Ein String, der eine Anzahl von Offsets angibt, die zur Berechnung der Schnittstellen dem Begrenzungsrahmen des root hinzugefügt werden, wodurch der root für Berechnungszwecke effektiv verkleinert oder vergrößert wird. Die Syntax ist in etwa die gleiche wie die für die CSS
margin
-Eigenschaft; siehe The intersection root and root margin für weitere Informationen darüber, wie der Rand funktioniert und die Syntax. Der Standard ist "0px 0px 0px 0px". scrollMargin
-
Ein String, der die Offsets angibt, die jedem rollenden Container auf dem Weg zum Ziel hinzugefügt werden, um die Schnittstellen zu berechnen, wodurch die Clip-Rechtecke effektiv verkleinert oder vergrößert werden, die zur Berechnung der Schnittstellen verwendet werden. Dies ermöglicht zum Beispiel eine bessere Beobachtung von Zielen innerhalb verschachtelter, derzeit von den rollenden Containern abgeschnittener Scroll-Container. Die Syntax ist in etwa die gleiche wie die für die CSS
margin
-Eigenschaft. Der Standard ist "0px 0px 0px 0px". threshold
-
Entweder eine einzelne Zahl oder ein Array von Zahlen zwischen 0,0 und 1,0, die ein Verhältnis des Schnittflächenbereichs zum gesamten Begrenzungsrahmenbereich für das beobachtete Ziel angeben. Ein Wert von 0,0 bedeutet, dass selbst ein einzelnes sichtbares Pixel als sichtbar für das Ziel angesehen wird. 1,0 bedeutet, dass das gesamte Ziel-Element sichtbar ist. Siehe Thresholds für eine detailliertere Beschreibung, wie Schwellenwerte verwendet werden. Der Standard ist ein Schwellenwert von "0".
trackVisibility
-
Ein Boolean, das anzeigt, ob der Beobachter die Sichtbarkeit verfolgen soll.
Wenn
true
, überprüft der Browser, dass das Ziel keine beeinträchtigte Sichtbarkeit aufweist, wenn Schnittstellen berechnet werden; zum Beispiel, dass es nicht von anderen Elementen bedeckt wurde oder möglicherweise durch einen Filter, verringerte Deckkraft oder eine Transformation verzerrt oder verdeckt wurde.Die Verfolgung der Sichtbarkeit ist eine ressourcenintensive Operation und sollte nur bei Bedarf durchgeführt werden. Ein
delay
sollte ebenfalls gesetzt werden, wenn dieser Werttrue
ist. Der Standardwert istfalse
.
Rückgabewert
Ein neuer IntersectionObserver
, der verwendet werden kann, um die Sichtbarkeit eines Ziel-Elements innerhalb des angegebenen root
beim Überschreiten der spezifizierten Sichtbarkeits-threshold
s zu beobachten.
Rufen Sie dessen observe()
-Methode auf, um mit der Beobachtung von Sichtbarkeitsänderungen für ein gegebenes Ziel zu beginnen.
Ausnahmen
SyntaxError
DOMException
-
Der angegebene
rootMargin
oderscrollMargin
ist ungültig. RangeError
-
Einer oder mehrere der Werte in
threshold
liegen außerhalb des Bereichs 0,0 bis 1,0.
Beispiele
Dieses Beispiel erstellt einen neuen Schnittstellenbeobachter, der die Funktion myObserverCallback
jedes Mal aufruft, wenn der sichtbare Bereich des beobachteten Elements sich um mindestens 10 % verändert.
let observer = new IntersectionObserver(myObserverCallback, { threshold: 0.1 });
Spezifikationen
Specification |
---|
Intersection Observer # dom-intersectionobserver-intersectionobserver |