Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jsdf/react-native-refreshable-listview
Deprecated. A pull-to-refresh ListView which shows a loading spinner while your data reloads
https://github.com/jsdf/react-native-refreshable-listview
Last synced: 6 days ago
JSON representation
Deprecated. A pull-to-refresh ListView which shows a loading spinner while your data reloads
- Host: GitHub
- URL: https://github.com/jsdf/react-native-refreshable-listview
- Owner: jsdf
- Created: 2015-03-31T15:42:15.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-03-18T07:58:25.000Z (over 7 years ago)
- Last Synced: 2024-12-01T06:55:51.763Z (12 days ago)
- Language: JavaScript
- Homepage:
- Size: 289 KB
- Stars: 1,381
- Watchers: 49
- Forks: 168
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- my-awesome - react-native-refreshable-listview - A pull-to-refresh ListView which shows a loading spinner while your data reloads (JavaScript)
README
# React Native RefreshableListView
A pull-to-refresh ListView which shows a loading spinner while your data reloads
*Deprecated*: now you can use the built-in [RefreshControl](https://facebook.github.io/react-native/docs/refreshcontrol.html) instead.
In action (from [ReactNativeHackerNews](https://github.com/jsdf/ReactNativeHackerNews)):
## Usage
**Note:** these are the docs for the 2.x branch, currently in beta. If you are looking for the docs for a 1.x version, see the [1.x branch](https://github.com/jsdf/react-native-refreshable-listview/tree/1.x).
You can install the latest beta with `npm install react-native-refreshable-listview@next`
### RefreshableListView
Replace a ListView with a RefreshableListView to add pulldown-to-refresh
functionality. Accepts the same props as ListView, plus a few extras (see the **props** definitions below).
```js
var React = require('react-native')
var {Text, View, ListView} = React
var RefreshableListView = require('react-native-refreshable-listview')
var ArticleStore = require('../stores/ArticleStore')
var StoreWatchMixin = require('./StoreWatchMixin')
var ArticleView = require('./ArticleView')
var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2}) // assumes immutable objects
var ArticlesScreen = React.createClass({
mixins: [StoreWatchMixin],
getInitialState() {
return {dataSource: ds.cloneWithRows(ArticleStore.all())}
},
getStoreWatches() {
this.watchStore(ArticleStore, () => {
this.setState({dataSource: ds.cloneWithRows(ArticleStore.all())})
})
},
reloadArticles() {
// returns a Promise of reload completion
// for a Promise-free version see ControlledRefreshableListView below
return ArticleStore.reload()
},
renderArticle(article) {
return
},
render() {
return (
)
}
})
```
#### Props
- `loadData: func.isRequired`
A function returning a Promise or taking a callback, invoked upon pulldown.
The refreshing indicator (spinner) will show until the Promise resolves or the callback
is called.
- `refreshDescription: oneOfType([string, element])`
Text/element to show alongside spinner. If a custom
`refreshingIndicatorComponent` is used this value will be passed as its
`description` prop.
- `refreshingIndicatorComponent: oneOfType([func, element])`
Content to show in list header when refreshing. Can be a component class or
instantiated element. Defaults to `RefreshableListView.RefreshingIndicator`.
You can easily customise the appearance of the indicator by passing in a
customised ``, or provide your own
entirely custom content to be displayed.
- `minDisplayTime: number`
Minimum time the spinner will show for.
- `minBetweenTime: number`
Minimum time after a refresh before another refresh can be performed.
- `minPulldownDistance: number`
Minimum distance (in px) which the list has to be scrolled off the top to
trigger a refresh.
- `ignoreInertialScroll: bool`
Require the user to be actually touching the screen when the pulldown distance
exceeds `minPulldownDistance` to trigger a refresh (eg. not just inertially
scrolling off the top). Defaults to `true`.
- `onScroll: func`
An event handler for the `onScroll` event which will be chained after the one
defined by the `RefreshableListView`.
- `scrollEventThrottle: number`
How often `ListView` produces scroll events, in ms. Defaults to a fairly low
value, try setting it higher if you encounter performance issues. Keep in mind
that a higher value will make the pulldown-to-refresh behaviour less responsive.
- `colors: array of strings`
Colors to be used for pull to refresh indicator in Android
- `progressBackgroundColor: string`
Color to be used for pull to refresh indicator background in Android
### ControlledRefreshableListView
Low level component used by `RefreshableListView`. Use this directly if you want
to manually control the refreshing status (rather than using a Promise).
This component is more suitable for use in a [Redux](https://github.com/rackt/redux)-style connected component.
```js
var React = require('react-native')
var {Text, View, ListView} = React
var {ControlledRefreshableListView} = require('react-native-refreshable-listview')
var ArticleView = require('./ArticleView')
var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2}) // assumes immutable objects
var ArticlesScreen = React.createClass({
propTypes: {
// eg. props mapped from store state
articles: React.PropTypes.array.isRequired,
isRefreshingArticles: React.PropTypes.bool.isRequired,
// eg. a bound action creator
refreshArticles: React.PropTypes.func.isRequired,
},
getInitialState() {
return {dataSource: ds.cloneWithRows(this.props.articles)}
},
componentWillReceiveProps(nextProps) {
if (this.props.articles !== nextProps.articles) {
this.setState({dataSource: ds.cloneWithRows(nextProps.articles)})
}
},
renderArticle(article) {
return
},
render() {
return (
)
}
})
```
#### Props
- `onRefresh: func.isRequired`
Called when user pulls listview down to refresh.
- `isRefreshing: bool.isRequired`
Whether or not to show the refreshing indicator.
- `refreshDescription: oneOfType([string, element])`
*See `RefreshableListView`*
- `refreshingIndicatorComponent: oneOfType([func, element])`
*See `RefreshableListView`*
- `minPulldownDistance: number`
*See `RefreshableListView`*
- `ignoreInertialScroll: bool`
*See `RefreshableListView`*
- `onScroll: func`
*See `RefreshableListView`*
- `scrollEventThrottle: number`
*See `RefreshableListView`*
### RefreshableListView.RefreshingIndicator
Component with activity indicator to be displayed in list header when refreshing.
(also exposed as `ControlledRefreshableListView.RefreshingIndicator`)
#### Props
- `description: oneOfType([string, element])`
Text/element to show alongside spinner.
- `stylesheet: object`
A stylesheet object which overrides one or more of the styles defined in the
[RefreshingIndicator stylesheet](lib/RefreshingIndicator.js).
- `activityIndicatorComponent: oneOfType([func, element])`
The spinner to display. Defaults to ``.
### RefreshableListView.DataSource, ControlledRefreshableListView.DataSource
Aliases of `ListView.DataSource`, for convenience.
## Howto
### Customise the refresh indicator (spinner)
Your first option is to style the default RefreshingIndicator:
```js
var indicatorStylesheet = StyleSheet.create({
wrapper: {
backgroundColor: 'red',
height: 60,
marginTop: 10,
},
content: {
backgroundColor: 'blue',
marginTop: 10,
height: 60,
},
})
}
/>
```
Alternatively, you can provide a custom RefreshingIndicator:
```js
var MyRefreshingIndicator = React.createClass({
render() {
return (
{this.props.description}
)
},
})
// or
} />
```
## Changelog
- **2.0.0-beta4**
- added Android support! (@maraujop)
- **2.0.0-beta3**
- fixed proptype warnings from internal component
- adjusted default styling of refreshing indicator
- **2.0.0-beta2**
- pulling down now reveals refreshing indicator behind current view, rather
than the refreshing indicator moving down from the top of the screen
- `renderHeaderWrapper` is no longer used
- fixed infinite refreshing when pulled down
- **1.2.0**
- deprecated `renderHeader` in favour of `renderHeaderWrapper` as some
developers seemed to be confused by the fact that a `renderHeader` handler
for a standard `ListView` will not automatically *just work* with this component,
but rather needs to be modified as described in the documentation. The new prop
`renderHeaderWrapper` works identically to the previous one, however hopefully
now it is named differently it will be more apparent that its behaviour is not
the same as with `ListView`. The `renderHeader` prop will be removed in 2.0.
- **1.1.0**
- added behaviour to ignore inertial scrolling (@dhrrgn)
- exposed props: ignoreInertialScroll, scrollEventThrottle
- **1.0.0**
- Split RefreshableListView into 3 parts:
- RefreshableListView handles 'refreshing' state by invoking 'loadData'
callback and waiting for resolution.
- ControlledRefreshableListView handles rendering of ListView header,
depending on isRefreshing prop. Calls onRefresh handler when
pulldown-to-refresh scroll motion occurs.
- RefreshingIndicator is the component rendered in the header of the
ListView when refreshing. Pass in a customised version of this (or a
completely different component) to RefreshableListView or
ControlledRefreshableListView if you want to customise refresh indicator
appearance.
- Added Jest unit tests
- **0.3.0** added minPulldownTime & minBetweenTime props, fixed bug where
refresh could happen twice
- **0.2.0** added support for ListView props setNativeProps and
getScrollResponder (@almost & @sscotth)