mescroll -- 精致的下拉刷新和上拉加载js框架（http://www.mescroll.com/index.html）

mescroll 1.3.6 文档 2018-09-10

快速开始 :

1. 下载并引用 mescroll.min.css , mescroll.min.js

2. 拷贝以下布局结构 :

	   	<div id="mescroll" class="mescroll"> //id可以改,而"mescroll"的class不能删
	   		<div> //这个div不能删, 可以改成ul或者其他容器标签.
		       	 //内容...
	    		</div>
	    	</div>
		       	

3. 固定mescroll的div高度. 推荐通过定位的方式,简单快捷: (点此查看其他方法)

		.mescroll{
			position: fixed;
			top: 44px;
			bottom: 0;
			height: auto; /*如设置bottom:50px,则需height:auto才能生效*/
		}
		       	

4. 创建mescroll对象 :

	       	var mescroll = new MeScroll("mescroll", { //第一个参数"mescroll"对应上面布局结构div的id (1.3.5版本支持传入dom对象)
	       		//如果您的下拉刷新是重置列表数据,那么down完全可以不用配置,具体用法参考第一个基础案例
	       		//解析: down.callback默认调用mescroll.resetUpScroll(),而resetUpScroll会将page.num=1,再触发up.callback
				down: {
					callback: downCallback //下拉刷新的回调,别写成downCallback(),多了括号就自动执行方法了
				},
				up: {
					callback: upCallback, //上拉加载的回调
					//以下是一些常用的配置,当然不写也可以的.
					page: {
						num: 0, //当前页 默认0,回调之前会加1; 即callback(page)会从1开始
						size: 10 //每页数据条数,默认10
					},
					noMoreSize: 5, //如果列表已无数据,可设置列表的总数量要大于5才显示无更多数据;
							避免列表数据过少(比如只有一条数据),显示无更多数据会不好看
					toTop: {
						//回到顶部按钮
						src: "../img/mescroll-totop.png", //图片路径,默认null,支持网络图
						offset: 1000 //列表滚动1000px才显示回到顶部按钮	
					},
					empty: {
						//列表第一页无任何数据时,显示的空提示布局; 需配置warpId才显示
						warpId:	"xxid", //父布局的id (1.3.5版本支持传入dom元素)
						icon: "../img/mescroll-empty.png", //图标,默认null,支持网络图
						tip: "暂无相关数据~" //提示
					},
					lazyLoad: {
		        			use: true // 是否开启懒加载,默认false
		        			attr: ‘imgurl‘ // 标签中网络图的属性名 : <img imgurl=‘网络图  src=‘占位图‘‘/>
		        		}
				}
			});
		       	

5. 处理回调 :

		//下拉刷新的回调
		function downCallback() {
			$.ajax({
				url: ‘xxxxxx‘,
				success: function(data) {
					//联网成功的回调,隐藏下拉刷新的状态;
					mescroll.endSuccess(); //无参. 注意结束下拉刷新是无参的
					//设置数据
					//setXxxx(data);//自行实现 TODO
				},
				error: function(data) {
					//联网失败的回调,隐藏下拉刷新的状态
					mescroll.endErr();
				}
			});
		}
		
		//上拉加载的回调 page = {num:1, size:10}; num:当前页 默认从1开始, size:每页数据条数,默认10
		function upCallback(page) {
			$.ajax({
				url: ‘xxxxxx?num=‘ + page.num + "&size=" + page.size, //如何修改page.num从0开始 ?
				success: function(curPageData) {
					//联网成功的回调,隐藏下拉刷新和上拉加载的状态;
					//mescroll会根据传的参数,自动判断列表如果无任何数据,则提示空,显示empty配置的内容;
					//列表如果无下一页数据,则提示无更多数据,(注意noMoreSize的配置)
					
					//方法一(推荐): 后台接口有返回列表的总页数 totalPage
					//必传参数(当前页的数据个数, 总页数)
					//mescroll.endByPage(curPageData.length, totalPage);
							
					//方法二(推荐): 后台接口有返回列表的总数据量 totalSize
					//必传参数(当前页的数据个数, 总数据量)
					//mescroll.endBySize(curPageData.length, totalSize);
							
					//方法三(推荐): 您有其他方式知道是否有下一页 hasNext
					//必传参数(当前页的数据个数, 是否有下一页true/false)
					//mescroll.endSuccess(curPageData.length, hasNext);
							
					//方法四 (不推荐),会存在一个小问题:比如列表共有20条数据,每页加载10条,共2页.
					//如果只根据当前页的数据个数判断,则需翻到第三页才会知道无更多数据
					//如果传了hasNext,则翻到第二页即可显示无更多数据.
					//mescroll.endSuccess(curPageData.length);
					
					//结束下拉刷新的 mescroll.endSuccess()无参.
					//结束上拉加载 curPageData.length必传的原因:
						1.使配置的noMoreSize生效
						2.判断是否有下一页的首要依据: 当传的值小于page.size时,则一定会认为无更多数据.
						  比传入的totalPage, totalSize, hasNext具有更高的判断优先级
						3.当传的值等于page.size时,才会取totalPage, totalSize, hasNext判断是否有下一页
						  传totalPage, totalSize, hasNext主要目的是避免方法四描述的小问题
					
					//设置列表数据
					//setListData(curPageData);//自行实现 TODO
				},
				error: function(e) {
					//联网失败的回调,隐藏下拉刷新和上拉加载的状态
					mescroll.endErr();
				}
			});
		}
		       	

