Virtualizer

Die Virtualizer-Klasse ist der Kern von TanStack Virtual. Virtualizer-Instanzen werden normalerweise für Sie von Ihrem Framework-Adapter erstellt, aber Sie erhalten den Virtualizer direkt.

export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
  constructor(options: VirtualizerOptions<TScrollElement, TItemElement>)
}

export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
  constructor(options: VirtualizerOptions<TScrollElement, TItemElement>)
}

count: number

count: number

Die Gesamtzahl der zu virtualisierenden Elemente.

getScrollElement: () => TScrollElement

getScrollElement: () => TScrollElement

Eine Funktion, die das scrollbare Element für den Virtualizer zurückgibt. Sie kann null zurückgeben, wenn das Element noch nicht verfügbar ist.

estimateSize: (index: number) => number

estimateSize: (index: number) => number

🧠 Wenn Sie Ihre Elemente dynamisch messen, wird empfohlen, die größtmögliche Größe (Breite/Höhe, im angenehmen Bereich) Ihrer Elemente abzuschätzen. Dies stellt sicher, dass Funktionen wie sanftes Scrollen besser funktionieren.

Diese Funktion erhält den Index jedes Elements und sollte die tatsächliche Größe (oder eine geschätzte Größe, wenn Sie Elemente dynamisch mit virtualItem.measureElement messen werden) für jedes Element zurückgeben. Diese Messung sollte entweder die Breite oder die Höhe zurückgeben, abhängig von der Ausrichtung Ihres Virtualizers.

enabled?: boolean

enabled?: boolean

Setzen Sie dies auf false, um ScrollElement-Observer zu deaktivieren und den Zustand des Virtualizers zurückzusetzen.

debug?: boolean

debug?: boolean

Setzen Sie dies auf true, um Debug-Logs zu aktivieren.

initialRect?: Rect

initialRect?: Rect

Das anfängliche Rect des scrollbaren Elements. Dies ist hauptsächlich nützlich, wenn Sie den Virtualizer in einer SSR-Umgebung ausführen müssen, andernfalls wird initialRect beim Mounten durch die observeElementRect-Implementierung berechnet.

onChange?: (instance: Virtualizer<TScrollElement, TItemElement>, sync: boolean) => void

onChange?: (instance: Virtualizer<TScrollElement, TItemElement>, sync: boolean) => void

Eine Callback-Funktion, die aufgerufen wird, wenn sich der interne Zustand des Virtualizers ändert. Sie erhält die Virtualizer-Instanz und den Sync-Parameter.

Der Sync-Parameter gibt an, ob gerade gescrollt wird. Er ist true, wenn gescrollt wird, und false, wenn das Scrollen beendet wurde oder andere Aktionen (wie Größenänderungen) ausgeführt werden.

overscan?: number

overscan?: number

Die Anzahl der Elemente, die oberhalb und unterhalb des sichtbaren Bereichs gerendert werden sollen. Eine Erhöhung dieser Zahl verlängert die Renderzeit des Virtualizers, kann aber die Wahrscheinlichkeit verringern, dass beim Scrollen langsame, leere Elemente oben und unten im Virtualizer sichtbar werden. Der Standardwert ist 1.

horizontal?: boolean

horizontal?: boolean

Setzen Sie dies auf true, wenn Ihr Virtualizer horizontal ausgerichtet ist.

paddingStart?: number

paddingStart?: number

Das Padding, das am Anfang des Virtualizers in Pixeln angewendet werden soll.

paddingEnd?: number

paddingEnd?: number

Das Padding, das am Ende des Virtualizers in Pixeln angewendet werden soll.

scrollPaddingStart?: number

scrollPaddingStart?: number

Das Padding, das am Anfang des Virtualizers in Pixeln angewendet werden soll, wenn zu einem Element gescrollt wird.

scrollPaddingEnd?: number

scrollPaddingEnd?: number

