Skip to main content

VirtualizedList

更方便的 <FlatList> 和 <SectionList> 组件的基本实现，这些组件也有更好的文档记录。一般来说，只有当你需要比 FlatList 提供的更多灵活性时才应该真正使用它，例如 用于不可变数据而不是普通数组。

¥Base implementation for the more convenient <FlatList> and <SectionList> components, which are also better documented. In general, this should only really be used if you need more flexibility than FlatList provides, e.g. for use with immutable data instead of plain arrays.

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

¥Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. The window adapts to scrolling behavior, and items are rendered incrementally with low-pri (after any running interactions) if they are far from the visible area, or with hi-pri otherwise to minimize the potential of seeing blank space.

示例​

¥Example

一些注意事项：

¥Some caveats:

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

    ¥Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.

  • 这是 PureComponent，这意味着如果 props 浅相等，它将不会重新渲染。确保 renderItem 函数所依赖的所有内容都作为 prop（例如 extraData）传递，而更新后不是 ===，否则你的 UI 可能不会因更改而更新。这包括 data 属性和父组件状态。

    ¥This is a PureComponent which means that it will not re-render if props are shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.

  • 为了限制内存并实现平滑滚动，内容在屏幕外异步渲染。这意味着滚动速度可能快于填充速度，并暂时看到空白内容。这是一个可以调整以适应每个应用的需求的权衡，我们正在幕后努力改进它。

    ¥In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.

  • 默认情况下，列表会在每个项目上查找 key 属性并将其用作 React 键。或者，你可以提供自定义 keyExtractor 属性。

    ¥By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

参考

¥Reference

属性​

¥Props

ScrollView 属性​

¥ScrollView Props

继承 ScrollView 属性。

¥Inherits ScrollView Props.

data​

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

¥Opaque data type passed to getItem and getItemCount to retrieve items.

类型
any

​

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

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

¥A generic accessor for extracting an item from any sort of data blob.

类型
function

​

(data: any) => number;

确定数据 blob 中有多少项。

¥Determines how many items are in the data blob.

类型
function

​

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

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

¥Takes an item from data and renders it into the list

类型
function

CellRendererComponent​

CellRendererComponent 允许自定义将 renderItem/ListItemComponent 渲染的单元格放入底层 ScrollView 时如何封装。该组件必须接受事件处理程序，通知 VirtualizedList 单元内的更改。

¥CellRendererComponent allows customizing how cells rendered by renderItem/ListItemComponent are wrapped when placed into the underlying ScrollView. This component must accept event handlers which notify VirtualizedList of changes within the cell.

类型
React.ComponentType<CellRendererProps>

ItemSeparatorComponent​

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

¥Rendered in between each item, but not at the top or bottom. By default, highlighted and leadingItem props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、函数、元素

ListEmptyComponent​

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

¥Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、元素

ListItemComponent​

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

¥Each data item is rendered using this element. Can be a React Component Class, or a render function.

类型
组件、函数

ListFooterComponent​

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

¥Rendered at the bottom of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、元素

ListFooterComponentStyle​

ListFooterComponent 内部视图的样式。

¥Styling for internal View for ListFooterComponent.

类型必需的
ViewStyleProp不

ListHeaderComponent​

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

¥Rendered at the top of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、元素

ListHeaderComponentStyle​

ListHeaderComponent 内部视图的样式。

¥Styling for internal View for ListHeaderComponent.

类型
View 样式

debug​

debug 将打开额外的日志记录和可视化覆盖来帮助调试使用和实现，但性能会受到显着影响。

¥debug will turn on extra logging and visual overlays to aid with debugging both usage and implementation, but with a significant perf hit.

类型
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、页眉、页脚等功能依赖于 data 属性之外的任何内容，请将其粘贴在这里并以不变的方式对待它。

¥A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

类型
any

getItemLayout​

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

horizontal​

如果为 true，则水平渲染彼此相邻的项目，而不是垂直堆叠。

¥If true, renders items next to each other horizontally instead of stacked vertically.

类型
boolean

initialNumToRender​

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

¥How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

类型默认
number10

initialScrollIndex​

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

¥Instead of starting at the top with the first item, start at initialScrollIndex. This disables the "scroll to top" optimization that keeps the first initialNumToRender items always rendered and immediately renders the items starting at this initial index. Requires getItemLayout to be implemented.

类型
number

inverted​

反转滚动方向。使用 -1 的比例变换。

¥Reverses the direction of scroll. Uses scale transforms of -1.

类型
boolean

keyExtractor​

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

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

¥Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then item.id, and then falls back to using the index, like React does.

类型
function

maxToRenderPerBatch​

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

¥The maximum number of items to render in each incremental render batch. The more rendered at once, the better the fill rate, but responsiveness may suffer because rendering content may interfere with responding to button taps or other interactions.

类型
number

onEndReached​

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

¥Called once when the scroll position gets within onEndReachedThreshold from the logical end of the list.

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

onEndReachedThreshold​

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

¥How far from the end (in units of visible length of the list) the trailing edge of the list must be from the end of the content to trigger the onEndReached callback. Thus, a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

