ListView - A core component designed for efficient display of vertically
scrolling lists of changing data. The minimal API is to create a
ListView.DataSource
, populate it with a simple array of data blobs, and
instantiate a ListView
component with that data source and a renderRow
callback which takes a blob from the data array and returns a renderable
component.
Minimal example:
getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2});
return {
dataSource: ds.cloneWithRows(['row 1', 'row 2']),
};
},
render: function() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
},
ListView also supports more advanced features, including sections with sticky
section headers, header and footer support, callbacks on reaching the end of
the available data (onEndReached
) and on the set of rows that are visible
in the device viewport change (onChangeVisibleRows
), and several
performance optimizations.
There are a few performance operations designed to make ListView scroll
smoothly while dynamically loading potentially very large (or conceptually
infinite) data sets:
Only re-render changed rows - the rowHasChanged function provided to the
data source tells the ListView if it needs to re-render a row because the
source data has changed - see ListViewDataSource for more details.
Rate-limited row rendering - By default, only one row is rendered per
event-loop (customizable with the pageSize
prop). This breaks up the
work into smaller chunks to reduce the chance of dropping frames while
rendering rows.
dataSource ListViewDataSource #
initialListSize number #
How many rows to render on initial component mount. Use this to make
it so that the first screen worth of data apears at one time instead of
over the course of multiple frames.
onChangeVisibleRows function #
(visibleRows, changedRows) => void
Called when the set of visible rows changes. visibleRows
maps
{ sectionID: { rowID: true }} for all the visible rows, and
changedRows
maps { sectionID: { rowID: true | false }} for the rows
that have changed their visibility, with true indicating visible, and
false indicating the view has moved out of view.
onEndReached function #
Called when all rows have been rendered and the list has been scrolled
to within onEndReachedThreshold of the bottom. The native scroll
event is provided.
onEndReachedThreshold number #
Threshold in pixels for onEndReached.
pageSize number #
Number of rows to render per event loop.
removeClippedSubviews bool #
An experimental performance optimization for improving scroll perf of
large lists, used in conjunction with overflow: 'hidden' on the row
containers. Use at your own risk.
renderFooter function #
() => renderable
The header and footer are always rendered (if these props are provided)
on every render pass. If they are expensive to re-render, wrap them
in StaticContainer or other mechanism as appropriate. Footer is always
at the bottom of the list, and header at the top, on every render pass.
renderRow function #
(rowData, sectionID, rowID, highlightRow) => renderable
Takes a data entry from the data source and its ids and should return
a renderable component to be rendered as the row. By default the data
is exactly what was put into the data source, but it's also possible to
provide custom extractors. ListView can be notified when a row is
being highlighted by calling highlightRow function. The separators above and
below will be hidden when a row is highlighted. The highlighted state of
a row can be reset by calling highlightRow(null).
renderScrollComponent function #
(props) => renderable
A function that returns the scrollable component in which the list rows
are rendered. Defaults to returning a ScrollView with the given props.
renderSectionHeader function #
(sectionData, sectionID) => renderable
If provided, a sticky header is rendered for this section. The sticky
behavior means that it will scroll with the content at the top of the
section until it reaches the top of the screen, at which point it will
stick to the top until it is pushed off the screen by the next section
header.
renderSeparator function #
(sectionID, rowID, adjacentRowHighlighted) => renderable
If provided, a renderable component to be rendered as the separator
below each row but not the last row if there is a section header below.
Take a sectionID and rowID of the row above and whether its adjacent row
is highlighted.
scrollRenderAheadDistance number #
How early to start rendering rows before they come on screen, in
pixels.
'use strict';
var React = require('react-native');
var {
Image,
ListView,
TouchableHighlight,
StyleSheet,
Text,
View,
} = React;
var UIExplorerPage = require('./UIExplorerPage');
var ListViewSimpleExample = React.createClass({
statics: {
title: '<ListView> - Simple',
description: 'Performant, scrollable list of data.'
},
getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2});
return {
dataSource: ds.cloneWithRows(this._genRows({})),
};
},
_pressData: ({}: {[key: number]: boolean}),
componentWillMount: function() {
this._pressData = {};
},
render: function() {
return (
<UIExplorerPage
title={this.props.navigator ? null : '<ListView> - Simple'}
noSpacer={true}
noScroll={true}>
<ListView
dataSource={this.state.dataSource}
renderRow={this._renderRow}
/>
</UIExplorerPage>
);
},
_renderRow: function(rowData: string, sectionID: number, rowID: number) {
var rowHash = Math.abs(hashCode(rowData));
var imgSource = {
uri: THUMB_URLS[rowHash % THUMB_URLS.length],
};
return (
<TouchableHighlight onPress={() => this._pressRow(rowID)}>
<View>
<View style={styles.row}>
<Image style={styles.thumb} source={imgSource} />
<Text style={styles.text}>
{rowData + ' - ' + LOREM_IPSUM.substr(0, rowHash % 301 + 10)}
</Text>
</View>
<View style={styles.separator} />
</View>
</TouchableHighlight>
);
},
_genRows: function(pressData: {[key: number]: boolean}): Array<string> {
var dataBlob = [];
for (var ii = 0; ii < 100; ii++) {
var pressedText = pressData[ii] ? ' (pressed)' : '';
dataBlob.push('Row ' + ii + pressedText);
}
return dataBlob;
},
_pressRow: function(rowID: number) {
this._pressData[rowID] = !this._pressData[rowID];
this.setState({dataSource: this.state.dataSource.cloneWithRows(
this._genRows(this._pressData)
)});
},
});
var THUMB_URLS = ['https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-ash3/t39.1997/p128x128/851549_767334479959628_274486868_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851561_767334496626293_1958532586_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-ash3/t39.1997/p128x128/851579_767334503292959_179092627_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851589_767334513292958_1747022277_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851563_767334559959620_1193692107_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851593_767334566626286_1953955109_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851591_767334523292957_797560749_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851567_767334529959623_843148472_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851548_767334489959627_794462220_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851575_767334539959622_441598241_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-ash3/t39.1997/p128x128/851573_767334549959621_534583464_n.png', 'https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-prn1/t39.1997/p128x128/851583_767334573292952_1519550680_n.png'];
var LOREM_IPSUM = 'Lorem ipsum dolor sit amet, ius ad pertinax oportere accommodare, an vix civibus corrumpit referrentur. Te nam case ludus inciderint, te mea facilisi adipiscing. Sea id integre luptatum. In tota sale consequuntur nec. Erat ocurreret mei ei. Eu paulo sapientem vulputate est, vel an accusam intellegam interesset. Nam eu stet pericula reprimique, ea vim illud modus, putant invidunt reprehendunt ne qui.';
var hashCode = function(str) {
var hash = 15;
for (var ii = str.length - 1; ii >= 0; ii--) {
hash = ((hash << 5) - hash) + str.charCodeAt(ii);
}
return hash;
};
var styles = StyleSheet.create({
row: {
flexDirection: 'row',
justifyContent: 'center',
padding: 10,
backgroundColor: '#F6F6F6',
},
separator: {
height: 1,
backgroundColor: '#CCCCCC',
},
thumb: {
width: 64,
height: 64,
},
text: {
flex: 1,
},
});
module.exports = ListViewSimpleExample;