pullToRefresh

load your world

Contribute or Issue

There is 1 new feature to implement, JUST DO IT AND JOIN US!

pack this plugin into a npm package.

If you have problems with this plugin, then just create an issue, and I will solve it as soon as possible.

Experience

click to experience （switch to mobile device in browser）

Description

Complete features: both support "pull-down-to-refresh" and "pull-up-to-load".
Simple API: only need to provide your data-callback-function, the plugin will do the left.
Configurable: you can specific the position where "refresh/load" will be triggered, the images that show up...But the default config already works well.
Flexibility: "pull-down/pull-up" features can be "open/close" separately, and "pull-up-to-load" anamition can be added by yourself additionaly.
Experience: in line with user's operating habits, strongly support multi-touch.

Dependency

iscroll5: high performance, small footprint, dependency free, multi-platform javascript scroller.
jquery: make it much easier to use JavaScript on your website.

Implement

use "CSS Transition" for "bounce animation".
use "CSS Anamation" for "loading anamation".
use IScroll5's "Scroll Event" for "pull-up-to-load"
assign to jquery as a Static Function

Tested

wechat
mobile-chrome
safari

WARNING

There is some tricks for IScroll5 codes, all modification listed below:

// NEW FEATURE:
// user can lock scroll Y for certain direction, used by pull-to-refresh-like scenarios
lockScrollUp: function() {
	this.isScrollUpLocked = true;
},

unlockScrollUp: function() {
	this.isScrollUpLocked = false;
},
////////////////////////////////////////