Das Padding, das am Ende des Virtualizers in Pixeln angewendet werden soll, wenn zu einem Element gescrollt wird.

initialOffset?: number | (() => number)

initialOffset?: number | (() => number)

Die Position, zu der die Liste beim Rendern gescrollt wird. Dies ist nützlich, wenn Sie den Virtualizer in einer SSR-Umgebung rendern oder den Virtualizer bedingt rendern.

getItemKey?: (index: number) => Key

getItemKey?: (index: number) => Key

Diese Funktion erhält den Index jedes Elements und sollte einen eindeutigen Schlüssel für dieses Element zurückgeben. Die Standardfunktionalität dieser Funktion ist die Rückgabe des Indexes des Elements, aber Sie sollten diese überschreiben, wenn möglich, um eine eindeutige Kennung für jedes Element über den gesamten Satz zurückzugeben. Diese Funktion sollte memoisiert werden, um unnötige Neu-Renderings zu verhindern.

rangeExtractor?: (range: Range) => number[]

rangeExtractor?: (range: Range) => number[]

Diese Funktion erhält die Indizes des sichtbaren Bereichs und sollte ein Array von Indizes zurückgeben, die gerendert werden sollen. Dies ist nützlich, wenn Sie Elemente manuell zum Virtualizer hinzufügen oder entfernen müssen, unabhängig vom sichtbaren Bereich, z. B. zum Rendern von Sticky-Elementen, Headern, Footern usw. Die Standard-Implementierung des Range-Extrators gibt die sichtbaren Bereichsindizes zurück und wird als defaultRangeExtractor exportiert.

scrollToFn?: (
  offset: number,
  options: { adjustments?: number; behavior?: 'auto' | 'smooth' },
  instance: Virtualizer<TScrollElement, TItemElement>,
) => void

scrollToFn?: (
  offset: number,
  options: { adjustments?: number; behavior?: 'auto' | 'smooth' },
  instance: Virtualizer<TScrollElement, TItemElement>,
) => void

Eine optionale Funktion, die (falls vorhanden) das Scrollverhalten für Ihr scrollbares Element implementieren sollte. Sie wird mit den folgenden Argumenten aufgerufen

• Ein Offset (in Pixeln), zu dem gescrollt werden soll.
• Ein Objekt, das angibt, ob es einen Unterschied zwischen der geschätzten und der tatsächlichen Größe gab (adjustments) und/oder ob mit einer sanften Animation gescrollt wurde (behaviour).
• Die Virtualizer-Instanz selbst.

Beachten Sie, dass integrierte Scroll-Implementierungen als elementScroll und windowScroll exportiert werden, die automatisch von den Framework-Adapterfunktionen wie useVirtualizer oder useWindowVirtualizer konfiguriert werden.

⚠️ Der Versuch, smoothScroll mit dynamisch gemessenen Elementen zu verwenden, funktioniert nicht.

observeElementRect: (
  instance: Virtualizer<TScrollElement, TItemElement>,
  cb: (rect: Rect) => void,
) => void | (() => void)

observeElementRect: (
  instance: Virtualizer<TScrollElement, TItemElement>,
  cb: (rect: Rect) => void,
) => void | (() => void)

