VirtualizedList

更便捷的 <FlatList> 和 <SectionList> 组件的基础实现，这两个组件的文档也更完善。一般来说，只有当你需要比 FlatList 提供的更灵活的灵活性时才应该使用这个，例如用于不可变数据而不是普通数组。

虚拟化通过维护一个有限的活动项渲染窗口，并用适当大小的空白空间替换渲染窗口外的所有项，从而极大地提高了大列表的内存消耗和性能。窗口适应滚动行为，如果项远离可见区域，则以低优先级（在任何运行的交互之后）增量渲染，否则以高优先级渲染，以最小化看到空白空间的可能性。

示例

TypeScript

JavaScript

---

一些注意事项：

• 当内容滚动出渲染窗口时，内部状态不会保留。确保所有数据都捕获在项数据或外部存储（如 Flux、Redux 或 Relay）中。
• 这是一个 PureComponent，这意味着如果 props 浅相等，它将不会重新渲染。确保你的 renderItem 函数依赖的所有内容都作为 prop 传递（例如 extraData），并且在更新后不是 ===，否则你的 UI 可能不会随变化更新。这包括 data prop 和父组件状态。
• 为了限制内存并实现平滑滚动，内容是在屏幕外异步渲染的。这意味着滚动速度可能快于填充率，并暂时看到空白内容。这是一个可以根据每个应用的需求进行调整的权衡，我们正在幕后改进它。
• 默认情况下，列表查找每个项上的 key prop 并将其用作 React key。或者，你可以提供自定义的 keyExtractor prop。

---

参考

属性

ScrollView 属性

继承 ScrollView 属性。

---

data

传递给 getItem 和 getItemCount 以检索项的不透明数据类型。

类型
any

---

必填

getItem

tsx

(data: any, index: number) => any;

用于从任何类型的数据块中提取项的通用访问器。

类型
function

---

必填

getItemCount

tsx

(data: any) => number;

确定数据块中有多少项。

类型
function

---

必填

renderItem

tsx

(info: any) => ?React.Element<any>

从 data 中获取一项并将其渲染到列表中

类型
function

---

CellRendererComponent

CellRendererComponent 允许自定义由 renderItem/ListItemComponent 渲染的单元格在放入底层 ScrollView 时如何包装。此组件必须接受事件处理程序，以通知 VirtualizedList 单元格内的变化。

类型
React.ComponentType<CellRendererProps>

---

ItemSeparatorComponent

渲染在每项之间，但不在顶部或底部。默认情况下，提供 highlighted 和 leadingItem prop。renderItem 提供 separators.highlight/unhighlight 将更新 highlighted prop，但你也可以使用 separators.updateProps 添加自定义 prop。可以是 React 组件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

类型
component, function, element

---

ListEmptyComponent

当列表为空时渲染。可以是 React 组件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

类型
component, element

---

ListItemComponent

每个数据项都使用此元素渲染。可以是 React 组件类，或渲染函数。

类型
component, function

---

ListFooterComponent

渲染在所有项的底部。可以是 React 组件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

类型
component, element

---

ListFooterComponentStyle

ListFooterComponent 内部 View 的样式。

类型	必填
ViewStyleProp	否

---

ListHeaderComponent

渲染在所有项的顶部。可以是 React 组件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

类型
component, element

---

ListHeaderComponentStyle

ListHeaderComponent 内部 View 的样式。

类型
View 样式

---

debug

debug 将开启额外的日志记录和视觉覆盖，以帮助调试使用情况和实现，但会显著影响性能。

类型
boolean

---

disableVirtualization

Deprecated

Virtualization provides significant performance and memory optimizations, but fully unmounts react instances that are outside of the render window. You should only need to disable this for debugging purposes.

类型
boolean

---

extraData

一个标记属性，用于告诉列表重新渲染（因为它实现了 PureComponent）。如果你的任何 renderItem、Header、Footer 等函数依赖于 data prop 之外的任何内容，将其放在这里并将其视为不可变的。

类型
any

---

getItemLayout

tsx

(
  data: any,
  index: number,
) => {length: number, offset: number, index: number}

类型
function

---

horizontal

如果为 true，则水平并排渲染项，而不是垂直堆叠。

类型
boolean

---

initialNumToRender

在初始批次中渲染多少项。这应该足以填充屏幕，但不要太多。注意，作为窗口化渲染的一部分，这些项永远不会被卸载，以提高滚动到顶部操作的感知性能。

类型	默认值
number	10

---

initialScrollIndex

不是从第一项的顶部开始，而是从 initialScrollIndex 开始。这会禁用“滚动到顶部”优化（该优化保持前 initialNumToRender 项始终渲染），并立即渲染从此初始索引开始的项。需要实现 getItemLayout。

类型
number

---

inverted

反转滚动方向。使用 -1 的缩放变换。

类型
boolean

---

keyExtractor

tsx

(item: any, index: number) => string;

用于提取给定索引处项的唯一 key。Key 用于缓存并作为 React key 跟踪项重新排序。默认提取器检查 item.key，然后 item.id，然后回退到使用索引，就像 React 所做的那样。

类型
function

---

maxToRenderPerBatch

每个增量渲染批次中渲染的最大项数。一次渲染的越多，填充率越好，但响应能力可能会受到影响，因为渲染内容可能会干扰响应按钮点击或其他交互。

类型
number

