mirror of
https://github.com/facebook/react-native.git
synced 2025-11-01 09:14:26 +00:00
54 lines
16 KiB
Markdown
54 lines
16 KiB
Markdown
---
|
|
id: virtualizedlist
|
|
title: VirtualizedList
|
|
category: Components
|
|
permalink: docs/virtualizedlist.html
|
|
---
|
|
<div><div><p>Base implementation for the more convenient <a href="/react-native/docs/flatlist.html" target=""><code><FlatList></code></a>
|
|
and <a href="/react-native/docs/sectionlist.html" target=""><code><SectionList></code></a> components, which are also better
|
|
documented. In general, this should only really be used if you need more flexibility than
|
|
<code>FlatList</code> provides, e.g. for use with immutable data instead of plain arrays.</p><p>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.</p><p>Some caveats:</p><ul><li>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.</li><li>This is a <code>PureComponent</code> which means that it will not re-render if <code>props</code> remain shallow-
|
|
equal. Make sure that everything your <code>renderItem</code> function depends on is passed as a prop
|
|
(e.g. <code>extraData</code>) that is not <code>===</code> after updates, otherwise your UI may not update on
|
|
changes. This includes the <code>data</code> prop and parent component state.</li><li>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 ands 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.</li><li>By default, the list looks for a <code>key</code> prop on each item and uses that for the React key.
|
|
Alternatively, you can provide a custom <code>keyExtractor</code> prop.</li></ul></div><h3><a class="anchor" name="props"></a>Props <a class="hash-link" href="docs/virtualizedlist.html#props">#</a></h3><div class="props"><div class="prop"><h4 class="propTitle"><a class="anchor" name="listemptycomponent"></a>ListEmptyComponent?: <span class="propType"><span>?<span><span>ReactClass<any> | </span>React.Element<any></span></span></span> <a class="hash-link" href="docs/virtualizedlist.html#listemptycomponent">#</a></h4><div><p>Rendered when the list is empty. Can be a React Component Class, a render function, or
|
|
a rendered element.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="listfootercomponent"></a>ListFooterComponent?: <span class="propType"><span>?<span><span>ReactClass<any> | </span>React.Element<any></span></span></span> <a class="hash-link" href="docs/virtualizedlist.html#listfootercomponent">#</a></h4><div><p>Rendered at the bottom of all the items. Can be a React Component Class, a render function, or
|
|
a rendered element.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="listheadercomponent"></a>ListHeaderComponent?: <span class="propType"><span>?<span><span>ReactClass<any> | </span>React.Element<any></span></span></span> <a class="hash-link" href="docs/virtualizedlist.html#listheadercomponent">#</a></h4><div><p>Rendered at the top of all the items. Can be a React Component Class, a render function, or
|
|
a rendered element.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="data"></a>data?: <span class="propType">any</span> <a class="hash-link" href="docs/virtualizedlist.html#data">#</a></h4><div><p>The default accessor functions assume this is an Array<{key: string}> but you can override
|
|
getItem, getItemCount, and keyExtractor to handle any type of index-based data.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="debug"></a>debug?: <span class="propType"><span>?boolean</span></span> <a class="hash-link" href="docs/virtualizedlist.html#debug">#</a></h4><div><p><code>debug</code> will turn on extra logging and visual overlays to aid with debugging both usage and
|
|
implementation, but with a significant perf hit.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="disablevirtualization"></a>disableVirtualization: <span class="propType">boolean</span> <a class="hash-link" href="docs/virtualizedlist.html#disablevirtualization">#</a></h4><div><p>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.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="extradata"></a>extraData?: <span class="propType">any</span> <a class="hash-link" href="docs/virtualizedlist.html#extradata">#</a></h4><div><p>A marker property for telling the list to re-render (since it implements <code>PureComponent</code>). If
|
|
any of your <code>renderItem</code>, Header, Footer, etc. functions depend on anything outside of the
|
|
<code>data</code> prop, stick it here and treat it immutably.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="getitem"></a>getItem: <span class="propType">(data: any, index: number) => ?Item</span> <a class="hash-link" href="docs/virtualizedlist.html#getitem">#</a></h4><div><p>A generic accessor for extracting an item from any sort of data blob.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="getitemcount"></a>getItemCount: <span class="propType">(data: any) => number</span> <a class="hash-link" href="docs/virtualizedlist.html#getitemcount">#</a></h4><div><p>Determines how many items are in the data blob.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="getitemlayout"></a>getItemLayout?: <span class="propType">(
|
|
data: any,
|
|
index: number,
|
|
) => {length: number, offset: number, index: number}</span> <a class="hash-link" href="docs/virtualizedlist.html#getitemlayout">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="horizontal"></a>horizontal?: <span class="propType"><span>?boolean</span></span> <a class="hash-link" href="docs/virtualizedlist.html#horizontal">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="initialnumtorender"></a>initialNumToRender: <span class="propType">number</span> <a class="hash-link" href="docs/virtualizedlist.html#initialnumtorender">#</a></h4><div><p>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.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="initialscrollindex"></a>initialScrollIndex?: <span class="propType"><span>?number</span></span> <a class="hash-link" href="docs/virtualizedlist.html#initialscrollindex">#</a></h4><div><p>Instead of starting at the top with the first item, start at <code>initialScrollIndex</code>. This
|
|
disables the "scroll to top" optimization that keeps the first <code>initialNumToRender</code> items
|
|
always rendered and immediately renders the items starting at this initial index. Requires
|
|
<code>getItemLayout</code> to be implemented.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="inverted"></a>inverted?: <span class="propType"><span>?boolean</span></span> <a class="hash-link" href="docs/virtualizedlist.html#inverted">#</a></h4><div><p>Reverses the direction of scroll. Uses scale transforms of -1.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="keyextractor"></a>keyExtractor: <span class="propType">(item: Item, index: number) => string</span> <a class="hash-link" href="docs/virtualizedlist.html#keyextractor">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="maxtorenderperbatch"></a>maxToRenderPerBatch: <span class="propType">number</span> <a class="hash-link" href="docs/virtualizedlist.html#maxtorenderperbatch">#</a></h4><div><p>The maximum number of items to render in each incremental render batch. The more rendered at
|
|
once, the better the fill rate, but responsiveness my suffer because rendering content may
|
|
interfere with responding to button taps or other interactions.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onendreached"></a>onEndReached?: <span class="propType"><span>?(info: {distanceFromEnd: number}) => void</span></span> <a class="hash-link" href="docs/virtualizedlist.html#onendreached">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onendreachedthreshold"></a>onEndReachedThreshold?: <span class="propType"><span>?number</span></span> <a class="hash-link" href="docs/virtualizedlist.html#onendreachedthreshold">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onlayout"></a>onLayout?: <span class="propType"><span>?Function</span></span> <a class="hash-link" href="docs/virtualizedlist.html#onlayout">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onrefresh"></a>onRefresh?: <span class="propType"><span>?Function</span></span> <a class="hash-link" href="docs/virtualizedlist.html#onrefresh">#</a></h4><div><p>If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make
|
|
sure to also set the <code>refreshing</code> prop correctly.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="onviewableitemschanged"></a>onViewableItemsChanged?: <span class="propType"><span>?(info: {
|
|
viewableItems: Array<ViewToken>,
|
|
changed: Array<ViewToken>,
|
|
}) => void</span></span> <a class="hash-link" href="docs/virtualizedlist.html#onviewableitemschanged">#</a></h4><div><p>Called when the viewability of rows changes, as defined by the
|
|
<code>viewabilityConfig</code> prop.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="refreshing"></a>refreshing?: <span class="propType"><span>?boolean</span></span> <a class="hash-link" href="docs/virtualizedlist.html#refreshing">#</a></h4><div><p>Set this true while waiting for new data from a refresh.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="removeclippedsubviews"></a>removeClippedSubviews?: <span class="propType">boolean</span> <a class="hash-link" href="docs/virtualizedlist.html#removeclippedsubviews">#</a></h4><div><p>Note: may have bugs (missing content) in some circumstances - use at your own risk.</p><p>This may improve scroll performance for large lists.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="renderitem"></a>renderItem: <span class="propType">(info: any) => ?React.Element<any></span> <a class="hash-link" href="docs/virtualizedlist.html#renderitem">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="renderscrollcomponent"></a>renderScrollComponent?: <span class="propType">(props: Object) => React.Element<any></span> <a class="hash-link" href="docs/virtualizedlist.html#renderscrollcomponent">#</a></h4><div><p>Render a custom scroll component, e.g. with a differently styled <code>RefreshControl</code>.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="scrolleventthrottle"></a>scrollEventThrottle?: <a class="hash-link" href="docs/virtualizedlist.html#scrolleventthrottle">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="updatecellsbatchingperiod"></a>updateCellsBatchingPeriod: <span class="propType">number</span> <a class="hash-link" href="docs/virtualizedlist.html#updatecellsbatchingperiod">#</a></h4><div><p>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 <code>maxToRenderPerBatch</code>.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="viewabilityconfig"></a>viewabilityConfig?: <span class="propType">ViewabilityConfig</span> <a class="hash-link" href="docs/virtualizedlist.html#viewabilityconfig">#</a></h4></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="windowsize"></a>windowSize: <span class="propType">number</span> <a class="hash-link" href="docs/virtualizedlist.html#windowsize">#</a></h4><div><p>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 <code>windowSize={21}</code> (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.</p></div></div><div class="prop"><h4 class="propTitle"><a class="anchor" name="progressviewoffset"></a><span class="platform">android</span>progressViewOffset?: <span class="propType">number</span> <a class="hash-link" href="docs/virtualizedlist.html#progressviewoffset">#</a></h4><div><p>Set this when offset is needed for the loading indicator to show correctly.</p></div></div></div><span><h3><a class="anchor" name="methods"></a>Methods <a class="hash-link" href="docs/virtualizedlist.html#methods">#</a></h3><div class="props"><div class="prop"><h4 class="methodTitle"><a class="anchor" name="scrolltoend"></a>scrollToEnd<span class="methodType">(params?: object)</span> <a class="hash-link" href="docs/virtualizedlist.html#scrolltoend">#</a></h4></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="scrolltoindex"></a>scrollToIndex<span class="methodType">(params: object)</span> <a class="hash-link" href="docs/virtualizedlist.html#scrolltoindex">#</a></h4></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="scrolltoitem"></a>scrollToItem<span class="methodType">(params: object)</span> <a class="hash-link" href="docs/virtualizedlist.html#scrolltoitem">#</a></h4></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="scrolltooffset"></a>scrollToOffset<span class="methodType">(params: object)</span> <a class="hash-link" href="docs/virtualizedlist.html#scrolltooffset">#</a></h4><div><p>Scroll to a specific content pixel offset in the list.</p><p>Param <code>offset</code> expects the offset to scroll to.
|
|
In case of <code>horizontal</code> is true, the offset is the x-value,
|
|
in any other case the offset is the y-value.</p><p>Param <code>animated</code> (<code>true</code> by default) defines whether the list
|
|
should do an animation while scrolling.</p></div></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="recordinteraction"></a>recordInteraction<span class="methodType">()</span> <a class="hash-link" href="docs/virtualizedlist.html#recordinteraction">#</a></h4></div><div class="prop"><h4 class="methodTitle"><a class="anchor" name="flashscrollindicators"></a>flashScrollIndicators<span class="methodType">()</span> <a class="hash-link" href="docs/virtualizedlist.html#flashscrollindicators">#</a></h4></div></div></span><span><h3><a class="anchor" name="type-definitions"></a>Type Definitions <a class="hash-link" href="docs/virtualizedlist.html#type-definitions">#</a></h3><div class="props"><div class="prop"><h4 class="propTitle"><a class="anchor" name="props"></a>Props <a class="hash-link" href="docs/virtualizedlist.html#props">#</a></h4><strong>Type:</strong><br>IntersectionTypeAnnotation</div></div></span></div> |