Eine optionale Funktion, die (falls vorhanden) aufgerufen wird, wenn sich das scrollbare Element ändert und die anfängliche Messung sowie die kontinuierliche Überwachung des Rect des scrollbaren Elements (ein Objekt mit width und height) implementieren sollte. Sie wird mit der Instanz aufgerufen (die Ihnen auch Zugriff auf das scrollbare Element über instance.scrollElement gibt. Integrierte Implementierungen werden als observeElementRect und observeWindowRect exportiert, die automatisch für Sie von den exportierten Funktionen Ihres Framework-Adapters wie useVirtualizer oder useWindowVirtualizer konfiguriert werden.

observeElementOffset: (
    instance: Virtualizer<TScrollElement, TItemElement>,
    cb: (offset: number) => void,
  ) => void | (() => void)

observeElementOffset: (
    instance: Virtualizer<TScrollElement, TItemElement>,
    cb: (offset: number) => void,
  ) => void | (() => void)

Eine optionale Funktion, die (falls vorhanden) aufgerufen wird, wenn sich das scrollbare Element ändert und die anfängliche Messung sowie die kontinuierliche Überwachung des Scroll-Offsets des scrollbaren Elements (eine Zahl) implementieren sollte. Sie wird mit der Instanz aufgerufen (die Ihnen auch Zugriff auf das scrollbare Element über instance.scrollElement gibt. Integrierte Implementierungen werden als observeElementOffset und observeWindowOffset exportiert, die automatisch für Sie von den exportierten Funktionen Ihres Framework-Adapters wie useVirtualizer oder useWindowVirtualizer konfiguriert werden.

measureElement?: (
  element: TItemElement,
  entry: ResizeObserverEntry | undefined,
  instance: Virtualizer<TScrollElement, TItemElement>,
) => number

measureElement?: (
  element: TItemElement,
  entry: ResizeObserverEntry | undefined,
  instance: Virtualizer<TScrollElement, TItemElement>,
) => number

Diese optionale Funktion wird aufgerufen, wenn der Virtualizer die Größe (Breite oder Höhe) eines Elements dynamisch messen muss.

🧠 Sie können instance.options.horizontal verwenden, um festzustellen, ob die Breite oder Höhe des Elements gemessen werden soll.

scrollMargin?: number

scrollMargin?: number

Mit dieser Option können Sie festlegen, woher der Scroll-Offset stammt. Typischerweise repräsentiert dieser Wert den Abstand zwischen dem Anfang des scrollbaren Elements und dem Beginn der Liste. Dies ist besonders nützlich in gängigen Szenarien, wie z. B. wenn ein Header einem Window Virtualizer vorausgeht oder wenn mehrere Virtualizer innerhalb eines einzigen scrollbaren Elements verwendet werden. Wenn Sie Elemente absolut positionieren, sollten Sie den scrollMargin in Ihrer CSS-Transformation berücksichtigen.

transform: `translateY(${
   virtualRow.start - rowVirtualizer.options.scrollMargin
}px)` 

transform: `translateY(${
   virtualRow.start - rowVirtualizer.options.scrollMargin
}px)` 

Um den Wert für scrollMargin dynamisch zu messen, können Sie getBoundingClientRect() oder ResizeObserver verwenden. Dies ist hilfreich in Szenarien, in denen sich die Höhe von Elementen oberhalb Ihrer virtuellen Liste ändern könnte.

gap?: number

gap?: number

Diese Option ermöglicht es Ihnen, den Abstand zwischen den Elementen in der virtualisierten Liste festzulegen. Sie ist besonders nützlich, um eine konsistente visuelle Trennung zwischen den Elementen aufrechtzuerhalten, ohne jeden Rand oder jedes Polster jedes Elements manuell anpassen zu müssen. Der Wert wird in Pixeln angegeben.

lanes: number

lanes: number

Die Anzahl der Bahnen, in die die Liste unterteilt ist (auch Spalten für vertikale Listen und Zeilen für horizontale Listen genannt).

isScrollingResetDelay: number

isScrollingResetDelay: number

Diese Option ermöglicht es Ihnen, die Wartezeit nach dem letzten Scroll-Ereignis festzulegen, bevor die `isScrolling`-Instanzeigenschaft zurückgesetzt wird. Der Standardwert ist 150 Millisekunden.

Die Implementierung dieser Option ergibt sich aus der Notwendigkeit eines zuverlässigen Mechanismus zur Handhabung des Scrollverhaltens über verschiedene Browser hinweg. Bis alle Browser das `scrollEnd`-Ereignis einheitlich unterstützen.

useScrollendEvent: boolean

useScrollendEvent: boolean

Bestimmt, ob das native `scrollend`-Ereignis verwendet werden soll, um zu erkennen, wann das Scrollen beendet wurde. Wenn auf `false` gesetzt, wird ein entprellter Fallback verwendet, um die `isScrolling`-Instanzeigenschaft nach `isScrollingResetDelay` Millisekunden zurückzusetzen. Der Standardwert ist false.

Die Implementierung dieser Option ergibt sich aus der Notwendigkeit eines zuverlässigen Mechanismus zur Handhabung des Scrollverhaltens über verschiedene Browser hinweg. Bis alle Browser das `scrollEnd`-Ereignis einheitlich unterstützen.

isRtl: boolean

isRtl: boolean

Ob das horizontale Scrollen invertiert werden soll, um Rechts-nach-Links-Sprachregionen zu unterstützen.

useAnimationFrameWithResizeObserver: boolean

useAnimationFrameWithResizeObserver: boolean

Diese Option ermöglicht das Einpacken von ResizeObserver-Messungen in `requestAnimationFrame` für sanftere Updates und reduziertes Layout-Thrashing. Der Standardwert ist false.

Es hilft, den Fehler "ResizeObserver loop completed with undelivered notifications" zu vermeiden, indem sichergestellt wird, dass Messungen mit dem Renderzyklus übereinstimmen. Dies kann die Leistung verbessern und UI-Jitter reduzieren, insbesondere beim dynamischen Ändern der Größe von Elementen. Da ResizeObserver jedoch bereits asynchron ausgeführt wird, kann das Hinzufügen von `requestAnimationFrame` zu einer leichten Verzögerung bei den Messungen führen, was in einigen Fällen spürbar sein könnte. Wenn Größenänderungsoperationen leichtgewichtig sind und keine Reflows verursachen, bietet die Aktivierung dieser Option möglicherweise keine signifikanten Vorteile.

Die folgenden Eigenschaften und Methoden sind auf der Virtualizer-Instanz verfügbar

options: readonly Required<VirtualizerOptions<TScrollElement, TItemElement>>

options: readonly Required<VirtualizerOptions<TScrollElement, TItemElement>>

Die aktuellen Optionen für den Virtualizer. Diese Eigenschaft wird über Ihren Framework-Adapter aktualisiert und ist schreibgeschützt.

scrollElement: readonly TScrollElement | null

scrollElement: readonly TScrollElement | null

Das aktuelle scrollbare Element für den Virtualizer. Diese Eigenschaft wird über Ihren Framework-Adapter aktualisiert und ist schreibgeschützt.

type getVirtualItems = () => VirtualItem[]

type getVirtualItems = () => VirtualItem[]

Gibt die virtuellen Elemente für den aktuellen Zustand des Virtualizers zurück.

type getVirtualIndexes = () => number[]

type getVirtualIndexes = () => number[]

Gibt die virtuellen Zeilenindizes für den aktuellen Zustand des Virtualizers zurück.

scrollToOffset: (
  toOffset: number,
  options?: {
    align?: 'start' | 'center' | 'end' | 'auto',
    behavior?: 'auto' | 'smooth'
  }
) => void

scrollToOffset: (
  toOffset: number,
  options?: {
    align?: 'start' | 'center' | 'end' | 'auto',
    behavior?: 'auto' | 'smooth'
  }
) => void

Scrollt den Virtualizer zum angegebenen Pixel-Offset. Sie können optional einen Ausrichtungsmodus angeben, um das Scrollen an einem bestimmten Teil des scrollbaren Elements zu verankern.

scrollToIndex: (
  index: number,
  options?: {
    align?: 'start' | 'center' | 'end' | 'auto',
    behavior?: 'auto' | 'smooth'
  }
) => void

scrollToIndex: (
  index: number,
  options?: {
    align?: 'start' | 'center' | 'end' | 'auto',
    behavior?: 'auto' | 'smooth'
  }
) => void

Scrollt den Virtualizer zu den Elementen des angegebenen Indexes. Sie können optional einen Ausrichtungsmodus angeben, um das Scrollen an einem bestimmten Teil des scrollbaren Elements zu verankern.

getTotalSize: () => number

getTotalSize: () => number

Gibt die Gesamtgröße in Pixeln für die virtualisierten Elemente zurück. Diese Messung ändert sich inkrementell, wenn Sie Ihre Elemente dynamisch messen lassen, während sie gerendert werden.

measure: () => void

measure: () => void

Setzt alle vorherigen Elementmessungen zurück.

measureElement: (el: TItemElement | null) => void

measureElement: (el: TItemElement | null) => void

Misst das Element mit Ihrer konfigurierten measureElement-Option des Virtualizers. Sie sind dafür verantwortlich, diese in Ihrem Virtualizer-Markup aufzurufen, wenn die Komponente gerendert wird (z. B. mit der `ref`-Callback-Prop von React) und fügen Sie auch data-index hinzu.

 <div
  key={virtualRow.key}
  data-index={virtualRow.index}
  ref={virtualizer.measureElement}
  style={...}
>...</div>

 <div
  key={virtualRow.key}
  data-index={virtualRow.index}
  ref={virtualizer.measureElement}
  style={...}
>...</div>

Standardmäßig ist die measureElement-Option des Virtualizers so konfiguriert, dass Elemente mit getBoundingClientRect() gemessen werden.

resizeItem: (index: number, size: number) => void

resizeItem: (index: number, size: number) => void

Ändert die Größe des virtualisierten Elements manuell. Verwenden Sie diese Funktion, um die für diesen Index berechnete Größe manuell festzulegen. Nützlich in Fällen, in denen Sie eine benutzerdefinierte Morphing-Übergangsanimation verwenden und die Größe des morphigen Elements im Voraus kennen.

Sie können diese Methode auch mit einem throttled ResizeObserver anstelle von Virtualizer.measureElement verwenden, um Neu-Renderings zu reduzieren.

⚠️ Bitte beachten Sie, dass das manuelle Ändern der Größe eines Elements, wenn Sie Virtualizer.measureElement verwenden, um dieses Element zu überwachen, zu unvorhersehbarem Verhalten führt, da Virtualizer.measureElement ebenfalls die Größe ändert. Sie können jedoch `resizeItem` oder `measureElement` in derselben Virtualizer-Instanz, aber mit unterschiedlichen Elementindizes, verwenden.

scrollRect: Rect

scrollRect: Rect

Aktuelles Rect des scrollbaren Elements.

shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean)

shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean)

