Necessitates Proper Modularity

    vue-mescroll

    0.0.4 • Public • Published

    mescroll

    mescroll -- 精致的下拉刷新和上拉加载js框架 (JS framework for pull-refresh and pull-up-loading)

    http://www.mescroll.com

    Vue项目单组件引用请看这里

    1. 原生js, 支持vue, 不依赖jquery,zepto

    2. 一套代码多端运行. 完美运行于android,iOS,手机浏览器,兼容PC主流浏览器

    3. 参数自由搭配, 随心定制, 轻松拓展

    4. 主流APP案例, 丰富经典

    5. 免费商用

    6. mescroll交流群

    目录:

    功能亮点 :

    1. 自动判断和提示列表无任何数据或无更多数据

    2. 支持监听列表滚动事件,无需手动判断处理列表的页码,时间等变量

    3. 可指定列表滚动到任何位置,附带平滑效果一键滚动到顶部或底部

    4. 可配置列表数据不满屏时,自动加载下一页

    5. 一个界面可支持多个下拉刷新,上拉加载

    6. 可临时锁定下拉刷新和上拉加载

    NPM

    特别感谢 @channg 帮忙整理发布NPM

    https://www.npmjs.com/package/mescroll.js NPM 安装命令:

        npm install mescroll.js
    

    Vue单组件

        npm install vue-mescroll
    

    快速入门 :

    JS 版本引用

    1. 引用 mescroll.min.css , mescroll.min.js

    2. 拷贝以下布局结构:

            <div id="mescroll" class="mescroll"> //id可以改,而"mescroll"的class不能删
                //列表内容,如:<ul>列表数据</ul> ...
            </div>  
    

    3. 创建MeScroll对象:

            var mescroll = new MeScroll("mescroll", { //第一个参数"mescroll"对应上面布局结构div的id
        		down: {
                callback: downCallback //下拉刷新的回调,别写成downCallback(),多了括号就自动执行方法了
            },
            up: {
                callback: upCallback //上拉加载回调,简写callback:function(page){upCallback(page);}
            }
        });
    

    Vue单组件版本引用

    1.

        import Mescroll from 'vue-mescroll/mescroll'
    

    2. 布局结构:

            <me-scroll
            ref="mescroll"
            :id="mescroll"	//id默认为 mescroll
            :opt-up="{}" //up 参数配置(isBounce 默认未false)
            :opt-down="{}" //down 参数配置
            :callback="() => {}" //统一回调(up、down均使用此回调)
            :up-callback="() => {}" //up 回调
            :down-callback="() => {}"> //down 回调
                
                //列表内容,如:<ul>列表数据</ul> ...
                
            </me-scroll>  
    

    3. 获取MeScroll对象实例(ref 可用):

            this.$refs.mescroll.instance
    
    温馨提示:
    1. 如果您的下拉刷新是重置列表数据,那么down完全可以不用配置,具体用法参考第一个基础案例
    解析: down内部默认调用的是mescroll.resetUpScroll(),而resetUpScroll会将page.num=1,再触发up.callback,从而实现刷新列表数据
    2. 如果您的项目是在iOS的微信,QQ,Safari等浏览器访问的,则建议配置up的isBounce为false,禁止ios的回弹效果; 解析(必读)

    4. 处理回调:

            //下拉刷新的回调
            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:每页数据条数
            function upCallback(page){
                $.ajax({
                    url: 'xxxxxx?num='+ page.num +"&size="+ page.size,
                    success: function(curPageData){
                //联网成功的回调,隐藏下拉刷新和上拉加载的状态;
                //mescroll会根据传的参数,自动判断列表如果无任何数据,则提示空;列表无下一页数据,则提示无更多数据;
                        
                //方法一(推荐): 后台接口有返回列表的总页数 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);
                        
                //设置列表数据
                //setListData(curPageData);//自行实现 TODO
                    },
                    error: function(){
                    	//联网失败的回调,隐藏下拉刷新和上拉加载的状态
                        mescroll.endErr();
                    }
             });
            }
    

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

    --- mescroll在vue中的使用案例---------- 点此在线体验 ---------- 点此查看源码 ----------

    --- 以上为mescroll最基本的用法,强烈建议您下载并查看 mescroll基础案例 , 发现mescroll更强大的功能 ~
    --- 基础案例一共6个, 每个案例3分钟, 一共花您18分钟; 这18分钟您将了解mescroll在不同情况下应如何快速配置 ~
    --- 磨刀不误砍柴工,心急吃不了热豆腐. 请静下心来体验与理解mescroll, 一定会让您事半功倍 ~
    --- 如使用中有疑问, 请先查看 常见问题专区 ~

    mescroll.m.js和mescroll.min.js

    您如果在vue,angular等环境中,因作用域的问题未能正常引入或初始化Mescroll对象,则引用mescroll.m.js;
    mescroll.m.js只是去掉了mescroll.min.js套的一层模块规范的代码:

    ;(function(name,definition){
        //检测上下文环境是否为AMD或CMD
        var hasDefine = typeof define === 'function',
            // 检测上下文环境是否为Node
            hasExports = typeof module !== 'function' && module.exports;
        if(hasDefine){
            //AMD环境或CMD环境
            define(definition);
        }else if(hasExports){
            //定义为普通Node模块
            module.exports = definition();
        }else{
            //将模块的执行结果挂在window变量中,在浏览器中this指向window对象
            this[name] = definition();
        }
    
    })('Mescroll',function(){
        var Mescroll = function(){}
        return Mescroll
    })
    
    mescroll.m.js因为没有闭包限制作用域,所以能解决某些情况下引用mescroll.min.js报'Mescroll' undefined的问题
    具体请参考 https://github.com/mescroll/mescroll/issues/56

    API文档 :

    前往官网查看 >>

    //创建mescroll对象
    var mescroll = new MeScroll("mescroll", { down: {下拉刷新的配置参数}, up: {上拉加载的配置参数} });
    
    down 下拉刷新的配置参数
    参数名 默认值 说明
    use true 是否启用下拉刷新
    auto true 是否在初始化完毕之后自动执行一次下拉刷新的回调
    autoShowLoading false 当设置auto=true时(在初始化完毕之后自动执行下拉刷新的回调)
    是否显示下拉刷新的进度
    isLock false 是否锁定下拉刷新
    isBoth false 下拉刷新时,如果滑动到列表底部是否可以同时触发上拉加载
    offset 80 在列表顶部,下拉大于80px,松手即可触发下拉刷新的回调
    outOffsetRate 0.2 在列表顶部,下拉的距离大于offset时,改变下拉区域高度比例;值越接近0,高度变化越小,表现为越往下越难拉
    bottomOffset 20 当手指touchmove位置在距离body底部20px范围内的时候结束上拉刷新,避免Webview嵌套导致touchend事件不执行
    这是1.2.1版本新增的配置,请检查最新版~
    minAngle 45 触发下拉最少要偏移的角度(滑动的轨迹与水平线的锐角值),取值区间 [0,90];默认45度,即向下滑动的角度大于45度(方位角为45°~145°及225°~315°)则触发下拉;而小于45度,将不触发下拉,避免与左右滑动的轮播等组件冲突;
    注意:没有必要配置超出[0,90]区间的值,否则角度限制无效; 因为假设配置60, 生效的方位角就已经是60°到120° 和 240°到300°的范围了;
    这是1.1.6版本新增的配置,请检查最新版~
    hardwareClass "mescroll-hardware" 硬件加速样式,解决iOS下拉因隐藏进度条而闪屏的问题,参见mescroll.css
    warpClass "mescroll-downwarp" 下拉刷新的布局容器样式,参见mescroll.css
    resetClass "mescroll-downwarp-reset" 下拉刷新高度重置的动画,参见mescroll.css
    htmlContent '<p class="downwarp-progress"></p><p class="downwarp-tip">下拉刷新</p>' 下拉刷新的布局内容
    inited function(mescroll, downwarp) { ... } 下拉刷新初始化完毕的回调(mescroll实例对象,下拉刷新容器dom对象)
    inOffset function(mescroll) { ... } 下拉的距离进入offset范围内那一刻的回调(mescroll实例对象)
    outOffset function(mescroll) { ... } 下拉的距离大于offset那一刻的回调(mescroll实例对象)
    onMoving function(mescroll, rate, downHight) { ... } 下拉过程中的回调,滑动过程一直在执行; rate下拉区域当前高度与指定距离的比值(inOffset: rate=1); downHight当前下拉区域的高度
    beforeLoading function(mescroll, downwarp) { return false; } 准备触发下拉刷新的回调; 如果要完全自定义下拉刷新,那么return true,此时将不触发showLoading和callback回调; 参考案例【淘宝 v6.8.0】
    showLoading function(mescroll) { ... } 显示下拉刷新进度的回调
    callback function(mescroll) { mescroll.resetUpScroll(); } 下拉刷新的回调; 默认重置上拉加载列表为第一页

    up 上拉加载的配置参数
    参数名 默认值 说明
    use true 是否启用上拉加载
    auto 1.3.1以前版本默认false
    1.3.1版本默认true
    是否在初始化完毕之后自动执行一次上拉加载的回调
    isLock false 是否锁定上拉加载
    isBoth false 上拉加载时,如果滑动到列表顶部是否可以同时触发下拉刷新
    isBounce true 是否允许ios的bounce回弹;默认true,允许回弹 (v 1.3.0新增)
    offset 100 列表滚动到距离底部小于100px,即可触发上拉加载的回调
    noMoreSize 5 如果列表已无数据,可设置列表的总数量要大于5条才显示无更多数据;避免列表数据过少(比如只有一条数据),显示无更多数据会不好看
    toTop {
    warpId: null,
    src: null,
    html: null,
    offset: 1000,
    warpClass: "mescroll-totop",
    showClass: "mescroll-fade-in",
    hideClass: "mescroll-fade-out",
    duration: 300,
    supportTap: false
    }
    回到顶部按钮的配置:
    warpId: 父布局的id; 默认添加在body中 (v 1.2.8 新增)
    src: 图片路径,必须配置src才会显示回到顶部按钮,不配置不显示
    html: 标签内容,默认null; 如果同时设置了src,则优先取src (2017/12/10新增)
    offset: 列表滚动1000px显示回到顶部按钮
    warpClass: 按钮样式,参见mescroll.css
    showClass: 显示样式,参见mescroll.css
    hideClass: 隐藏样式,参见mescroll.css
    duration: 回到顶部的动画时长,默认300ms
    supportTap: 如果您的运行环境支持tap,则可配置true,可减少点击延时,快速响应事件;默认false,通过onclick添加点击事件; (v 1.3.0 新增) (注:微信和PC无法响应tap事件)
    loadFull {
    use: false,
    delay: 500
    }
    use: 列表数据过少,不足以滑动触发上拉加载,是否自动加载下一页,直到满屏或者无更多数据为止; 默认false,因为可通过调高page.size避免这个情况
    delay: 延时执行的毫秒数; 延时是为了保证列表数据或占位的图片都已初始化完成,且下拉刷新上拉加载中区域动画已执行完毕;
    empty {
    warpId: null,
    icon: null,
    tip: "暂无相关数据~",
    btntext: "",
    btnClick: null,
    supportTap: false
    }
    列表第一页无任何数据时,显示的空提示布局; 需配置warpId或clearEmptyId才生效
    warpId: 父布局的id; 如果此项有值,将不使用clearEmptyId的值;
    icon: 空布局的图标路径
    tip: 提示文本
    btntext: 按钮文本
    btnClick: 点击按钮的回调
    supportTap: 如果您的运行环境支持tap,则可配置true,可减少点击延时,快速响应事件;默认false,通过onclick添加点击事件; (v 1.3.0 新增) (注:微信和PC无法响应tap事件)
    clearId null 加载第一页时需清空数据的列表id; 如果此项有值,将不使用clearEmptyId的值; 在vue中使用,则无需配置此项
    clearEmptyId null 相当于同时设置了clearId和empty.warpId; 简化写法; 在vue中使用,则无需配置此项
    hardwareClass "mescroll-hardware" 硬件加速样式,使动画更流畅,参见mescroll.css
    warpClass "mescroll-upwarp" 上拉加载的布局容器样式,参见mescroll.css
    htmlLoading '<p class="upwarp-progress mescroll-rotate"></p><p class="upwarp-tip">加载中..</p>' 上拉加载中的布局,参见mescroll.css
    htmlNodata '<p class="upwarp-nodata">-- END --</p>' 无数据的布局,参见mescroll.css
    inited function(mescroll, upwarp){} 初始化完毕的回调; 回调(mescroll实例, upwarp上拉加载的布局Dom对象)
    showLoading function(mescroll, upwarp){ ... } 显示上拉加载中的回调; 回调(mescroll实例, upwarp上拉加载的布局Dom对象)
    showNoMore function(mescroll, upwarp){ ... } 显示无更多数据的回调; 回调(mescroll实例, upwarp上拉加载的布局Dom对象)
    onScroll null 列表滑动监听, 默认null
    例 onScroll : function(mescroll, y, isUp){ ... };
    y为列表当前滚动条的位置;
    isUp=true向上滑,isUp=false向下滑)
    isUp是1.2.1版本新增的配置,请检查最新版~
    callback function(page,mescroll){} 上拉加载的回调; 回调(page对象,mescroll实例), 其中page={num:页码, size:每页数据的数量, time:第一页数据的时间}
    page {
    num:0,
    size:10,
    time:null
    }
    num: 当前页码,默认0,回调之前会加1,即callback(page)会从1开始;
    size: 每页数据的数量;
    time: 加载第一页数据服务器返回的时间;防止用户翻页时,后台新增了数据从而导致下一页数据重复;
    scrollbar {
      use : ... ,
      barClass : "mescroll-bar"
    }
    use : 是否开启自定义滚动条; PC端默认true开启自定义滚动条; 移动端默认false不使用
    barClass : 自定义滚动条的样式; 参见mescroll.css

    常用方法 :

    前往官网查看 >>

    方法名 说明
    mescroll.endByPage(dataSize, totalPage, systime);
    (v 1.2.1 新增)
    隐藏下拉刷新和上拉加载的状态, 在联网获取数据成功后调用
    dataSize : 当前页获取的数据总数(注意是当前页)
    totalPage : 列表的总页数
    systime : 加载第一页数据的服务器时间 (可空);
    mescroll.endBySize(dataSize, totalSize, systime);
    (v 1.2.1 新增)
    隐藏下拉刷新和上拉加载的状态, 在联网获取数据成功后调用
    dataSize : 当前页获取的数据总数(注意是当前页)
    totalSize : 列表的总数据量
    systime : 加载第一页数据的服务器时间 (可空);
    mescroll.endSuccess(dataSize, hasNext, systime);
    (v 1.2.1 调整)
    隐藏下拉刷新和上拉加载的状态, 在联网获取数据成功后调用
    dataSize : 当前页获取的数据量(注意是当前页)
    hasNext : 是否有下一页数据true/false
    systime : 加载第一页数据的服务器时间 (可空);
    mescroll.endErr(); 隐藏下拉刷新和上拉加载的状态, 在联网获取数据失败后调用;
    mescroll内部会自动恢复原来的页码,时间等变量;
    mescroll.resetUpScroll( isShowLoading ); 重置列表为第一页 (常用于列表筛选条件变化或切换菜单时重新刷新列表数据)
    内部实现: 把page.num=1,再主动触发up.callback
    isShowLoading 是否显示进度布局;
    1.默认null,不传参,则显示上拉加载的进度布局
    2.传参true, 则显示下拉刷新的进度布局
    3.传参false,则不显示上拉和下拉的进度 (常用于静默更新列表数据)
    mescroll.triggerDownScroll(); 主动触发下拉刷新
    mescroll.triggerUpScroll(); 主动触发上拉加载
    mescroll.setPageNum(num);
    (v 1.2.5 新增)
    设置当前page.num的值
    mescroll.setPageSize(size);
    (v 1.2.5 新增)
    设置当前page.size的值
    mescroll.scrollTo( y, t ); 滚动列表到指定位置 ( y=0回到列表顶部; 如需滚动到列表底部,可设置y很大的值,比如y=99999 ); t时长,单位ms,默认300
    mescroll.optDown; 获取下拉刷新的配置
    mescroll.optUp; 获取上拉加载的配置
    mescroll.lockDownScroll( isLock ); 锁定下拉刷新 ( isLock=ture,null 锁定 ; isLock=false 解锁 )
    mescroll.lockUpScroll( isLock ); 锁定上拉加载 ( isLock=ture,null 锁定 ; isLock=false 解锁 )
    mescroll.os
    (v 1.2.5 新增)
    mescroll.os.ios 为true, 则是ios设备;
    mescroll.os.android 为true, 则是android设备;
    mescroll.os.pc 为true, 则是PC端;
    mescroll.setBounce(boolean)
    (v 1.3.0 新增)
    mescroll.setBounce(true) 允许bounce;
    mescroll.setBounce(false) 禁止bounce

    其他方法 :

    前往官网查看 >>

    以下方法不常用,您可灵活运用于更复杂的场景
    mescroll.showDownScroll(); 显示下拉刷新的进度布局
    mescroll.triggerDownScroll() 和 mescroll.resetUpScroll() 内部有调用
    mescroll.endDownScroll(); 隐藏下拉刷新的进度布局
    mescroll.endSuccess() 和 mescroll.endErr() 内部有调用
    mescroll.showUpScroll(); 显示上拉加载的进度布局
    mescroll.triggerDownScroll() 和 mescroll.resetUpScroll() 内部有调用
    mescroll.showNoMore(); 显示上拉无更多数据的布局
    mescroll.endUpScroll() 内部有调用
    mescroll.hideUpScroll(); 隐藏上拉加载的布局
    mescroll.endUpScroll() 内部有调用
    mescroll.clearDataList(); 清空上拉加载的数据列表
    mescroll.resetUpScroll() 和 mescroll.endSuccess() 内部有调用
    mescroll.loadFull(); 检查如果加载的数据过少,无法触发上拉加载时,则自动加载下一页,直到满屏或无数据
    此方法最好在列表的图片数据加载完成之后调用,以便计算列表内容高度的准确性
    mescroll.endSuccess() 内部有调用
    mescroll.showEmpty(); 显示无任何数据的空布局
    mescroll.endSuccess() 内部有调用
    mescroll.removeEmpty(); 移除无任何数据的空布局
    mescroll.endSuccess() 内部有调用
    mescroll.showTopBtn(); 显示回到顶部的按钮
    mescroll.hideTopBtn(); 隐藏回到顶部的按钮
    mescroll.getScrollTop(); 获取滚动条的位置y; 也可以在up配置onScroll监听滚动条的位置
    mescroll.getBodyHeight(); 获取body的高度
    mescroll.getClientHeight(); 获取滚动容器的高度
    mescroll.getScrollHeight(); 获取滚动内容的高度
    mescroll.getToBottom();
    (v 1.3.0新增)
    获取当前滚动条到底部的距离
    mescroll.getStep(star, end, callback, t, rate);
    (v 1.2.8 新增)
    star : 开始值;
    end : 结束值;
    callback(step,timer) : 回调 function(step,timer),
    t : 计步时长; 传0则直接回调end值; 不传则默认300ms ;
    rate : 周期; 不传则默认30ms计步一次 ;
    此方法相当于默认在300ms内,每30ms返回star到end之间的阶梯值step; 可用于模拟帧动画
    比如mescroll的回到顶部缓冲动画,轮播导航案例的顶部菜单滚动都是通过getStep实现
    (注: 您可根据实际情况在 callback 通过 window.clearInterval(timer) 提前结束计步器)
    mescroll.version;
    (v 1.3.0新增)
    mescroll的版本号
    mescroll.destroy(); 销毁mescroll

    基础案例 base demos :

    前往官网查看 >>

    1. 【商品列表】演示下拉刷新重置列表数据

    ---------- 在线体验 ---------- 查看源码 ----------



    2. 【新闻列表】演示下拉刷新添加新数据到列表顶部

    ---------- 在线体验 ---------- 查看源码 ----------



    3. 【单mescroll】演示每次切换菜单都重置列表,不缓存数据

    ---------- 在线体验 ---------- 查看源码 ----------



    4. 【多mescroll】演示每个菜单列表仅初始化一次,切换菜单缓存数据

    ---------- 在线体验 ---------- 查看源码 ----------



    5. 【满屏加载与锁定滑动】演示自动满屏加载,可临时锁定上拉刷新和下拉加载

    ---------- 在线体验 ---------- 查看源码 ----------



    6. 【mescroll所有配置项】源码展示mescroll所有配置项, 快速理解与调试mescroll

    ---------- 在线体验 ---------- 查看源码 ----------



    中级案例 intermediate demos :

    前往官网查看 >>

    1. 【知乎 v3.53.0】APP的下拉刷新上拉加载

    ---------- 在线体验 ---------- 查看源码 ----------



    2. 【新浪微博 v7.6.1】APP的下拉刷新上拉加载

    ---------- 在线体验 ---------- 查看源码 ----------



    3. 【贝贝 v6.0.0】APP的下拉刷新上拉加载

    ---------- 在线体验 ---------- 查看源码 ----------



    4. 【雅布力 v2.4.0】APP的下拉刷新上拉加载

    ---------- 在线体验 ---------- 查看源码 ----------



    5. 【吸顶悬浮效果】

    ---------- 在线体验 ---------- 查看源码 ----------



    6. 【关键词搜索】

    ---------- 在线体验 ---------- 查看源码 ----------



    7. 【轮播切换效果】

    ---------- 在线体验 ---------- 查看源码 ----------



    8. 【轮播导航菜单】

    ---------- 在线体验 ---------- 查看源码 ----------



    高级案例 senior demos :

    前往官网查看 >>

    1. 【淘宝 v6.8.0】APP的下拉刷新上拉加载



    2. 【京东 v6.1.0】APP的下拉刷新上拉加载



    3. 【美团 v8.2.3】APP的下拉刷新上拉加载



    4. 【美囤妈妈 v2.0.5】APP的下拉刷新上拉加载



    下载基础中级案例源码 :

    mescroll.min.css mescroll.min.js mescroll所有基础案例源码 mescroll所有中级案例源码
    【立即下载】

    获取高级案例源码 :

    mescroll高级案例源码 -- 淘宝 v6.8.0
    mescroll高级案例源码 -- 京东 v6.1.0
    mescroll高级案例源码 -- 美团 v8.2.3
    mescroll高级案例源码 -- 美囤妈妈 v2.0.5
    【 获取方法一 】
    我是大神 , 我为mescroll添砖加瓦
    在 GitHub 上 Star 和 Fork 了 mescroll
    并提出优化或改进建议,获得了采纳 ~
    【 获取方法二 】
    我爱分享 , 编写mescroll相关案例
    联系 QQ 2260429223 投稿
    评审优化后,在mescroll官网展示
    源码指向您的GitHub
    【 获取方法三 】
    我不做伸手党, 打赏任意金额
    联系 QQ 2260429223 获取高级案例源码
    打赏排行 榜上有名

    Install

    npm i vue-mescroll

    DownloadsWeekly Downloads

    10

    Version

    0.0.4

    License

    ISC

    Unpacked Size

    11.4 MB

    Total Files

    131

    Last publish

    Collaborators

    • mvpleung