可上拉请求数据,下拉刷新当前页面数据的垂直滚动容器,主要应用场景:
在列表数据展现时,可根据需要分页展示数据列表,并能实现根据上拉和下拉手势对当前页面展示的数据进行刷新、增加处理

构造函数

cmp.listView

cmp.listView
(
  • container
  • [opts]
)
Object

参数:

名称类型标识描述
container String 必选

列表容器标识,querySelector能定位的css选择器均可,比如:id、.class等,如:"#id"、".class"(必须符合以上两种形式的查询)

[opts] Object 可选

配置上拉下拉参数,如果没有定义,则该容器是一个普通列表,不会有分页、上拉下拉特征

名称类型标识描述
[config] Object 可选

数据刷新、分页数量等参数的配置(组件提供了默认值)

名称类型标识描述
[captionType] Number 可选
下拉上拉控件显示类型
  • 0:不显示条数,只显示文字
  • 1:显示条数和文字(默认)
[pageSize] Number 可选
分页大小(默认:20)
[height] Number 可选
下拉刷新的高度(默认:60)
params Object | Array 必选
上拉下拉刷新请求函数需要的参数,格式:{ticket: "luodx"},即开发者传的是什么参数,组件就返回给开发者怎么参数,其中格式:
  • 对象格式:在调用开发者的dataFunc时返回两个参数给开发者,1、第一个参数:包含开发者的传参和pageNo+pageSize;2、第二个参数:包含了组件的成功回调+错误回调+组件返回的参数
  • 数组格式(最多有两个item):在调用开发者的dataFunc时返回三个参数给开发者,1、第一个参数:开发者传的数组的第一个参数2、第二个参数:包含开发者的传参和pageNo+pageSize;3、第三个参数:包含了组件的成功回调+错误回调+组件返回的参数
dataFunc Function 必选
上拉下拉刷新请求数据的函数
renderFunc Function 必选
下拉上拉刷新数据请求完毕渲染列表的函数
renderNoDataCallback Function 必选
无数据时回调开发者定义的函数
[isClear] Boolean 可选
是否在进行使用同一个listview时,在进行面包屑或页签切换时重新向服务器请求数据(而不缓存数据)
  • true:重新请求;
  • false:不重新请求(默认)
[clearCache] Boolean 可选
当isClear为false的时候,页面跳转后回到当前页面,是否需要清空之前的缓存,
  • true:需要清空
  • false:不清空(默认)
[crumbsID] Number 可选
面包屑/页签id,用于区分同一个listview对象时,有面包屑/页签时,对数据进行缓存,避免重复向服务器请求已经请求过的数据,以及页面跳转后缓存前一个页面最后一次所在的面包屑/页签数据
[purpose] Number 可选
列表用作的方式,应用场景当首次请求无数据时,以一个开发者自定义的html来展示.
  • 1:普通内容展示;
  • 2:搜索内容展示
  • 以后进行扩展
  • -1:开发者自己渲染无数据的页面,还是要走开发者定义的渲染方法,只是返回的数据为空
[onePageMaxNum] Number 可选
一屏最大数据条数,用于上一页下一页的切换显示,默认:80条
[customScrollMoveEvent] Function 可选
自定义滚动到顶部的事件,如果开发着定义该值,将滚动的y值返回给开发者
[clearUI] Boolean 可选
是否销毁之前创建的listview对象,默认false
[down] Object 可选

下拉控件的文字、数据数量配置

名称类型标识描述
[contentdown] String 可选
在下拉可刷新状态时,下拉刷新控件上显示的标题内容(默认:"下拉可以刷新")
[contentover] String 可选
在释放可刷新状态时,下拉刷新控件上显示的标题内容(默认:"释放立即刷新")
[contentrefresh] String 可选
正在刷新状态时,下拉刷新控件上显示的标题内容(默认:"正在刷新...")
[contentprepage] String 可选
请求数据条数超过一屏了,需要显示【上一页】的文字
[up] Object 可选

上拉控件的文字、数据数量配置

名称类型标识描述
[contentdown] String 可选
在上拉可刷新状态时,上拉刷新控件上显示的标题内容(默认:"上拉显示更多")
[contentrefresh] String 可选
正在加载状态时,上拉加载控件上显示的标题内容(默认:"正在加载...")
[contentnomore] String 可选
请求完毕若没有更多数据时显示的提醒内容(默认:"没有更多数据了")
[contentnextpage] String 可选
请求数据条数满一屏了,需要显示【下一页】的文字
[imgCache] Boolean 可选

是否进行列表中图片的缓存和懒加载

  • true:进行缓存;
  • false:不缓存;
  • 默认:未定义

[offset] Object 可选

当开启列表图片缓存和懒加载时,如果是有弹出层的情况,需要设置该值,

  • x:页面X坐标开始检测图片的懒加载位置(默认:0,即页面最左边)
  • x:页面Y坐标开始检测图片的懒加载位置(默认:0,即页面最上面边,比如:选人组件是从页面底部弹出的,那么Y坐标的检测位置应该从window.innerHeight开始检测)

返回值:

[Object]

