Permalink
Browse files

Update ListView Basics to use FlatList, SectionList.

Summary:
The new list views, FlatList and SectionList, are recommended over ListView.

Built website on localhost and verified the guide is rendered correctly.

![screencapture-localhost-8079-react-native-docs-using-a-listview-html-1495834607096](https://cloud.githubusercontent.com/assets/165856/26513523/c5d2913a-4220-11e7-8c8d-68bb12c75736.png)
Closes #14210

Differential Revision: D5149151

Pulled By: hramos

fbshipit-source-id: f28f02ee8893c4723c73d610b96ccda51cc31410
  • Loading branch information...
hramos authored and facebook-github-bot committed Jun 2, 2017
1 parent 07ee04d commit c419ae8c8d0f6bb6bf54091a2a5ee2f3420af167
Showing with 107 additions and 37 deletions.
  1. +1 −1 docs/HandlingTouches.md
  2. +83 −26 docs/UsingAListView.md
  3. +1 −1 docs/UsingAScrollView.md
  4. +22 −9 website/core/SnackPlayer.js
View
@@ -56,7 +56,7 @@ A common pattern to many mobile apps is the scrollable list of items. Users inte
ScrollViews can scroll vertically or horizontally, and can be configured to allow paging through views using swiping gestures by using the `pagingEnabled` props. Swiping horizontally between views can also be implemented on Android using the [ViewPagerAndroid](docs/viewpagerandroid.html) component.
A [ListView](docs/using-a-listview.html) is a special kind of ScrollView that is best suited for displaying long vertical lists of items. It can also display section headers and footers, similar to `UITableView`s on iOS.
A [FlatList](docs/using-a-listview.html) is a special kind of ScrollView that is best suited for displaying long vertical lists of items. If you want to display section headers and footers, similar to `UITableView`s on iOS, then [SectionList](docs/using-a-listview.html) is the way to go.
### Pinch-to-zoom
View
@@ -1,52 +1,109 @@
---
id: using-a-listview
title: Using a ListView
title: Using List Views
layout: docs
category: The Basics
permalink: docs/using-a-listview.html
next: network
previous: using-a-scrollview
---
The `ListView` component displays a scrolling list of changing, but similarly structured, data.
React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either [FlatList](docs/flatlist.html) or [SectionList](docs/sectionlist.html).
`ListView` works well for long lists of data, where the number of items might change over time. Unlike the more generic [`ScrollView`](docs/using-a-scrollview.html), the `ListView` only renders elements that are currently showing on the screen, not all the elements at once.
The `FlatList` component displays a scrolling list of changing, but similarly structured, data. `FlatList` works well for long lists of data, where the number of items might change over time. Unlike the more generic [`ScrollView`](docs/using-a-scrollview.html), the `FlatList` only renders elements that are currently showing on the screen, not all the elements at once.
The `ListView` component requires two props: `dataSource` and `renderRow`. `dataSource` is the source of information for the list. `renderRow` takes one item from the source and returns a formatted component to render.
The `FlatList` component requires two props: `data` and `renderItem`. `data` is the source of information for the list. `renderItem` takes one item from the source and returns a formatted component to render.
This example creates a simple `ListView` of hardcoded data. It first initializes the `dataSource` that will be used to populate the `ListView`. Each item in the `dataSource` is then rendered as a `Text` component. Finally it renders the `ListView` and all `Text` components.
This example creates a simple `FlatList` of hardcoded data. Each item in the `data` props is rendered as a `Text` component. The `FlatListBasics` component then renders the `FlatList` and all `Text` components.
> A `rowHasChanged` function is required to use `ListView`. Here we just say a row has changed if the row we are on is not the same as the previous row.
```ReactNativeWebPlayer
```SnackPlayer?name=FlatList%20Basics
import React, { Component } from 'react';
import { AppRegistry, ListView, Text, View } from 'react-native';
export default class ListViewBasics extends Component {
// Initialize the hardcoded data
constructor(props) {
super(props);
const ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2});
this.state = {
dataSource: ds.cloneWithRows([
'John', 'Joel', 'James', 'Jimmy', 'Jackson', 'Jillian', 'Julie', 'Devin'
])
};
import { AppRegistry, FlatList, StyleSheet, Text, View } from 'react-native';
export default class FlatListBasics extends Component {
render() {
return (
<View style={styles.container}>
<FlatList
data={[
{key: 'Devin'},
{key: 'Jackson'},
{key: 'James'},
{key: 'Joel'},
{key: 'John'},
{key: 'Jillian'},
{key: 'Jimmy'},
{key: 'Julie'},
]}
renderItem={({item}) => <Text style={styles.item}>{item.key}</Text>}
/>
</View>
);
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
paddingTop: 22
},
item: {
padding: 10,
fontSize: 18,
height: 44,
},
})
// skip this line if using Create React Native App
AppRegistry.registerComponent('AwesomeProject', () => FlatListBasics);
```
If you want to render a set of data broken into logical sections, maybe with section headers, then a `SectionList` is the way to go.
```SnackPlayer?name=SectionList%20Basics
import React, { Component } from 'react';
import { AppRegistry, SectionList, StyleSheet, Text, View } from 'react-native';
export default class SectionListBasics extends Component {
render() {
return (
<View style={{flex: 1, paddingTop: 22}}>
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
<View style={styles.container}>
<SectionList
sections={[
{title: 'D', data: ['Devin']},
{title: 'J', data: ['Jackson', 'James', 'Jillian', 'Jimmy', 'Joel', 'John', 'Julie']},
]}
renderItem={({item}) => <Text style={styles.item}>{item}</Text>}
renderSectionHeader={({section}) => <Text style={styles.sectionHeader}>{section.title}</Text>}
/>
</View>
);
}
}
const styles = StyleSheet.create({
container: {
flex: 1,
paddingTop: 22
},
sectionHeader: {
paddingTop: 2,
paddingLeft: 10,
paddingRight: 10,
paddingBottom: 2,
fontSize: 14,
fontWeight: 'bold',
backgroundColor: 'rgba(247,247,247,1.0)',
},
item: {
padding: 10,
fontSize: 18,
height: 44,
},
})
// skip this line if using Create React Native App
AppRegistry.registerComponent('AwesomeProject', () => ListViewBasics);
AppRegistry.registerComponent('AwesomeProject', () => SectionListBasics);
```
One of the most common uses for a `ListView` is displaying data that you fetch from a server. To do that, you will need to [learn about networking in React Native](docs/network.html).
One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to [learn about networking in React Native](docs/network.html).
View
@@ -62,4 +62,4 @@ AppRegistry.registerComponent(
() => IScrolledDownAndWhatHappenedNextShockedMe);
```
`ScrollView` works best to present a small amount of things of a limited size. All the elements and views of a `ScrollView` are rendered, even if they are not currently shown on the screen. If you have a long list of more items that can fit on the screen, you should use a `ListView` instead. So let's [learn about the ListView](docs/using-a-listview.html) next.
`ScrollView` works best to present a small amount of things of a limited size. All the elements and views of a `ScrollView` are rendered, even if they are not currently shown on the screen. If you have a long list of more items that can fit on the screen, you should use a `FlatList` instead. So let's [learn about list views](docs/using-a-listview.html) next.
@@ -15,8 +15,10 @@ var React = require('React');
const PropTypes = require('prop-types');
const LatestSDKVersion = '15.0.0';
const LatestSDKVersion = '16.0.0';
var ReactNativeToExpoSDKVersionMap = {
'0.44': '17.0.0',
'0.43': '16.0.0',
'0.42': '15.0.0',
'0.41': '14.0.0',
};
@@ -51,33 +53,44 @@ var SnackPlayer = React.createClass({
render() {
var code = encodeURIComponent(this.props.children);
var params = this.parseParams(this.props.params);
var platform = params.platform ? params.platform : 'ios';
var name = params.name ? decodeURIComponent(params.name) : 'Example';
var platform = params.platform
? params.platform
: 'ios';
var name = params.name
? decodeURIComponent(params.name)
: 'Example';
var description = params.description
? decodeURIComponent(params.description)
: 'Example usage';
var optionalProps = {};
var { version } = this.context;
if (version === 'next') {
optionalProps['data-snack-sdk-version'] = LatestSDKVersion;
optionalProps[
'data-snack-sdk-version'
] = LatestSDKVersion;
} else {
optionalProps['data-snack-sdk-version'] = ReactNativeToExpoSDKVersionMap[
version
] || LatestSDKVersion;
optionalProps[
'data-snack-sdk-version'
] = ReactNativeToExpoSDKVersionMap[version] ||
LatestSDKVersion;
}
return (
<div className="snack-player">
<div className="mobile-friendly-snack" style={{ display: 'none' }}>
<div
className="mobile-friendly-snack"
style={{ display: 'none' }}
>
<Prism>
{this.props.children}
</Prism>
</div>
<div
className="desktop-friendly-snack"
style={{ marginTop: 15, marginBottom: 15 }}>
style={{ marginTop: 15, marginBottom: 15 }}
>
<div
data-snack-name={name}
data-snack-description={description}

0 comments on commit c419ae8

Please sign in to comment.