版本：0.82

虚拟列表

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

这是更便捷的 <FlatList> 和 <SectionList> 组件的基础实现（这两个组件的文档也更完善）。通常仅在需要比 FlatList 更高灵活性的场景中使用，例如处理不可变数据而非普通数组时。

虚拟化技术通过维护有限的可见项渲染窗口，并将窗口外的项替换为适当大小的空白区域，显著提升大型列表的内存效率和渲染性能。该窗口会根据滚动行为动态调整，远离可视区域的项采用低优先级增量渲染（在所有交互完成后执行），近端项则采用高优先级渲染以最大限度减少空白区域出现的可能性。

示例

TypeScript
JavaScript

注意事项：

当内容滚动出渲染窗口时，内部状态不会被保留。请确保所有数据都存储在项数据或外部状态库（如 Flux/Redux/Relay）中
这是 PureComponent 组件，意味着当 props 进行浅层比较相等时不会重新渲染。请确保 renderItem 函数依赖的所有数据都通过 props 传入（例如 extraData），且更新后不能保持 === 全等，否则界面可能无法响应变更。这包括 data 属性和父组件状态
为控制内存占用并确保滚动流畅，列表内容会在屏幕外异步渲染。这意味着用户可能快速滚动时暂时看到空白区域，这是为平衡性能所做的设计取舍。我们正在持续优化该体验。
默认情况下，列表会查找每个项目的 key 属性作为 React key。您也可以通过 keyExtractor 属性提供自定义键

参考

属性

ScrollView 属性

继承 ScrollView 的所有属性

`data`

传递给 getItem 和 getItemCount 的不透明数据类型，用于获取列表项

Type
any

Required
`getItem`

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

通用访问器，用于从任意数据块中提取列表项

Type
function

Required
`getItemCount`

tsx
(data: any) => number;

确定数据块中包含的列表项数量

Type
function

Required
`renderItem`

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

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

Type
function

`CellRendererComponent`

该组件可自定义通过 renderItem/ListItemComponent 渲染的单元格在底层 ScrollView 中的包装方式。该组件必须接受事件处理器以向 VirtualizedList 通知单元格内的变更

Type
`React.ComponentType<CellRendererProps>`

`ItemSeparatorComponent`

渲染在列表项之间（不包括顶部和底部）。默认提供 highlighted 和 leadingItem 属性。renderItem 提供 separators.highlight/unhighlight 来更新 highlighted 属性，也可通过 separators.updateProps 添加自定义属性。可以是 React 组件（如 SomeComponent）或 React 元素（如 <SomeComponent />）

Type
component, function, element

`ListEmptyComponent`

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

Type
component, element

`ListItemComponent`

每个数据项都通过此元素渲染。可以是 React 类组件，也可以是渲染函数。

Type
component, function

`ListFooterComponent`

在所有列表项底部渲染。可以是 React 类组件（如 SomeComponent），也可以是 React 元素（如 <SomeComponent />）。

Type
component, element

`ListFooterComponentStyle`

用于 ListFooterComponent 内部 View 组件的样式。

Type	Required
ViewStyleProp	No

`ListHeaderComponent`

在所有列表项顶部渲染。可以是 React 类组件（如 SomeComponent），也可以是 React 元素（如 <SomeComponent />）。

Type
component, element

`ListHeaderComponentStyle`

用于 ListHeaderComponent 内部 View 组件的样式。

Type
View Style

`debug`

开启 debug 模式将启用额外日志和可视化覆盖层辅助调试（包括使用和实现），但会显著影响性能。

Type
boolean

`disableVirtualization`

已弃用

虚拟化技术可显著提升性能和内存效率，但会完全卸载渲染窗口之外的 React 实例。仅在调试时才需禁用此功能。

Type
boolean

`extraData`

用于通知列表重新渲染的标记属性（因列表继承自 PureComponent）。若 renderItem、Header、Footer 等函数依赖 data 属性之外的任何数据，请将其置于此处并视为不可变数据。

Type
any

`getItemLayout`

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

Type
function

`horizontal`

若为 true，则水平排列项目而非垂直堆叠。

Type
boolean

`initialNumToRender`

初始批次渲染的项目数量。应足以填满屏幕但不宜过多。注意：为提升滚动至顶部的感知性能，这些初始项目永远不会因窗口化渲染而被卸载。

Type	Default
number	`10`

`initialScrollIndex`

不从首项开始渲染，而是从 initialScrollIndex 指定位置开始。此设置会禁用"滚动至顶部"优化（该优化会永久渲染前 initialNumToRender 个项目），并立即渲染从该初始索引开始的项。需要实现 getItemLayout。

Type
number

`inverted`

反转滚动方向（通过 -1 的缩放变换实现）。

Type
boolean

`keyExtractor`

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

用于为指定索引处的项目生成唯一键。该键用于缓存及作为 React key 跟踪项目重排序。默认提取器依次检查 item.key、item.id，最后回退使用索引（与 React 行为一致）。

Type
function

`maxToRenderPerBatch`

每批次增量渲染的最大项目数。单次渲染越多填充率越高，但响应性可能下降（因渲染内容可能干扰按钮点击等交互响应）。

Type
number

`onEndReached`

当滚动位置距离列表逻辑末尾 onEndReachedThreshold 范围内时触发一次。

Type
`(info: {distanceFromEnd: number}) => void`

`onEndReachedThreshold`

当列表尾部边缘距离内容末尾的距离（以列表可见区域长度为单位）达到此阈值时，将触发 onEndReached 回调。例如，值为 0.5 表示当内容末尾处于列表可见区域一半长度范围内时触发 onEndReached。

Type	Default
number	`2`

`onRefresh`

tsx
() => void;