返回一个scroll对象:
对象提供调用方法

  • refresh:刷新列表(当容器html内容有增减改变时,需要开发者调用此方法,容器重新计算高度)
    cmp.listView("container").refresh()
  • scrollTo:滚动到容器指定位置
    cmp.listView("container").scrollTo(x,y)
  • updateAdditionalParts:如果有额外部件的话,可以重新更新额外部件,如果不传值的话,则是删除额外部件,并进行滚动区刷新
    cmp.listView("#container").updateAdditionalParts(true); true:即将html中的额外部件显示出来,false为隐藏起
    额外部件存放位置,应该是cmp-scroll的后面如:
    <div class="cmp-scroll-wrapper">
             <div class="cmp-scroll"></div>
             <div class="cmp-scroll-parts"></div><!--额外部件html位置-->
    </div>
  • refreshHeight:根据新传的高度值重置滚动容器高度
    cmp.listView("#container").refreshHeight(300);此时滚动容器高度被重置成300像素高了
  • refreshInitData:主动刷新当前列表数据,将pageNo设置成1,效果和下拉刷新效果一样
    cmp.listView("#container").refreshInitData()-------显示刷新成功的提示
    cmp.listView("#container").refreshInitData(false)-------不显示刷新成功的提示
  • destroyListview:销毁listview组件(包括删除掉上落下拉ui部分)
    cmp.listView("#container").destroyListview();
  • getSize:获取listview对象的尺寸
    var size = cmp.listView("#container").getSize();
    var x = size.x;---------滚动到的x轴位置
    var y = size.y;---------滚动到的Y轴位置
    var wrapperW = size.wrapperW-------------容器的宽度
    var wrapperH = size.wrapperH-------------容器的高度
    var scrollerW = size.scrollerW-----------滚动层的宽度
    var scrollerH = size.scrollerH-----------滚动层的高度
    var maxScrollX = size.maxScrollX---------滚动层最大可以滚动X向的距离
    var maxScrollY = size.maxScrollY---------滚动层最大可以滚动的Y向距离
    var minScrollY = size.minScrollY---------滚动层最小可以滚动的Y向距离
  • disable:禁止滚动
    cmp.listView("#container").disable();
  • enable:恢复滚动
    cmp.listView("#container").enable();

示例:

<html>
<head>
    <!--导入css文件-->
    <link rel="stylesheet" href="<%context%>/cmp/css/cmp.css"/>
</head>
<body>
<!--列表容器-->
<div id="pullrefresh" class="cmp-scroll-wrapper">
    <!-- 滚动容器 -->
    <div class="cmp-scroll">
        <div class="cmp-pull-widget">额外部件</div><!--如果需要如批量操作效果的话,在html页面定义此装载小部件的容器-->
        <!--数据列表-->
        <ul class="cmp-table-view">
        </ul>
    </div>
</div>
<!--导入的js文件-->
<script src="<%context%>/cmp/js/cmp.js"></script>
<script src="<%context%>/cmp/js/cmp-listView.js"></script>
<script>
    cmp.listView("#pullrefresh", {   //容器标识(当前是用id的方式来查询的)
        config: {
            isClear:false,//是否重新创建新的listview;false:不重新创建(默认:false)true:重新创建
            imgCache:true,//是否进行列表中图片的缓存true:进行缓存;false:不缓存;默认:未定义
            crumbsID:"anyCrumbsID",//面包屑ID,使用场景,在创建一个listview的时候,进行面包屑切换后,可对应到相应的面包屑数据,当再切换回原来的面包屑后,
                                    // 不需要重新向后台请求数据,可直接进行渲染,并将滚动位置滚动到,开始的那个面包屑最后一次操作,滚动到的位置,(默认:未定义;如果是没有面包屑/页签的场景,可以不用定义)
            purpose:1,//列表用作的方式,应用场景当首次请求无数据时,以一个无数据的图片来展示,1:普通内容展示;2:搜索内容展示
            captionType:0,  //不显示条数,只显示文字
            pageSize:20,    //一次请求数据显示20条数据
            height:60,      //手势下拉到60px时进行刷新操作
            params: ['', {ticket: "luodx"}],//上拉下拉刷新请求函数需要的关键参数
            onePageMaxNum:80,//一屏最大数据条数,用于上一页下一页的切换显示,默认:80条
            offset:{
                x:0,
                y:0
            },
            dataFunc: function(params,option){  //请求数据的函数
                var success = option.success; //success用于参数请求成功的回调,组件已经实现
                cmp.ajax({     //请求数据的方式,本例是用ajax请求
                    url:"http://...",
                    data:params, //params:之前定义用于请求刷新数据的关键参数(可能已经改变)
                    success:function(result){ //无论用什么请求,请求成功的数据result一定是数组的形式返回,按规则返回的result需要将该系列的数据总数一并返回
                        var renderData = {};  //将需要渲染的数据进行一次规则下的转换成规则下的对象(必须)
                        renderData.data = result; //按规则渲染对象的属性data为渲染数据
                        renderData.total = result.total; //按规则渲染对象的属性total为该系列数据的总数
                        success(renderData);//需要开发者将请求成功后的数据放进success方法里,组件进行处理
                    }
                });
            },
            renderFunc: function(result){  //渲染数据的函数,该result也就是dataFun中请求到的数据,如本例中dataFun中的renderData
                //do something with result to render
            },
            renderNoDataCallback:function(result){//空数据时回调开发者定义的函数

            }
        },
        down: {
            contentdown:"下拉可以刷新",
            contentover:"释放立即刷新",
            contentrefresh:"正在刷新...",
            contentprepage:"上一页"
        },
        up: {
            contentdown:"上拉显示更多",
            contentrefresh:"正在加载...",
            contentnomore:"没有更多数据了",
            contentnextpage:"下一页"

        }
    });
</script>
</body>

</html>
Top