Die Methode `shouldAdjustScrollPositionOnItemSizeChange` ermöglicht eine feingranulare Kontrolle über die Anpassung der Scroll-Position, wenn die Größe dynamisch gerenderter Elemente von der geschätzten Größe abweicht. Wenn Sie sich mitten in der Liste befinden und rückwärts scrollen, können neue Elemente eine andere Größe als die ursprünglich geschätzte Größe haben. Diese Diskrepanz kann dazu führen, dass nachfolgende Elemente verschoben werden, was das Scroll-Erlebnis des Benutzers beeinträchtigen kann, insbesondere beim Navigieren rückwärts durch die Liste.

isScrolling: boolean

isScrolling: boolean

Boolesche Flagge, die angibt, ob die Liste gerade gescrollt wird.

scrollDirection: 'forward' | 'backward' | null

scrollDirection: 'forward' | 'backward' | null

Diese Option gibt die Scrollrichtung an, wobei mögliche Werte 'forward' für Scrollen nach unten und 'backward' für Scrollen nach oben sind. Der Wert ist null, wenn gerade nicht gescrollt wird.

scrollOffset: number

scrollOffset: number

Diese Option repräsentiert die aktuelle Scroll-Position entlang der Scroll-Achse. Sie wird in Pixeln vom Startpunkt des scrollbaren Bereichs gemessen.