VirtualizedList
它是更方便的 <FlatList>
和 <SectionList>
组件的基础实现,这些组件的文档也更完善。通常,你只在需要比 FlatList
提供更多灵活性时才应使用它,例如与不可变数据而非普通数组一起使用。
虚拟化通过维护一个有限的活动项目渲染窗口,并将渲染窗口之外的所有项目替换为适当大小的空白空间,从而大幅改善了大型列表的内存消耗和性能。该窗口会根据滚动行为进行调整,如果项目离可见区域较远,则以低优先级(在任何正在进行的交互之后)增量渲染;否则以高优先级渲染,以最大程度减少出现空白区域的可能性。
示例
- TypeScript
- JavaScript
注意事项
- 当内容滚动出渲染窗口时,内部状态不会保留。请确保所有数据都已捕获到项目数据或外部存储(如 Flux、Redux 或 Relay)中。
- 这是一个
PureComponent
,这意味着如果props
浅相等,它将不会重新渲染。请确保您的renderItem
函数所依赖的所有内容都作为 prop (例如extraData
) 传递,并且更新后该 prop 不等于===
,否则您的 UI 可能不会随着更改而更新。这包括data
prop 和父组件状态。 - 为了限制内存并实现平滑滚动,内容会在屏幕外异步渲染。这意味着滚动速度可能快于填充速度,并短暂看到空白内容。这是一种权衡,可以根据每个应用程序的需求进行调整,我们正在幕后努力改进它。
- 默认情况下,列表会在每个项目上寻找
key
prop,并将其用作 React 键。或者,您可以提供自定义的keyExtractor
prop。
参考
属性
ScrollView 属性
继承 ScrollView 属性。
data
传递给 getItem
和 getItemCount
用于检索项目的不透明数据类型。
类型 |
---|
any |
必需 getItem
(data: any, index: number) => any;
一个用于从任何类型的数据块中提取项目的通用访问器。
类型 |
---|
函数 |
必需 getItemCount
(data: any) => number;
确定数据块中有多少个项目。
类型 |
---|
函数 |
必需 renderItem
(info: any) => ?React.Element<any>
从 data
中获取一个项目并将其渲染到列表中
类型 |
---|
函数 |
CellRendererComponent
CellRendererComponent 允许自定义 renderItem
/ListItemComponent
渲染的单元格在放入底层 ScrollView 时如何被包裹。此组件必须接受事件处理程序,以通知 VirtualizedList 单元格内的更改。
类型 |
---|
React.ComponentType<CellRendererProps> |
ItemSeparatorComponent
在每个项目之间渲染,但不在顶部或底部。默认情况下,提供 highlighted
和 leadingItem
属性。renderItem
提供 separators.highlight
/unhighlight
以更新 highlighted
属性,但您也可以使用 separators.updateProps
添加自定义属性。可以是 React 组件(例如 SomeComponent
),也可以是 React 元素(例如 <SomeComponent />
)。
类型 |
---|
组件,函数,元素 |
ListEmptyComponent
当列表为空时渲染。可以是 React 组件(例如 SomeComponent
),也可以是 React 元素(例如 <SomeComponent />
)。
类型 |
---|
组件,元素 |
ListItemComponent
每个数据项都使用此元素渲染。可以是 React 组件类,也可以是渲染函数。
类型 |
---|
组件,函数 |
ListFooterComponent
在所有项目的底部渲染。可以是 React 组件(例如 SomeComponent
),也可以是 React 元素(例如 <SomeComponent />
)。
类型 |
---|
组件,元素 |
ListFooterComponentStyle
ListFooterComponent
内部 View 的样式。
类型 | 必需 |
---|---|
ViewStyleProp | 否 |
ListHeaderComponent
在所有项目的顶部渲染。可以是 React 组件(例如 SomeComponent
),也可以是 React 元素(例如 <SomeComponent />
)。
类型 |
---|
组件,元素 |
ListHeaderComponentStyle
ListHeaderComponent
内部 View 的样式。
类型 |
---|
View 样式 |
debug
debug
将开启额外的日志记录和视觉覆盖,以帮助调试使用和实现,但这会显著影响性能。
类型 |
---|
布尔值 |
disableVirtualization
已废弃。 虚拟化提供了显著的性能和内存优化,但会完全卸载渲染窗口之外的 React 实例。你只应在调试目的时才禁用此功能。
类型 |
---|
布尔值 |
extraData
一个标记属性,用于告知列表重新渲染(因为它实现了 PureComponent
)。如果你的任何 renderItem
、Header、Footer 等函数依赖于 data
属性之外的任何内容,请将其放在此处并将其视为不可变。
类型 |
---|
any |
getItemLayout
(
data: any,
index: number,
) => {length: number, offset: number, index: number}
类型 |
---|
函数 |
horizontal
如果为 true
,则水平渲染项目,而不是垂直堆叠。
类型 |
---|
布尔值 |
initialNumToRender
初始批次中要渲染的项目数量。这应该足以填充屏幕,但不要太多。请注意,这些项目永远不会作为窗口化渲染的一部分被卸载,以提高滚动到顶部操作的感知性能。
类型 | 默认 |
---|---|
数字 | 10 |
initialScrollIndex
不从顶部第一个项目开始,而是从 initialScrollIndex
开始。这会禁用“滚动到顶部”优化,该优化会使前 initialNumToRender
个项目始终渲染,并立即渲染从该初始索引开始的项目。需要实现 getItemLayout
。
类型 |
---|
数字 |
inverted
反转滚动方向。使用 -1
的缩放变换。
类型 |
---|
布尔值 |
keyExtractor
(item: any, index: number) => string;
用于为指定索引处的给定项目提取唯一键。键用于缓存和作为 React 键来跟踪项目重新排序。默认提取器会检查 item.key
,然后是 item.id
,最后回退到使用索引,就像 React 那样。
类型 |
---|
函数 |
maxToRenderPerBatch
每个增量渲染批次中要渲染的最大项目数。一次渲染越多,填充率越好,但响应性可能会受到影响,因为渲染内容可能会干扰响应按钮点击或其他交互。
类型 |
---|
数字 |
onEndReached
当滚动位置距离列表逻辑末端在 onEndReachedThreshold
之内时,此方法会被调用一次。
类型 |
---|
(info: {distanceFromEnd: number}) => void |
onEndReachedThreshold
列表的尾部边缘距离内容末端的距离(以列表可见长度为单位),当该距离在此值之内时,会触发 onEndReached
回调。因此,值为 0.5 将在内容末端距离列表可见长度的一半之内时触发 onEndReached
。
类型 | 默认 |
---|---|
数字 | 2 |
onRefresh
() => void;
如果提供,将添加一个标准的 RefreshControl
以实现“下拉刷新”功能。请确保也正确设置 refreshing
属性。
类型 |
---|
函数 |
onScrollToIndexFailed
(info: {
index: number,
highestMeasuredFrameIndex: number,
averageItemLength: number,
}) => void;
用于处理滚动到尚未测量索引失败的情况。建议的操作是计算自己的偏移量并 scrollTo
,或者尽可能滚动,然后在渲染更多项目后重试。
类型 |
---|
函数 |
onStartReached
当滚动位置距离列表逻辑起始端在 onStartReachedThreshold
之内时,此方法会被调用一次。
类型 |
---|
(info: {distanceFromStart: number}) => void |
onStartReachedThreshold
列表的前沿边缘距离内容起始端的距离(以列表可见长度为单位),当该距离在此值之内时,会触发 onStartReached
回调。因此,值为 0.5 将在内容起始端距离列表可见长度的一半之内时触发 onStartReached
。
类型 | 默认 |
---|---|
数字 | 2 |
onViewableItemsChanged
当行的可见性根据 viewabilityConfig
属性的定义发生变化时调用。
类型 |
---|
(callback: {changed: ViewToken[], viewableItems: ViewToken[]}) => void |
persistentScrollbar
类型 |
---|
布尔值 |
progressViewOffset
当需要偏移量以正确显示加载指示器时,设置此属性。
类型 |
---|
数字 |
refreshControl
一个自定义的刷新控制元素。设置后,它将覆盖内部构建的默认 <RefreshControl>
组件。onRefresh
和 refreshing
属性也将被忽略。仅适用于垂直 VirtualizedList。
类型 |
---|
元素 |
refreshing
等待刷新获取新数据时,将其设置为 true。
类型 |
---|
布尔值 |
removeClippedSubviews
这可能会改善大型列表的滚动性能。
注意:在某些情况下可能存在 Bug(内容缺失)——请自行承担风险使用。
类型 |
---|
布尔值 |
renderScrollComponent
(props: object) => element;
渲染自定义滚动组件,例如带有不同样式的 RefreshControl
。
类型 |
---|
函数 |
viewabilityConfig
有关流类型和更多文档,请参阅 ViewabilityHelper.js
。
类型 |
---|
ViewabilityConfig |
viewabilityConfigCallbackPairs
ViewabilityConfig
/onViewableItemsChanged
对的列表。当满足对应的 ViewabilityConfig
条件时,会调用特定的 onViewableItemsChanged
。有关流类型和更多文档,请参阅 ViewabilityHelper.js
。
类型 |
---|
ViewabilityConfigCallbackPair 数组 |
updateCellsBatchingPeriod
低优先级项目渲染批次之间的时间量,例如用于渲染屏幕外较远的项目。与 maxToRenderPerBatch
具有相似的填充率/响应性权衡。
类型 |
---|
数字 |
windowSize
确定在可见区域之外渲染的最大项目数,以可见长度为单位。因此,如果您的列表填满了屏幕,则 windowSize={21}
(默认值)将渲染可见屏幕区域以及视口上方和下方的最多 10 个屏幕。减少此数字将减少内存消耗并可能提高性能,但会增加快速滚动时可能会显示未渲染内容的瞬时空白区域的可能性。
类型 |
---|
数字 |
方法
flashScrollIndicators()
flashScrollIndicators();
getScrollableNode()
getScrollableNode(): any;
getScrollRef()
getScrollRef():
| React.ElementRef<typeof ScrollView>
| React.ElementRef<typeof View>
| null;
getScrollResponder()
getScrollResponder () => ScrollResponderMixin | null;
提供底层滚动响应器的句柄。请注意,this._scrollRef
可能不是 ScrollView
,因此在调用 getScrollResponder
之前,我们需要检查它是否响应此方法。
scrollToEnd()
scrollToEnd(params?: {animated?: boolean});
滚动到内容末尾。如果没有 getItemLayout
属性,可能会卡顿。
参数
名称 | 类型 |
---|---|
params | 对象 |
有效的 params
键有
'animated'
(布尔值) - 列表滚动时是否应执行动画。默认为true
。
scrollToIndex()
scrollToIndex(params: {
index: number;
animated?: boolean;
viewOffset?: number;
viewPosition?: number;
});
有效的 params
包含
- 'index' (数字)。必需。
- 'animated' (布尔值)。可选。
- 'viewOffset' (数字)。可选。
- 'viewPosition' (数字)。可选。
scrollToItem()
scrollToItem(params: {
item: ItemT;
animated?: boolean;
viewOffset?: number;
viewPosition?: number;
);
有效的 params
包含
- 'item' (项目)。必需。
- 'animated' (布尔值)。可选。
- 'viewOffset' (数字)。可选。
- 'viewPosition' (数字)。可选。
scrollToOffset()
scrollToOffset(params: {
offset: number;
animated?: boolean;
});
滚动到列表中特定的内容像素偏移量。
参数 offset
期望滚动到的偏移量。如果 horizontal
为 true,则偏移量是 x 值;在任何其他情况下,偏移量是 y 值。
参数 animated
(默认为 true
)定义了列表滚动时是否应执行动画。