upCallback推荐的三个方法mescroll.endByPage(), mescroll.endBySize(), mescroll.endSuccess()是mescroll 1.2.1新增的, 请检查更新~ 
至此 mescroll 还更新了许多内容哦,点此查看~ 请保持star,这阵子都会有新功能加入~

------ 以上为mescroll最基本的用法,强烈建议您下载并查看 mescroll基础案例 , 发现mescroll更强大的功能 ~

------ 基础案例一共6个, 每个案例3分钟, 一共花您18分钟; 这18分钟您将了解mescroll在不同情况下应如何快速配置 ~

------ 特别建议您, 手动改改 mescroll-options 的每项配置, 观察修改后的效果, 可让您轻松理解各项参数, 还会有意想不到的发现哦~

------ 磨刀不误砍柴工,心急吃不了热豆腐. 请静下心来体验与理解mescroll, 一定会让您事半功倍 ~

------ 如使用中有疑问, 请先查看 常见问题专区 ~

mescroll图片懒加载的使用 ,一分钟入门: (1.3.6版本新增):

1. 确保mescroll已更新到1.3.6版本

2. 初始化mescroll的时候,在up中配置lazyLoad的use为true :

	var mescroll = new MeScroll("mescroll", {
		up: {
			lazyLoad: {
		        	use: true, // 是否开启懒加载,默认false
			        attr: ‘imgurl‘, // 网络图片地址的属性名 (图片加载成功会自动移除改属性): <img imgurl=‘网络图  src=‘占位图‘‘/>
			        showClass: ‘mescroll-lazy-in‘, // 图片加载成功的显示动画: 渐变显示,参见mescroll.css
			        delay: 500, // 列表滚动的过程中每500ms检查一次图片是否在可视区域,如果在可视区域则加载图片
			        offset: 200 // 超出可视区域200px的图片仍可触发懒加载,目的是提前加载部分图片
		    	}
		}
	})
		       	

3. 设置img或div的 imgurl 属性, 值为图片的网络地址

	img标签: <img imgurl="网络图" src="占位图"/> // 占位图直接在src设置; 图片加载成功,就会替换src的占位图
	div或其他标签: <div imgurl="网络图" style="background-image: url(占位图)"><div> // 占位图在css中设置; 图片以背景图的形式展示
		       	

4. 至此mescroll的懒加载功能已经可以正常使用了,mescroll在列表滚动时会自动加载可视区域内的图片.
另外,有时候您可能会动态添加或修改图片,希望手动触发一下懒加载,
那么只需调用 mescroll.lazyLoad() 或 mescroll.endByPage() 或 mescroll.endBySize() 或 mescroll.endSuccess() 即可.

5. mescroll的所有案例都开启了懒加载,您可参考体验. 当然这里还有专门介绍懒加载的案例~

NPM :

	       			npm install --save mescroll.js   //不要使用cnpm安装
		       	

在vue-cli的单文件中使用 (至少更新到1.3.5版本):

1. 执行npm命令安装mescroll :   npm install --save mescroll.js //不要使用cnpm安装

2. 引入mescroll.min.js :   import MeScroll from ‘mescroll.js‘

3. 引入mescroll.min.css :   import ‘mescroll.js/mescroll.min.css‘

