207 lines
7.2 KiB
Markdown
207 lines
7.2 KiB
Markdown
|
|
|
|
[](https://travis-ci.org/BoxFactura/pulltorefresh.js)
|
|
[](http://badge.fury.io/js/pulltorefreshjs)
|
|
[](https://cdnjs.com/libraries/pulltorefreshjs)
|
|
|
|
[**PulltoRefresh.js**](http://www.boxfactura.com/pulltorefresh.js/) • [Demos](http://www.boxfactura.com/pulltorefresh.js/demos/basic.html)
|
|
|
|
A small, but powerful Javascript library crafted to power your webapp's pull to refresh feature. No markup needed, highly customizable and dependency-free!
|
|
|
|
---
|
|
|
|
## Donations
|
|
|
|
If you found this project helpful, please consider a donation.
|
|
|
|
[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WYS5CSZWWLNN4)
|
|
|
|
|
|
## Installation
|
|
|
|
Download PulltoRefresh either from the [NPM Registry](https://www.npmjs.com/package/pulltorefreshjs), [CDNJS](https://cdnjs.com/libraries/pulltorefreshjs) or [UNPKG](https://unpkg.com/pulltorefreshjs):
|
|
|
|
```bash
|
|
$ npm install pulltorefreshjs --save-dev
|
|
$ wget -O pulltorefresh.js https://unpkg.com/pulltorefreshjs
|
|
```
|
|
|
|
Include the JS file in your webapp and initialize it:
|
|
|
|
```js
|
|
const ptr = PullToRefresh.init({
|
|
mainElement: 'body',
|
|
onRefresh() {
|
|
window.location.reload();
|
|
}
|
|
});
|
|
```
|
|
|
|
Bundlers can consume `pulltorefreshjs` as CommonJS and ES6-modules syntax:
|
|
|
|
```js
|
|
import PullToRefresh from 'pulltorefreshjs';
|
|
// or
|
|
const PullToRefresh = require('pulltorefreshjs');
|
|
```
|
|
|
|
API
|
|
---
|
|
|
|
- **`init(options)`**
|
|
Will return a unique ptr-instance with a `destroy()` method.
|
|
- **`destroyAll()`**
|
|
Stop and remove all registered ptr-instances.
|
|
- **`setPassiveMode(isPassive)`**
|
|
Enable or disable passive mode for event handlers (new instances only).
|
|
|
|
## Options
|
|
|
|
- **`distThreshold`** (integer)
|
|
Minimum distance required to trigger the refresh.
|
|
<br />— Defaults to `60`
|
|
- **`distMax`** (integer)
|
|
Maximum distance possible for the element.
|
|
<br />— Defaults to `80`
|
|
- **`distReload`** (integer)
|
|
After the `distThreshold` is reached and released, the element will have this height.
|
|
<br />— Defaults to `50`
|
|
- **`distIgnore`** (integer)
|
|
After which distance should we start pulling?
|
|
<br />— Defaults to `0`
|
|
- **`mainElement`** (string)
|
|
Before which element the pull to refresh elements will be?
|
|
<br />— Defaults to `body`
|
|
- **`triggerElement`** (string)
|
|
Which element should trigger the pull to refresh?
|
|
<br />— Defaults to `body`
|
|
- **`ptrElement`** (string)
|
|
Which class will the main element have?
|
|
<br />— Defaults to `.ptr`
|
|
- **`classPrefix`** (string)
|
|
Which class prefix for the elements?
|
|
<br />— Defaults to `ptr--`
|
|
- **`cssProp`** (string)
|
|
Which property will be usedto calculate the element's proportions?
|
|
<br />— Defaults to `min-height`
|
|
- **`iconArrow`** (string)
|
|
The icon for both `instructionsPullToRefresh` and `instructionsReleaseToRefresh`
|
|
<br />— Defaults to `⇣`
|
|
- **`iconRefreshing`** (string)
|
|
The icon when the refresh is in progress.
|
|
<br />— Defaults to `…`
|
|
- **`instructionsPullToRefresh`** (string)
|
|
The initial instructions string.
|
|
<br />— Defaults to `Pull down to refresh`
|
|
- **`instructionsReleaseToRefresh`** (string)
|
|
The instructions string when the `distThreshold` has been reached.
|
|
<br />— Defaults to `Release to refresh`
|
|
- **`instructionsRefreshing`** (string)
|
|
The refreshing text.
|
|
<br />— Defaults to `Refreshing`
|
|
- **`refreshTimeout`** (integer)
|
|
The delay, in milliseconds before the `onRefresh` is triggered.
|
|
<br />— Defaults to `500`
|
|
- **`getMarkup`** (function)
|
|
It returns the default HTML for the widget, `__PREFIX__` is replaced.
|
|
<br />— See [src/lib/markup.js](src/lib/markup.js)
|
|
- **`getStyles`** (function)
|
|
It returns the default CSS for the widget, `__PREFIX__` is replaced.
|
|
<br />— See [src/lib/styles.js](src/lib/styles.js)
|
|
- **`onInit`** (function)
|
|
The initialize function.
|
|
- **`onRefresh`** (function)
|
|
What will the pull to refresh trigger? You can return a promise.
|
|
<br />— Defaults to `window.location.reload()`
|
|
- **`resistanceFunction`** (function)
|
|
The resistance function, accepts one parameter, must return a number, capping at 1.
|
|
<br />— Defaults to `t => Math.min(1, t / 2.5)`
|
|
- **`shouldPullToRefresh`** (function)
|
|
Which condition should be met for pullToRefresh to trigger?
|
|
<br />— Defaults to `!window.scrollY` • Please note that this default is useful whenever you're setting mainElement as the body of the document, if you need it in another element with overflow, use `!this.mainElement.scrollTop`. Refer to the [multiple instances demo](https://www.boxfactura.com/pulltorefresh.js/demos/multiple.html) for reference.
|
|
|
|
## Use with React
|
|
|
|
With [ReactDOMServer](https://reactjs.org/docs/react-dom-server.html) and `renderToString()` you can use components as
|
|
icons instead of just strings.
|
|
In this example we also use [Font Awesome](https://fontawesome.com/how-to-use/on-the-web/using-with/react) to get nice icons with animation, but you can
|
|
use any React component you like.
|
|
|
|
[Demo on codesandbox.io](https://codesandbox.io/s/21o9z8rrzy)
|
|
|
|
```jsx harmony
|
|
|
|
import React, { Component } from 'react';
|
|
import ReactDOMServer from 'react-dom/server';
|
|
import PullToRefresh from 'pulltorefreshjs';
|
|
import { faSyncAlt} from '@fortawesome/free-solid-svg-icons';
|
|
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
|
|
|
|
class App extends Component
|
|
{
|
|
componentDidMount()
|
|
{
|
|
PullToRefresh.init({
|
|
mainElement: 'body',
|
|
onRefresh() {
|
|
window.location.reload();
|
|
},
|
|
iconArrow: ReactDOMServer.renderToString(
|
|
<FontAwesomeIcon icon={faSyncAlt} />
|
|
),
|
|
iconRefreshing: ReactDOMServer.renderToString(
|
|
<FontAwesomeIcon icon={faSyncAlt} spin={true} />
|
|
),
|
|
});
|
|
}
|
|
|
|
componentWillUnmount()
|
|
{
|
|
// Don't forget to destroy all instances on unmout
|
|
// or you will get some glitches.
|
|
PullToRefresh.destroyAll();
|
|
}
|
|
|
|
render()
|
|
{
|
|
return (
|
|
<div>
|
|
<h1>App</h1>
|
|
</div>
|
|
);
|
|
}
|
|
}
|
|
|
|
export default App;
|
|
```
|
|
|
|
## Contribute
|
|
|
|
To quickly start the development workflow:
|
|
|
|
1. Install NodeJS ([NVM](https://github.com/creationix/nvm/blob/master/nvm.sh))
|
|
2. Run `nvm use 10 && npm install`
|
|
3. Then `npm run dev`
|
|
|
|
> This will watch and compile the bundle for browser usage.
|
|
|
|
E2E tests are executed with Testcafé.
|
|
|
|
- Run `npm test` to use standard Chrome
|
|
- Run `npm pretest && npm run test:ci` to run Chrome in headless mode
|
|
|
|
Advanced debug can be achieved with `testcafe-live`, e.g.
|
|
|
|
```bash
|
|
$ npm test --live chrome tests/e2e/cases --debug-on-fail
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
- [ ] More events: `onPullStart`, `onPullDown(direction, willRefresh)`, `onRelease(willRefresh)`
|
|
- [ ] Fully customizable CSS
|
|
- [ ] Gallery of use cases
|
|
- [ ] Advanced demos
|
|
- [x] Tests
|
|
- [x] Minified releases
|