countgetScrollElementestimateSizeenableddebuginitialRectonChangeoverscanhorizontalpaddingStartpaddingEndscrollPaddingStartscrollPaddingEndinitialOffsetgetItemKeyrangeExtractorscrollToFnobserveElementRectobserveElementOffsetmeasureElementscrollMargingaplanesisScrollingResetDelayuseScrollendEventisRtluseAnimationFrameWithResizeObserveroptionsscrollElementgetVirtualItemsgetVirtualIndexesscrollToOffsetscrollToIndexgetTotalSizemeasuremeasureElementresizeItemscrollRectshouldAdjustScrollPositionOnItemSizeChangeisScrollingscrollDirectionscrollOffsetVirtualizer 类是 TanStack Virtual 的核心。Virtualizer 实例通常由你的框架适配器为你创建，但你确实会直接收到 virtualizer。
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
要虚拟化的项目总数。
getScrollElement: () => TScrollElement
getScrollElement: () => TScrollElement
一个返回虚拟器可滚动元素的函数。如果元素尚不可用，它可能返回 null。
estimateSize: (index: number) => number
estimateSize: (index: number) => number
🧠 如果你正在动态测量元素，建议估算项目可能的最大尺寸（宽度/高度，在舒适范围内）。这将确保平滑滚动等功能有更好的机会正常工作。
此函数传递每个项目的索引，并应返回每个项目的实际大小（或者如果你将使用 virtualItem.measureElement 动态测量项目，则返回估计大小）。此测量应根据虚拟器的方向返回宽度或高度。
enabled?: boolean
enabled?: boolean
设置为 false 以禁用 scrollElement 观察器并重置虚拟器的状态。
debug?: boolean
debug?: boolean
设置为 true 以启用调试日志。
initialRect?: Rect
initialRect?: Rect
scrollElement 的初始 Rect。这主要在需要在 SSR 环境中运行虚拟器时有用，否则 initialRect 将在挂载时由 observeElementRect 实现计算。
onChange?: (instance: Virtualizer<TScrollElement, TItemElement>, sync: boolean) => void
onChange?: (instance: Virtualizer<TScrollElement, TItemElement>, sync: boolean) => void
当虚拟器的内部状态更改时触发的回调函数。它传递虚拟器实例和 sync 参数。
sync 参数指示当前是否正在进行滚动。滚动正在进行时为 true，滚动已停止或正在执行其他操作（例如调整大小）时为 false。
overscan?: number
overscan?: number
在可见区域上方和下方渲染的项目数。增加此数字会增加渲染虚拟器所需的时间，但可能会减少滚动时在虚拟器顶部和底部看到缓慢渲染的空白项目的可能性。默认值为 1。
horizontal?: boolean
horizontal?: boolean
如果你的虚拟器是水平定向的，则将其设置为 true。
paddingStart?: number
paddingStart?: number
以像素为单位应用于虚拟器开头的内边距。
paddingEnd?: number
paddingEnd?: number
以像素为单位应用于虚拟器末尾的内边距。
scrollPaddingStart?: number
scrollPaddingStart?: number
滚动到元素时以像素为单位应用于虚拟器开头的内边距。
scrollPaddingEnd?: number
scrollPaddingEnd?: number
滚动到元素时以像素为单位应用于虚拟器末尾的内边距。
initialOffset?: number | (() => number)
initialOffset?: number | (() => number)
应用于虚拟器的初始偏移量。这通常仅在 SSR 环境中渲染虚拟器时有用。
getItemKey?: (index: number) => Key
getItemKey?: (index: number) => Key
此函数传递每个项目的索引，并应为该项目返回一个唯一的键。此函数的默认功能是返回项目的索引，但你应该尽可能覆盖此函数以返回整个集合中每个项目的唯一标识符。此函数应进行记忆化以防止不必要的重新渲染。
rangeExtractor?: (range: Range) => number[]
rangeExtractor?: (range: Range) => number[]
此函数接收可见范围索引，并应返回要渲染的索引数组。如果你需要手动从虚拟器中添加或删除项目，而不管可见范围如何（例如渲染粘性项目、页眉、页脚等），这很有用。默认范围提取器实现将返回可见范围索引，并导出为 defaultRangeExtractor。
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
一个可选函数，（如果提供）应为你的 scrollElement 实现滚动行为。它将使用以下参数调用：
请注意，内置滚动实现导出为 elementScroll 和 windowScroll，它们由框架适配器函数（如 useVirtualizer 或 useWindowVirtualizer）自动配置。
⚠️ 尝试将 smoothScroll 与动态测量的元素一起使用将不起作用。
observeElementRect: (
instance: Virtualizer<TScrollElement, TItemElement>,
cb: (rect: Rect) => void,
) => void | (() => void)
observeElementRect: (
instance: Virtualizer<TScrollElement, TItemElement>,
cb: (rect: Rect) => void,
) => void | (() => void)
一个可选函数，如果提供，则在 scrollElement 更改时调用，并应实现 scrollElement 的 Rect（具有 width 和 height 的对象）的初始测量和持续监控。它使用实例调用（这也使你可以通过 instance.scrollElement 访问 scrollElement）。内置实现导出为 observeElementRect 和 observeWindowRect，它们由框架适配器的导出函数（如 useVirtualizer 或 useWindowVirtualizer）自动为你配置。
observeElementOffset: (
instance: Virtualizer<TScrollElement, TItemElement>,
cb: (offset: number) => void,
) => void | (() => void)
observeElementOffset: (
instance: Virtualizer<TScrollElement, TItemElement>,
cb: (offset: number) => void,
) => void | (() => void)
一个可选函数，如果提供，则在 scrollElement 更改时调用，并应实现 scrollElement 的滚动偏移量（一个数字）的初始测量和持续监控。它使用实例调用（这也使你可以通过 instance.scrollElement 访问 scrollElement）。内置实现导出为 observeElementOffset 和 observeWindowOffset，它们由框架适配器的导出函数（如 useVirtualizer 或 useWindowVirtualizer）自动为你配置。
measureElement?: (
element: TItemElement,
entry: ResizeObserverEntry | undefined,
instance: Virtualizer<TScrollElement, TItemElement>,
) => number
measureElement?: (
element: TItemElement,
entry: ResizeObserverEntry | undefined,
instance: Virtualizer<TScrollElement, TItemElement>,
) => number
当虚拟器需要动态测量项目的大小（宽度或高度）时，将调用此可选函数。
🧠 你可以使用 instance.options.horizontal 来确定应测量项目的宽度还是高度。
scrollMargin?: number
scrollMargin?: number
使用此选项，你可以指定滚动偏移量的起点。通常，此值表示滚动元素的开头与列表开头之间的空间。这在常见场景中特别有用，例如在窗口虚拟器之前有一个页眉，或者在单个滚动元素中使用多个虚拟器时。如果使用元素的绝对定位，则应在 CSS 变换中考虑 scrollMargin：
transform: `translateY(${
virtualRow.start - rowVirtualizer.options.scrollMargin
}px)`
transform: `translateY(${
virtualRow.start - rowVirtualizer.options.scrollMargin
}px)`
要动态测量 scrollMargin 的值，可以使用 getBoundingClientRect() 或 ResizeObserver。这在虚拟列表上方的项目可能会更改其高度的场景中很有用。
gap?: number
gap?: number
此选项允许你设置虚拟化列表中项目之间的间距。这对于在项目之间保持一致的视觉分离特别有用，而无需手动调整每个项目的边距或内边距。该值以像素为单位指定。
lanes: number
lanes: number
列表划分的通道数（也称为垂直列表的列和水平列表的行）。
isScrollingResetDelay: number
isScrollingResetDelay: number
此选项允许你指定在最后一次滚动事件之后等待多长时间才重置 isScrolling 实例属性。默认值为 150 毫秒。
此选项的实现是为了在不同浏览器中处理滚动行为提供可靠的机制。直到所有浏览器统一支持 scrollEnd 事件。
useScrollendEvent: boolean
useScrollendEvent: boolean
确定是否使用本机 scrollend 事件来检测滚动何时停止。如果设置为 false，则使用防抖回退在 isScrollingResetDelay 毫秒后重置 isScrolling 实例属性。默认值为 false。
此选项的实现是为了在不同浏览器中处理滚动行为提供可靠的机制。直到所有浏览器统一支持 scrollEnd 事件。
isRtl: boolean
isRtl: boolean
是否反转水平滚动以支持从右到左的语言区域设置。
useAnimationFrameWithResizeObserver: boolean
useAnimationFrameWithResizeObserver: boolean
此选项启用将 ResizeObserver 测量包装在 requestAnimationFrame 中，以实现更平滑的更新并减少布局抖动。默认值为 false。
它通过确保测量与渲染周期对齐来帮助防止“ResizeObserver 循环已完成但有未传递的通知”错误。这可以提高性能并减少 UI抖动，尤其是在动态调整元素大小时。但是，由于 ResizeObserver 已经异步运行，因此添加 requestAnimationFrame 可能会在测量中引入轻微的延迟，这在某些情况下可能会很明显。如果调整大小操作是轻量级的并且不会导致重排，则启用此选项可能不会提供显着的好处。
虚拟器实例上提供了以下属性和方法：
options: readonly Required<VirtualizerOptions<TScrollElement, TItemElement>>
options: readonly Required<VirtualizerOptions<TScrollElement, TItemElement>>
虚拟器的当前选项。此属性通过你的框架适配器更新并且是只读的。
scrollElement: readonly TScrollElement | null
scrollElement: readonly TScrollElement | null
虚拟器的当前 scrollElement。此属性通过你的框架适配器更新并且是只读的。
type getVirtualItems = () => VirtualItem[]
type getVirtualItems = () => VirtualItem[]
返回虚拟器当前状态的虚拟项目。
type getVirtualIndexes = () => number[]
type getVirtualIndexes = () => number[]
返回虚拟器当前状态的虚拟行索引。
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
将虚拟器滚动到提供的像素偏移量。你可以选择传递对齐模式以将滚动锚定到 scrollElement 的特定部分。
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
将虚拟器滚动到所提供索引的项目。你可以选择传递对齐模式以将滚动锚定到 scrollElement 的特定部分。
getTotalSize: () => number
getTotalSize: () => number
返回虚拟化项目的总大小（以像素为单位）。如果你选择在渲染元素时动态测量它们，则此测量值将逐渐更改。
measure: () => void
measure: () => void
重置任何先前的项目测量。
measureElement: (el: TItemElement | null) => void
measureElement: (el: TItemElement | null) => void
使用配置的 measureElement 虚���器选项测量元素。你负责在渲染组件时在虚拟器标记中调用此函数（例如，使用 React 的 ref 回调 prop 之类的东西），同时还要添加 data-index
<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>
默认情况下，measureElement 虚拟器选项配置为使用 getBoundingClientRect() 测量元素。
resizeItem: (index: number, size: number) => void
resizeItem: (index: number, size: number) => void
手动更改虚拟化项目的大小。使用此函数手动设置为此索引计算的大小。在某些自定义变形过渡的情况下很有用，并且你事先知道变形项目的大小。
你还可以将此方法与节流的 ResizeObserver 一起使用，而不是 Virtualizer.measureElement 来减少重新渲染。
⚠️ 请注意，在使用 Virtualizer.measureElement 监视该项目时手动更改项目的大小将导致不可预测的行为，因为 Virtualizer.measureElement 也在更改大小。但是，你可以在同一虚拟器实例中但在不同的项目索引上使用 resizeItem 或 measureElement 中的一个。
scrollRect: Rect
scrollRect: Rect
滚动元素的当前 Rect。
shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean)
shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean)
当动态渲染的项目的大小与估计大小不同时，shouldAdjustScrollPositionOnItemSizeChange 方法可以对滚动位置的调整进行精细控制。当在列表的中间跳转并向后滚动时，新元素的大小可能与最初估计的大小不同。这种差异可能会导致后续项目发生偏移，从而可能中断用户的滚动体验，尤其是在向后浏览列表时。
isScrolling: boolean
isScrolling: boolean
布尔标志，指示列表当前是否正在滚动。
scrollDirection: 'forward' | 'backward' | null
scrollDirection: 'forward' | 'backward' | null
此选项指示滚动方向，可能的值为“forward”（向下滚动）和“backward”（向上滚动）。当没有活动滚动时，该值设置为 null。
scrollOffset: number
scrollOffset: number
此选项表示沿滚动轴的当前滚动位置。它以像素为单位，从可滚动区域的起点开始测量。