4. vue单文件示例 :

			<template>
			  <div>
			    <!--mescroll滚动区域的基本结构,为避免id重复导致的多次初始化,这里使用ref-->
			     <div ref="mescroll" class="mescroll">
			      <div>
			      <!--内容...-->
			      </div>
			    </div>
			  </div>
			</template>
			
			<script>
			//引入mescroll.min.js和mescroll.min.css
			import MeScroll from ‘mescroll.js‘
			import ‘mescroll.js/mescroll.min.css‘
			
			export default {
			  name: ‘xxx‘,
			  data() {
			    return {
			      mescroll: null, //mescroll实例对象
			      dataList:[] //列表数据
			    }
			  },
			  mounted: function () {
			    //创建MeScroll对象
			    this.mescroll = new MeScroll(this.$refs.mescroll, { //在mounted初始化mescroll,确保此处配置的ref有值
			    	// down:{}, //下拉刷新的配置. (如果下拉刷新和上拉加载处理的逻辑是一样的,则down可不用写了)
			      up: {
			        callback: this.upCallback,
		        	// 以下是一些常用的配置,当然不写也可以的.
				page: {
					num: 0, //当前页 默认0,回调之前会加1; 即callback(page)会从1开始
					size: 10, //每页数据条数,默认10
				},
				noMoreSize: 5, //如果列表已无数据,可设置列表的总数量要大于5才显示无更多数据;
							避免列表数据过少(比如只有一条数据),显示无更多数据会不好看
				toTop: {
					//回到顶部按钮
					src: "./static/mescroll/mescroll-totop.png", //图片路径,默认null,支持网络图
					offset: 1000, //列表滚动1000px才显示回到顶部按钮
				},
				empty: {
					//列表第一页无任何数据时,显示的空提示布局; 需配置warpId才显示
					warpId:	"xxid", //父布局的id (1.3.5版本支持传入dom元素)
					icon: "./static/mescroll/mescroll-empty.png", //图标,默认null,支持网络图
					tip: "暂无相关数据~", //提示
				}
			      }
			    });
			  },
			  methods: {
			    //上拉回调 page = {num:1, size:10}; num:当前页 ,默认从1开始; size:每页数据条数,默认10
			    upCallback(page) {
			      //联网请求
			      axios.get("xxxxxx", {
			        params: {
			          num: page.num, //页码
			          size: page.size //每页长度
			        }
			      }).then((response)=> {
			        //请求的列表数据
			        let arr = response.data;
			        //如果是第一页需手动制空列表
			        if (page.num == 1) this.dataList = [];
			        //把请求到的数据添加到列表
			        this.dataList = this.dataList.concat(arr);
			        //数据渲染成功后,隐藏下拉刷新的状态
			        this.$nextTick(() => {
			          this.mescroll.endSuccess(arr.length);
			        })
			      }).catch((e)=> {
			        //联网失败的回调,隐藏下拉刷新和上拉加载的状态;
			        this.mescroll.endErr();
			      })
			    }
			  },
			  // 进入路由时,恢复列表状态
			  beforeRouteEnter (to, from, next) {  // 如果没有配置回到顶部按钮或isBounce,则beforeRouteEnter不用写
			    next(vm => {
			      if (vm.mescroll) {
			      	// 恢复到之前设置的isBounce状态
			        if (vm.mescroll.lastBounce != null) vm.mescroll.setBounce(vm.mescroll.lastBounce)
			        // 滚动到之前列表的位置 (注意:路由使用keep-alive才生效)
			        if (vm.mescroll.lastScrollTop) {
			          vm.mescroll.setScrollTop(vm.mescroll.lastScrollTop)
			          setTimeout(() => { // 需延时,因为setScrollTop内部会触发onScroll,可能会渐显回到顶部按钮
			            vm.mescroll.setTopBtnFadeDuration(0)// 设置回到顶部按钮显示时无渐显动画
			          }, 16)
			        }
			      }
			    })
			  },
			  // 离开路由时,记录列表状态
			  beforeRouteLeave (to, from, next) {  // 如果没有配置回到顶部按钮或isBounce,则beforeRouteLeave不用写
			    if (this.mescroll) {
			      this.mescroll.lastBounce = this.mescroll.optUp.isBounce// 记录当前是否禁止ios回弹
			      this.mescroll.setBounce(true) // 允许bounce
			      this.mescroll.lastScrollTop = this.mescroll.getScrollTop()// 记录当前滚动条的位置
			      this.mescroll.hideTopBtn(0)// 隐藏回到顶部按钮,无渐隐动画
			    }
			    next()
			  }
			}
			</script>
			
			<style scope>
			  /*通过fixed固定mescroll的高度*/
			  .mescroll {
			    position: fixed;
			    top: 44px;
			    bottom: 0;
			    height: auto;
			  }
			</style>


       	