若提供此回调，将添加标准的 RefreshControl 组件实现"下拉刷新"功能。请确保同时正确设置 refreshing 属性。

Type
function

`onScrollToIndexFailed`

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

用于处理滚动到尚未测量的索引位置时发生的失败。推荐操作是自行计算偏移量并调用 scrollTo 方法，或先滚动到最远位置，待更多项目渲染后重试。

Type
function

`onStartReached`

当滚动位置进入距离列表逻辑起点 onStartReachedThreshold 阈值范围内时触发一次。

Type
`(info: {distanceFromStart: number}) => void`

`onStartReachedThreshold`

当列表头部边缘距离内容起点的距离（以列表可见区域长度为单位）达到此阈值时，将触发 onStartReached 回调。例如，值为 0.5 表示当内容起点处于列表可见区域一半长度范围内时触发 onStartReached。

Type	Default
number	`2`

`onViewableItemsChanged`

当行项目的可见性发生变化时触发（可见性规则由 viewabilityConfig 属性定义）。

Type
`(callback: {changed: ViewToken[], viewableItems: ViewToken[]}) => void`

`persistentScrollbar`

Type
bool

`progressViewOffset`

当加载指示器需要偏移量才能正确显示时设置此属性。

Type
number

`refreshControl`

自定义刷新控制组件。设置后将覆盖内置的默认 <RefreshControl> 组件，此时 onRefresh 和 refreshing 属性将被忽略。仅适用于垂直方向的 VirtualizedList。

Type
element

`refreshing`

在等待刷新数据时将此属性设为 true。

Type
boolean

`removeClippedSubviews`

警告

使用此属性在某些情况下可能导致错误（内容缺失）——请自行承担使用风险。

当设为 true 时，离屏子视图会从其原生父视图中卸载。对于大型列表，此操作可改善滚动性能。在 Android 平台上默认值为 true。

Type
boolean

`renderScrollComponent`

tsx
(props: object) => element;

渲染自定义滚动组件（例如包含定制样式的 RefreshControl）。

Type
function

`viewabilityConfig`

详见 ViewabilityHelper.js 中的 flow 类型定义和文档说明。

Type
ViewabilityConfig

`viewabilityConfigCallbackPairs`

由 ViewabilityConfig 和 onViewableItemsChanged 组成的配置对数组。当满足特定 ViewabilityConfig 的条件时，其对应的 onViewableItemsChanged 回调将被触发。详见 ViewabilityHelper.js 中的 flow 类型定义和文档说明。

Type
array of ViewabilityConfigCallbackPair

`updateCellsBatchingPeriod`

低优先级项目渲染批次之间的时间间隔（例如渲染屏幕外较远的项目）。与 maxToRenderPerBatch 类似，用于平衡填充速率和响应性能。

Type
number

`windowSize`

决定在可见区域之外渲染的最大项目数量，以可见区域长度为单位。如果列表占满整个屏幕，默认的 windowSize={21} 会渲染可见屏幕区域加上视口上方最多10屏和下方最多10屏的内容。减小该值会降低内存消耗并可能提升性能，但会增加快速滚动时短暂出现未渲染内容空白区域的可能性。

Type
number

方法

`flashScrollIndicators()`

tsx
flashScrollIndicators();

`getScrollableNode()`

tsx
getScrollableNode(): any;

`getScrollRef()`

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

`getScrollResponder()`

tsx
getScrollResponder () => ScrollResponderMixin | null;

提供底层滚动响应器（scroll responder）的句柄。请注意 this._scrollRef 可能不是 ScrollView，因此在调用前需确认其是否响应 getScrollResponder 方法。

`scrollToEnd()`

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

滚动至内容末尾。未提供 getItemLayout 属性时可能出现卡顿。

参数:

Name	Type
params	object

有效的 params 键如下：

'animated' (boolean) - 列表滚动时是否执行动画。默认为 true。

`scrollToIndex()`

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

有效的 params 包含：

'index' (number)。必需
'animated' (boolean)。可选
'viewOffset' (number)。可选
'viewPosition' (number)。可选

`scrollToItem()`

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

有效的 params 包含：

'item' (Item)。必需
'animated' (boolean)。可选
'viewOffset' (number)。可选
'viewPosition' (number)。可选

`scrollToOffset()`

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

滚动到列表内指定的内容像素偏移位置

参数 offset 表示目标滚动偏移量：当 horizontal 为 true 时表示 x 值，其他情况表示 y 值

参数 animated（默认为 true）定义列表滚动时是否执行动画

示例​

参考

属性​

ScrollView 属性​

data​

Required getItem​

Required getItemCount​

Required renderItem​

CellRendererComponent​

ItemSeparatorComponent​

ListEmptyComponent​

ListItemComponent​

ListFooterComponent​

ListFooterComponentStyle​

ListHeaderComponent​

ListHeaderComponentStyle​

debug​

disableVirtualization​

extraData​

getItemLayout​

horizontal​

initialNumToRender​

initialScrollIndex​

inverted​

keyExtractor​

maxToRenderPerBatch​

onEndReached​

onEndReachedThreshold​

onRefresh​

onScrollToIndexFailed​

onStartReached​

onStartReachedThreshold​

onViewableItemsChanged​

persistentScrollbar​

progressViewOffset​

refreshControl​

refreshing​

removeClippedSubviews​

renderScrollComponent​

viewabilityConfig​

viewabilityConfigCallbackPairs​

updateCellsBatchingPeriod​

windowSize​

方法​

flashScrollIndicators()​

getScrollableNode()​

getScrollRef()​

getScrollResponder()​

scrollToEnd()​

scrollToIndex()​

scrollToItem()​

scrollToOffset()​

示例

属性