FlatList
高性能的简单列表组件,支持下面这些常用的功能:
- 完全跨平台。
- 支持水平布局模式。
- 行组件显示或隐藏时可配置回调事件。
- 支持单独的头部组件。
- 支持单独的尾部组件。
- 支持自定义行间分隔线。
- 支持下拉刷新。
- 支持上拉加载。
- 支持跳转到指定行(ScrollToIndex)。
- 支持多列布局。
如果需要分组/类/区(section),请使用<SectionList>
.
示例
To render multiple columns, use the numColumns
prop. Using this approach instead of a flexWrap
layout can prevent conflicts with the item height logic.
下面是一个较复杂的例子,其中演示了如何利用PureComponent
来进一步优化性能和减少 bug 产生的可能(以下这段文字需要你深刻理解 shouldComponentUpdate 的机制,以及 Component 和 PureComponent 的不同,所以如果不了解就先跳过吧)。
- 对于
MyListItem
组件来说,其onPressItem
属性使用箭头函数而非 bind 的方式进行绑定,使其不会在每次列表重新 render 时生成一个新的函数,从而保证了 props 的不变性(当然前提是id
、selected
和title
也没变),不会触发自身无谓的重新 render。换句话说,如果你是用 bind 来绑定onPressItem
,每次都会生成一个新的函数,导致 props 在===
比较时返回 false,从而触发自身的一次不必要的重新 render。 - 给
FlatList
指定extraData={this.state}
属性,是为了保证state.selected
变化时,能够正确触发FlatList
的更新。如果不指定此属性,则FlatList
不会触发更新,因为它是一个PureComponent
,其 props 在===
比较中没有变化则不会触发更新。 keyExtractor
属性指定使用 id 作为列表每一项的 key。
本组件实质是基于<VirtualizedList>
组件的封装,继承了其所有 props(也包括所有<ScrollView>
)的 props),但在本文档中没有列出。此外还有下面这些需要注意的事项:
- 当某行滑出渲染区域之外后,其内部状态将不会保留。请确保你在行组件以外的地方保留了数据。
- 本组件继承自
PureComponent
而非通常的Component
,这意味着如果其props
在浅比较
中是相等的,则不会重新渲染。所以请先检查你的renderItem
函数所依赖的props
数据(包括data
属性以及可能用到的父组件的 state),如果是一个引用类型(Object 或者数组都是引用类型),则需要先修改其引用地址(比如先复制到一个新的 Object 或者数组中),然后再修改其值,否则界面很可能不会刷新。(译注:这一段不了解的朋友建议先学习下js 中的基本类型和引用类型。) - 为了优化内存占用同时保持滑动的流畅,列表内容会在屏幕外异步绘制。这意味着如果用户滑动的速度超过渲染的速度,则会先看到空白的内容。这是为了优化不得不作出的妥协,你可以根据自己的需求调整相应的参数,而我们也在设法持续改进。
- 默认情况下每行都需要提供一个不重复的 key 属性。你也可以提供一个
keyExtractor
函数来生成 key。
文档
Props
ScrollView Props
继承所有ScrollView 的 Props。但如果嵌套在其他同滚动方向的 FlatList 中则无效。
必需 renderItem
renderItem({item, index, separators});
从data
中挨个取出数据并渲染到列表中。
Provides additional metadata like index
if you need it, as well as a more generic separators.updateProps
function which let you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common highlight
and unhighlight
(which set the highlighted: boolean
prop) are insufficient for your use case.
类型 |
---|
function |
item
(Object): The item fromdata
being rendered.index
(number): The index corresponding to this item in thedata
array.separators
(Object)highlight
(Function)unhighlight
(Function)updateProps
(Function)select
(enum('leading', 'trailing'))newProps
(Object)
示例:
<FlatList
ItemSeparatorComponent={
Platform.OS !== 'android' &&
(({highlighted}) => (
<View
style={[style.separator, highlighted && {marginLeft: 0}]}
/>
))
}
data={[{title: 'Title Text', key: 'item1'}]}
renderItem={({item, index, separators}) => (
<TouchableHighlight
onPress={() => this._onPress(item)}
onShowUnderlay={separators.highlight}
onHideUnderlay={separators.unhighlight}>
<View style={{backgroundColor: 'white'}}>
<Text>{item.title}</Text>
</View>
</TouchableHighlight>
)}
/>
必需 data
为了简化起见,data 属性目前只支持普通数组。如果需要使用其他特殊数据结构,例如 immutable 数组,请直接使用更底层的VirtualizedList
组件。
类型 |
---|
array |
ItemSeparatorComponent
行与行之间的分隔线组件。不会出现在第一行之前和最后一行之后。 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
.
类型 |
---|
component |
ListEmptyComponent
列表为空时渲染该组件。可以是 React Component, 也可以是一个 render 函数,或者渲染好的 element。
类型 |
---|
component, function, element |
ListFooterComponent
尾部组件。可以是 React Component, 也可以是一个 render 函数,或者渲染好的 element。
类型 |
---|
component, function, element |
ListHeaderComponent
头部组件。可以是 React Component, 也可以是一个 render 函数,或者渲染好的 element。
类型 |
---|
component, function, element |
columnWrapperStyle
如果设置了多列布局(即将numColumns
值设为大于 1 的整数),则可以额外指定此样式作用在每行容器上。
类型 |
---|
style object |
extraData
如果有除data
以外的数据用在列表中(不论是用在renderItem
还是头部或者尾部组件中),请在此属性中指定。同时此数据在修改时也需要先修改其引用地址(比如先复制到一个新的 Object 或者数组中),然后再修改其值,否则界面很可能不会刷新。
类型 |
---|
any |
getItemLayout
(data, index) => {length: number, offset: number, index: number}
getItemLayout
是一个可选的优化,用于避免动态测量内容尺寸的开销,不过前提是你可以提前知道内容的高度。如果你的行高是固定的,getItemLayout
用起来就既高效又简单,类似下面这样:
getItemLayout={(data, index) => (
{length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
)}
对于元素较多的列表(几百行)来说,添加getItemLayout
可以极大地提高性能。注意如果你指定了ItemSeparatorComponent
,请把分隔线的尺寸也考虑到 offset 的计算之中。
类型 |
---|
function |
horizontal
设置为 true 则变为水平布局模式。
类型 |
---|
boolean |
initialNumToRender
指定一开始渲染的元素数量,最好刚刚够填满一个屏幕,这样保证了用最短的时间给用户呈现可见的内容。注意这第一批次渲染的元素不会在滑动过程中被卸载,这样是为了保证用户执行返回顶部的操作时,不需要重新渲染首批元素。
类型 |
---|
number |
initialScrollIndex
开始时屏幕顶端的元素是列表中的第 initialScrollIndex
个元素, 而不是第一个元素。如果设置了这个属性,则第一批initialNumToRender
范围内的元素不会再保留在内存里,而是直接立刻渲染位于 initialScrollIndex
位置的元素。需要先设置 getItemLayout
属性。
类型 |
---|
number |
inverted
翻转滚动方向。实质是将 scale 变换设置为-1。
类型 |
---|
boolean |
keyExtractor
(item: object, index: number) => string;