跳至主内容

虚拟列表

非官方测试版翻译

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

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

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

示例​

id: touchablenativefeedback title: 触摸原生反馈​

注意事项：

  • 当内容滚动出渲染窗口时，内部状态不会被保留。请确保所有数据都存储在项数据或外部状态库（如 Flux/Redux/Relay）中

  • 这是 PureComponent 组件，意味着当 props 进行浅层比较相等时不会重新渲染。请确保 renderItem 函数依赖的所有数据都通过 props 传入（例如 extraData），且更新后不能保持 === 全等，否则界面可能无法响应变更。这包括 data 属性和父组件状态

  • 为控制内存占用并确保滚动流畅，列表内容会在屏幕外异步渲染。这意味着用户可能快速滚动时暂时看到空白区域，这是为平衡性能所做的设计取舍。我们正在持续优化该体验。

  • 默认情况下，列表会查找每个项目的 key 属性作为 React key。您也可以通过 keyExtractor 属性提供自定义键

id: touchablenativefeedback title: 触摸原生反馈​

参考

属性​

ScrollView 属性​

继承 ScrollView 的所有属性

id: touchablenativefeedback title: 触摸原生反馈​

data​

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

Type
any

id: touchablenativefeedback title: 触摸原生反馈​

Required
getItem​

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

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

Type
function

id: touchablenativefeedback title: 触摸原生反馈​

Required
getItemCount​

tsx
(data: any) => number;

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

Type
function

id: touchablenativefeedback title: 触摸原生反馈​

Required
renderItem​

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

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

Type
function

id: touchablenativefeedback title: 触摸原生反馈​

CellRendererComponent​

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

Type
React.ComponentType<CellRendererProps>

id: touchablenativefeedback title: 触摸原生反馈​

ItemSeparatorComponent​

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

Type
component, function, element

id: touchablenativefeedback title: 触摸原生反馈​

ListEmptyComponent​

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

Type
component, element

id: touchablenativefeedback title: 触摸原生反馈​

ListItemComponent​

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

Type
component, function

id: touchablenativefeedback title: 触摸原生反馈​

ListFooterComponent​

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

Type
component, element

id: touchablenativefeedback title: 触摸原生反馈​

ListFooterComponentStyle​

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

TypeRequired
ViewStylePropNo

id: touchablenativefeedback title: 触摸原生反馈​

ListHeaderComponent​

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

Type
component, element

id: touchablenativefeedback title: 触摸原生反馈​

ListHeaderComponentStyle​

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

Type
View Style

id: touchablenativefeedback title: 触摸原生反馈​

debug​

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

Type
boolean

id: touchablenativefeedback title: 触摸原生反馈​

🗑️ disableVirtualization（已弃用）​

已弃用

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

Type
boolean

id: touchablenativefeedback title: 触摸原生反馈​

extraData​

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

Type
any

id: touchablenativefeedback title: 触摸原生反馈​

getItemLayout​

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

id: touchablenativefeedback title: 触摸原生反馈​

horizontal​

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

Type
boolean

id: touchablenativefeedback title: 触摸原生反馈​

initialNumToRender​

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

TypeDefault
number10

id: touchablenativefeedback title: 触摸原生反馈​

initialScrollIndex​

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

Type
number

id: touchablenativefeedback title: 触摸原生反馈​

inverted​

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

Type
boolean

id: touchablenativefeedback title: 触摸原生反馈​

keyExtractor​

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

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

Type
function

id: touchablenativefeedback title: 触摸原生反馈​

maxToRenderPerBatch​

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

Type
number

id: touchablenativefeedback title: 触摸原生反馈​

onEndReached​

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

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

id: touchablenativefeedback title: 触摸原生反馈​

onEndReachedThreshold​

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

TypeDefault
number2

id: touchablenativefeedback title: 触摸原生反馈​

onRefresh​

tsx
() => void;

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

Type
function

id: touchablenativefeedback title: 触摸原生反馈​

onScrollToIndexFailed​

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

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

Type
function

id: touchablenativefeedback title: 触摸原生反馈​

onStartReached​

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

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

id: touchablenativefeedback title: 触摸原生反馈​

onStartReachedThreshold​

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

TypeDefault
number2

id: touchablenativefeedback title: 触摸原生反馈​

onViewableItemsChanged​

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

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

id: touchablenativefeedback title: 触摸原生反馈​

persistentScrollbar​

Type
bool

id: touchablenativefeedback title: 触摸原生反馈​

progressViewOffset​

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

Type
number

id: touchablenativefeedback title: 触摸原生反馈​

refreshControl​

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

Type
element

id: touchablenativefeedback title: 触摸原生反馈​

refreshing​

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

Type
boolean

id: touchablenativefeedback title: 触摸原生反馈​

removeClippedSubviews​

警告

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

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

Type
boolean

id: touchablenativefeedback title: 触摸原生反馈​

renderScrollComponent​

tsx
(props: object) => element;

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

Type
function

id: touchablenativefeedback title: 触摸原生反馈​

viewabilityConfig​

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

Type
ViewabilityConfig

id: touchablenativefeedback title: 触摸原生反馈​

viewabilityConfigCallbackPairs​

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

Type
array of ViewabilityConfigCallbackPair

id: touchablenativefeedback title: 触摸原生反馈​

updateCellsBatchingPeriod​

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

Type
number

id: touchablenativefeedback title: 触摸原生反馈​

windowSize​

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

Type
number

方法​

flashScrollIndicators()​

tsx
flashScrollIndicators();

id: touchablenativefeedback title: 触摸原生反馈​

getScrollableNode()​

tsx
getScrollableNode(): any;

id: touchablenativefeedback title: 触摸原生反馈​

getScrollRef()​

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

id: touchablenativefeedback title: 触摸原生反馈​

getScrollResponder()​

tsx
getScrollResponder () => ScrollResponderMixin | null;

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

id: touchablenativefeedback title: 触摸原生反馈​

scrollToEnd()​

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

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

参数:

NameType
paramsobject

有效的 params 键如下：

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

id: touchablenativefeedback title: 触摸原生反馈​

scrollToIndex()​

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

有效的 params 包含：

  • 'index' (number)。必需

  • 'animated' (boolean)。可选

  • 'viewOffset' (number)。可选

  • 'viewPosition' (number)。可选

id: touchablenativefeedback title: 触摸原生反馈​

scrollToItem()​

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

有效的 params 包含：

  • 'item' (Item)。必需

  • 'animated' (boolean)。可选

  • 'viewOffset' (number)。可选

  • 'viewPosition' (number)。可选

id: touchablenativefeedback title: 触摸原生反馈​

scrollToOffset()​

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

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

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

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