以上写法有些繁琐,在 vue 中强烈建议使用mescroll组件,简单快捷 :

mescroll组件使用步骤 (至少更新到1.3.5版本):

1. 执行npm命令安装mescroll :   npm install --save mescroll.js //不要使用cnpm安装

2. 引入mescroll组件 :   import MescrollVue from ‘mescroll.js/mescroll.vue‘

3. vue单文件示例 :

			<template>
			  <div>
			    <!--mescroll滚动区域的基本结构-->
			    <mescroll-vue ref="mescroll" :down="mescrollDown" :up="mescrollUp" @init="mescrollInit">
			      <!--内容...-->
			    </mescroll-vue>
			  </div>
			</template>
			
			<script>
			// 引入mescroll的vue组件
			import MescrollVue from ‘mescroll.js/mescroll.vue‘
			
			export default {
			  name: ‘xxx‘,
			  components: {
			    MescrollVue // 注册mescroll组件
			  },
			  data () {
			    return {
			      mescroll: null, // mescroll实例对象
			      mescrollDown:{}, //下拉刷新的配置. (如果下拉刷新和上拉加载处理的逻辑是一样的,则mescrollDown可不用写了)
			      mescrollUp: { // 上拉加载的配置.
			        callback: this.upCallback, // 上拉回调,此处简写; 相当于 callback: function(page, mescroll) { }
			        //以下是一些常用的配置,当然不写也可以的.
				page: {
					num: 0, //当前页 默认0,回调之前会加1; 即callback(page)会从1开始
					size: 10 //每页数据条数,默认10
				},
				noMoreSize: 5, //如果列表已无数据,可设置列表的总数量要大于5才显示无更多数据;
							避免列表数据过少(比如只有一条数据),显示无更多数据会不好看
				toTop: {
					//回到顶部按钮
					src: "./static/mescroll/mescroll-totop.png", //图片路径,默认null,支持网络图
					offset: 1000 //列表滚动1000px才显示回到顶部按钮
				},
				empty: {
					//列表第一页无任何数据时,显示的空提示布局; 需配置warpId才显示
					warpId: "xxid", //父布局的id (1.3.5版本支持传入dom元素)
					icon: "./static/mescroll/mescroll-empty.png", //图标,默认null,支持网络图
					tip: "暂无相关数据~" //提示
				}
			      },
			      dataList: [] // 列表数据
			    }
			  },
			  beforeRouteEnter (to, from, next) { // 如果没有配置回到顶部按钮或isBounce,则beforeRouteEnter不用写
			    next(vm => {
			      vm.$refs.mescroll.beforeRouteEnter() // 进入路由时,滚动到原来的列表位置,恢复回到顶部按钮和isBounce的配置
			    })
			  },
			  beforeRouteLeave (to, from, next) { // 如果没有配置回到顶部按钮或isBounce,则beforeRouteLeave不用写
			    this.$refs.mescroll.beforeRouteLeave() // 退出路由时,记录列表滚动的位置,隐藏回到顶部按钮和isBounce的配置
			    next()
			  },
			  methods: {
			    // mescroll组件初始化的回调,可获取到mescroll对象
			    mescrollInit (mescroll) {
			      this.mescroll = mescroll
			    },
			    // 上拉回调 page = {num:1, size:10}; num:当前页 ,默认从1开始; size:每页数据条数,默认10
			    upCallback (page, mescroll) {
			      // 联网请求
			      axios.get(‘xxxxxx‘, {
			        params: {
			          num: page.num, // 页码
			          size: page.size // 每页长度
			        }
			      }).then((response) => {
			        // 请求的列表数据
			        let arr = response.data
			        // 如果是第一页需手动制空列表
			        if (page.num === 1) this.dataList = []
			        // 把请求到的数据添加到列表
			        this.dataList = this.dataList.concat(arr)
			        // 数据渲染成功后,隐藏下拉刷新的状态
			        this.$nextTick(() => {
			          mescroll.endSuccess(arr.length)
			        })
			      }).catch((e) => {
			        // 联网失败的回调,隐藏下拉刷新和上拉加载的状态;
			        mescroll.endErr()
			      })
			    }
			  }
			}
			</script>
			
			<style scope>
			  /*通过fixed固定mescroll的高度*/
			  .mescroll {
			    position: fixed;
			    top: 44px;
			    bottom: 0;
			    height: auto;
			  }
			</style>
		

参数说明 :

常用方法 :

其他方法 :