_move: function (e) {

...

deltaX = this.hasHorizontalScroll ? deltaX : 0;
deltaY = this.hasVerticalScroll ? deltaY : 0;

// NEW FEATURE:
// user can lock scroll Y for certain direction, used by pull-to-refresh-like scenarios
deltaY = deltaY < 0 && this.isScrollUpLocked ? 0 : deltaY;

...

lockScrollUp: is used to prevent iscroll's from scrolling while the user pull up the "pull-down-to-refresh".
unlockScrollUp: free the iscroll's scrolling-up lock.
_move: if scroll-y direction is up and lockScrollUp is called before, then reset deltaY to ZERO.

Usage

Import js and css

<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script src="iscroll.js"></script>
<script src="pullToRefresh.js"></script>
<link rel='stylesheet' type='text/css' href = 'pullToRefresh.css'>

Prepare Container

<div id="container">
	<div id="content"></div>
</div>

scroll-bar will appear inside container, you should add CSS below for it:
- position: absolute/relative/fixed.
- height: any container can't have scroll-bar without a fixed height.
content should hold your html, and the scroll-bar will appear when content is higher than container.
this plugin doesn't need "id" attribute in container and content, it is just an example here.

Install plugin

        var pullToRefresh = $.installPullToRefresh("#container", {
            onRefresh: function(refreshDone) {
                setTimeout(function() {
                    refreshDone();
                }, 0)
            },
            onLoad: function(loadDone) {
                setTimeout(function() {
                    loadDone();
                }, 0);
            },
            // noRefresh: true,
            // noLoad: true,
            // pauseBound: 40,
            // lowerBound: 80,
            // loadImg: "load.png",
            // pullImg: "pull.png",
            // bottomHeight: 1,
        });

first param: the javascript dom object or query-string of container.
second param: the config for plugin:
- onRefresh: callback when refresh is triggered, you may do ajax here to fill the latest data into "#content".
- onLoad: callback when load is triggered, you may do ajax here to append more data to "#content".
- noRefresh：set to true if you do not need "pull-down-to-refresh" featrue.
- noLoad：set to true if you do not need "pull-up-to-load" feature.
- pauseBound: the height where loading image stays while refreshing.
- lowerBound: the max height that user can pull down.
- loadImg: the url of refreshing image.
- pullImg: the url of pulling image.
- bottomHeight: the distance from content's bottom when "pull-up-to-load" will be triggered.

Redraw

If you have updated the html in "#content" that changes the height of "#content" outside onRefresh/onLoad callback, you MUST do the following, otherwise the iscroll5-bar may occur a drawing error:

pullToRefresh.refresh();

Force refresh

You may need to load data for the first screen in app without user's touch, the following method will trigger a "pull-down-to-refresh" immediately:

pullToRefresh.triggerPull();

pullToRefresh

加载你的世界

贡献与提问

现在有一个待实现的功能，希望你加入一起搞定！

将插件打包成npm可用形式

如果你对插件使用过程有任何BUG与需求，请创建一个ISSUE，我会尽快回复与解决

效果

点击体验（选择手机模式）

说明

完整的功能：同时支持"下拉刷新"，"上拉加载"
简单的接口：用户仅需提供数据回调函数，框架负责剩余任务
参数化配置：用户可自定义"下拉/上拉"的触发位置、图片等，但是默认值通常可以满足需求
灵活的设定："下拉/上拉"特性可独立"开启/关闭","上拉加载"特效交由用户订制
良好的体验：拖拽行为符合用户习惯，支持强大的多点触摸

依赖

iscroll5：兼容各移动平台的滚动条方案
jquery：高效跨平台的DOM操作

实现

基于transition实现bounce回弹动画
基于anamation实现自旋loading加载动画
基于iscroll5滚动事件实现"上拉加载"
基于jquery静态函数实现为插件

原理

参考鱼儿的博客

测试

微信浏览器
chrome移动浏览器
safari浏览器

注意

我为IScroll5打了一个小补丁, 所有的修改列举如下：

// NEW FEATURE:
// user can lock scroll Y for certain direction, used by pull-to-refresh-like scenarios
lockScrollUp: function() {
	this.isScrollUpLocked = true;
},

unlockScrollUp: function() {
	this.isScrollUpLocked = false;
},
////////////////////////////////////////

_move: function (e) {

...

deltaX = this.hasHorizontalScroll ? deltaX : 0;
deltaY = this.hasVerticalScroll ? deltaY : 0;

// NEW FEATURE:
// user can lock scroll Y for certain direction, used by pull-to-refresh-like scenarios
deltaY = deltaY < 0 && this.isScrollUpLocked ? 0 : deltaY;

...

lockScrollUp: 当用户下拉刷新并将动画向反方向拉回的时候，阻止IScroll5跟随滚动
unlockScrollUp: 解除对IScroll5的Y轴上拉锁定
_move: 如果当前正在向上拉动Y轴，并且Y轴上拉已锁定，那么重置本次移动的deltaY为0

用法

引入文件

<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script src="iscroll.js"></script>
<script src="pullToRefresh.js"></script>
<link rel='stylesheet' type='text/css' href = 'pullToRefresh.css'>

准备容器

<div id="container">
	<div id="content"></div>
</div>

container内的区域将出现滚动条，需添加以下CSS：
- position：relative/absolute/fixed
- height：固定高度,才能出现滚动条
content容纳内容，必须是container的唯一子元素
注：插件并不会依赖2个div的id属性, 这里仅仅为了演示用途

初始化插件

        // 安装下拉刷新插件
        var pullToRefresh = $.installPullToRefresh("#container", {
            onRefresh: function(refreshDone) {
                setTimeout(function() {
                    refreshDone();
                }, 0)
            },
            onLoad: function(loadDone) {
                setTimeout(function() {
                    loadDone();
                }, 0);
            },
            // noRefresh: true,
            // noLoad: true,
            // pauseBound: 40,
            // lowerBound: 80,
            // loadImg: "load.png",
            // pullImg: "pull.png",
            // bottomHeight: 1,
        });

第一个参数：container的节点Jquery选择语法或者dom对象
第二个参数：插件配置，所有内容列举如下：
- onRefresh：刷新回调函数，你应该在此发起ajax请求完整数据并覆盖到content内部，最后调用refreshDone通知插件完成
- onLoad：加载回调函数，你应该在此发起ajax请求增量数据并追加到content末尾，最后调用loadDone通知插件完成
- noRefresh：设置为true将禁止下拉刷新特性
- noLoad：设置为true将禁止上拉加载特性
- pauseBound：刷新数据时loading图标的停留高度
- lowerBound：下拉的最大高度
- loadImg：等待刷新图标的URL
- pullImg：下拉图标的URL
- bottomHeight：当距离内容底部小于该距离时触发上拉加载

重新绘制

如果你在onRefresh与onLoad之外更新了content里的内容，影响了其总高度，那么请主动发起如下重绘调用，否则可能导致滚动条绘制错误：

pullToRefresh.refresh();

主动刷新

app首屏通常需要异步获取数据，因此你可以通过下面的方式主动触发一次刷新，效果和手势滑动触发的刷新一致：

pullToRefresh.triggerPull();

owenliang/pullToRefresh

pullToRefresh

Contribute or Issue

Experience

Description

Dependency

Implement

Tested

WARNING

Usage

Import js and css

Prepare Container

Install plugin

Redraw

Force refresh

pullToRefresh

贡献与提问

效果

说明

依赖

实现

原理

测试

注意

用法

引入文件

准备容器

初始化插件

重新绘制

主动刷新