---

onEndReached

当滚动位置进入列表逻辑末端的 onEndReachedThreshold 范围内时调用一次。

类型
(info: {distanceFromEnd: number}) => void

---

onEndReachedThreshold

列表的尾端距离内容末端多远（以列表可见长度的单位）必须触发 onEndReached 回调。因此，值 0.5 将在内容末端位于列表可见长度的一半以内时触发 onEndReached。

类型	默认值
number	2

---

onRefresh

tsx

() => void;

如果提供，将添加标准的 RefreshControl 以实现“下拉刷新”功能。确保也正确设置 refreshing prop。

类型
function

---

onScrollToIndexFailed

tsx

(info: {
  index: number,
  highestMeasuredFrameIndex: number,
  averageItemLength: number,
}) => void;

用于处理滚动到尚未测量的索引时的失败。建议的操作是要么计算你自己的偏移量并 scrollTo 它，要么尽可能滚动，然后在渲染更多项后重试。

类型
function

---

onStartReached

当滚动位置进入列表逻辑起点的 onStartReachedThreshold 范围内时调用一次。

类型
(info: {distanceFromStart: number}) => void

---

onStartReachedThreshold

列表的前端距离内容起点多远（以列表可见长度的单位）必须触发 onStartReached 回调。因此，值 0.5 将在内容起点位于列表可见长度的一半以内时触发 onStartReached。

类型	默认值
number	2

---

onViewableItemsChanged

当行的可见性发生变化时调用，由 viewabilityConfig prop 定义。

类型
(callback: {changed: ViewToken[], viewableItems: ViewToken[]}) => void

---

persistentScrollbar

类型
bool

---

progressViewOffset

当需要偏移量以便加载指示器正确显示时设置此项。

类型
number

---

refreshControl

自定义刷新控制元素。设置时，它将覆盖内部构建的默认 <RefreshControl> 组件。onRefresh 和 refreshing prop 也会被忽略。仅适用于垂直 VirtualizedList。

类型
element

---

refreshing

等待刷新新数据时设置此项为 true。

类型
boolean

---

removeClippedSubviews

注意

在某些情况下使用此属性可能导致错误（内容丢失）- 使用风险自负。

当为 true 时，离屏子视图在离屏时从其原生备份父视图中移除。这可能会提高大列表的滚动性能。在 Android 上默认值为 true。

类型
boolean

---

renderScrollComponent

tsx

(props: object) => element;

渲染自定义滚动组件，例如具有不同样式的 RefreshControl。

类型
function

---

viewabilityConfig

有关流类型和进一步文档，请参阅 ViewabilityHelper.js。

类型
ViewabilityConfig

---

viewabilityConfigCallbackPairs

ViewabilityConfig/onViewableItemsChanged 对的列表。当特定的 ViewabilityConfig 条件满足时，将调用相应的 onViewableItemsChanged。有关流类型和进一步文档，请参阅 ViewabilityHelper.js。

类型
array of ViewabilityConfigCallbackPair

---

updateCellsBatchingPeriod

低优先级项渲染批次之间的时间量，例如用于渲染远离屏幕的项。与 maxToRenderPerBatch 类似的填充率/响应能力权衡。

类型
number

---

windowSize

确定可见区域外渲染的最大项数，以可见长度的单位表示。因此，如果你的列表填充了屏幕，那么 windowSize={21}（默认值）将渲染可见屏幕区域以及视口上方最多 10 个屏幕和下方 10 个屏幕。减少此数字将减少内存消耗并可能提高性能，但会增加快速滚动可能揭示未渲染内容的暂时空白区域的机会。

类型
number

Methods

flashScrollIndicators()

tsx

flashScrollIndicators();

---

getScrollableNode()

tsx

getScrollableNode(): any;

---

getScrollRef()

tsx

getScrollRef():
  | React.ElementRef<typeof ScrollView>
  | React.ElementRef<typeof View>
  | null;

---

getScrollResponder()

tsx

getScrollResponder () => ScrollResponderMixin | null;

Provides a handle to the underlying scroll responder. Note that this._scrollRef might not be a ScrollView, so we need to check that it responds to getScrollResponder before calling it.

---

scrollToEnd()

tsx

scrollToEnd(params?: {animated?: boolean});

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

Name	Type
params	object

Valid params keys are:

• 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

---

scrollToIndex()

tsx

scrollToIndex(params: {
  index: number;
  animated?: boolean;
  viewOffset?: number;
  viewPosition?: number;
});

Valid params include:

• 'index' (number). Required.
• 'animated' (boolean). Optional.
• 'viewOffset' (number). Optional.
• 'viewPosition' (number). Optional.

---

scrollToItem()

tsx

scrollToItem(params: {
  item: ItemT;
  animated?: boolean;
  viewOffset?: number;
  viewPosition?: number;
);

Valid params include:

• 'item' (Item). Required.
• 'animated' (boolean). Optional.
• 'viewOffset' (number). Optional.
• 'viewPosition' (number). Optional.

---

scrollToOffset()

tsx

scrollToOffset(params: {
  offset: number;
  animated?: boolean;
});

Scrolls to a specific content pixel offset in the list.

The offset parameter specifies the offset to scroll to. In case of horizontal=true, the offset is the x-value, in any other case the offset is the y-value.

The animated parameter (defaults to true) defines whether the list does animation while scrolling.