类型默认
number2

onRefresh​

() => void;

如果提供，将为 "拉动刷新" 功能添加标准 RefreshControl。确保正确设置 refreshing 属性。

¥If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly.

类型
function

onScrollToIndexFailed​

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

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

¥Used to handle failures when scrolling to an index that has not been measured yet. Recommended action is to either compute your own offset and scrollTo it, or scroll as far as possible and then try again after more items have been rendered.

类型
function

onStartReached​

当滚动位置距离列表逻辑开始 onStartReachedThreshold 以内时调用一次。

¥Called once when the scroll position gets within onStartReachedThreshold from the logical start of the list.

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

onStartReachedThreshold​

列表的前沿必须距内容的开头有多远（以列表的可见长度为单位）才能触发 onStartReached 回调。因此，当内容的开头在列表可见长度的一半以内时，值 0.5 将触发 onStartReached。

¥How far from the start (in units of visible length of the list) the leading edge of the list must be from the start of the content to trigger the onStartReached callback. Thus, a value of 0.5 will trigger onStartReached when the start of the content is within half the visible length of the list.

类型默认
number2

onViewableItemsChanged​

当行的可见性发生变化时调用，如 viewabilityConfig 属性所定义。

¥Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

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

persistentScrollbar​

类型
bool

progressViewOffset​

当加载指示器需要偏移才能正确显示时，请设置此项。

¥Set this when offset is needed for the loading indicator to show correctly.

类型
number

refreshControl​

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

¥A custom refresh control element. When set, it overrides the default <RefreshControl> component built internally. The onRefresh and refreshing props are also ignored. Only works for vertical VirtualizedList.

类型
element

refreshing​

在等待刷新的新数据时将其设置为 true。

¥Set this true while waiting for new data from a refresh.

类型
boolean

removeClippedSubviews​

这可以提高大型列表的滚动性能。

¥This may improve scroll performance for large lists.

注意：在某些情况下可能会出现错误（缺少内容） - 使用风险由你自行承担。

¥Note: May have bugs (missing content) in some circumstances - use at your own risk.

类型
boolean

renderScrollComponent​

(props: object) => element;

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

¥Render a custom scroll component, e.g. with a differently styled RefreshControl.

类型
function

viewabilityConfig​

有关流类型和更多文档，请参阅 ViewabilityHelper.js。

¥See ViewabilityHelper.js for flow type and further documentation.

类型
可见度配置

viewabilityConfigCallbackPairs​

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

¥List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

类型
ViewabilityConfigCallbackPair 数组

updateCellsBatchingPeriod​

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

¥Amount of time between low-pri item render batches, e.g. for rendering items quite a ways off screen. Similar fill rate/responsiveness tradeoff as maxToRenderPerBatch.

类型
number

windowSize​

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

¥Determines the maximum number of items rendered outside of the visible area, in units of visible lengths. So if your list fills the screen, then windowSize={21} (the default) will render the visible screen area plus up to 10 screens above and 10 below the viewport. Reducing this number will reduce memory consumption and may improve performance, but will increase the chance that fast scrolling may reveal momentary blank areas of unrendered content.

类型
number

方法​

¥Methods

flashScrollIndicators()​

flashScrollIndicators();

getScrollableNode()​

getScrollableNode(): any;

getScrollRef()​

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

getScrollResponder()​

getScrollResponder () => ScrollResponderMixin | null;

提供底层滚动响应程序的句柄。请注意，this._scrollRef 可能不是 ScrollView，因此我们需要在调用之前检查它是否响应 getScrollResponder。

¥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()​

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

滚动到内容末尾。如果没有 getItemLayout 属性，可能会很卡顿。

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

参数：

¥Parameters:

名称类型
paramsobject

有效的 params 键为：

¥Valid params keys are:

  • 'animated'（布尔值） - 列表是否应该在滚动时播放动画。默认为 true。

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

scrollToIndex()​

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

有效 params 包括：

¥Valid params consist of:

  • 'index'（号码）。必需的。

    ¥'index' (number). Required.

  • 'animated'（布尔值）。可选的。

    ¥'animated' (boolean). Optional.

  • 'viewOffset'（号码）。可选的。

    ¥'viewOffset' (number). Optional.

  • 'viewPosition'（号码）。可选的。

    ¥'viewPosition' (number). Optional.

scrollToItem()​

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

有效 params 包括：

¥Valid params consist of:

  • 'item'（项目）。必需的。

    ¥'item' (Item). Required.

  • 'animated'（布尔值）。可选的。

    ¥'animated' (boolean). Optional.

  • 'viewOffset'（号码）。可选的。

    ¥'viewOffset' (number). Optional.

  • 'viewPosition'（号码）。可选的。

    ¥'viewPosition' (number). Optional.

scrollToOffset()​

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

滚动到列表中的特定内容像素偏移。

¥Scroll to a specific content pixel offset in the list.

参数 offset 期望滚动到的偏移量。如果 horizontal 为 true，则偏移量为 x 值，在任何其他情况下，偏移量为 y 值。

¥Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

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

¥Param animated (true by default) defines whether the list should do an animation while scrolling.