Show:

bui.list Class

Module: UI

列表自动分页加载及刷新

注意field的配置,其中的field:{data:"data"} 为请求以后返回的数组所在字段, 对比示例的json理解. 如果结果是数组, 无需配置

list = scroll + pullrefresh 把scroll的数据请求逻辑封装,只需要传id,url,data,模板的生成器,field(把数据映射),如果需要你的页面的逻辑比较复杂,建议参考 http://www.easybui.com/demo/index.html#pages/ui_controls/bui.scroll.html" target="_blank">bui.scroll

预览地址: demo

方法说明:

refresh: 手动刷新数据
option: 获取设置参数
widget: 获取依赖的scroll控件,然后使用scroll的方法
控件预览

Constructor

bui.list

(
  • option
)

Parameters:

  • option Object
    • id String

      控件id

    • [uid] String optional

      1.6.6新增,实例的自定义唯一名字,用于命令式调用

    • url String

      数据请求地址

    • [data] Object optional

      数据请求许可参数, 分页及分页大小在field 配置, 默认请求的分页是: "page","pageSize", 这里只能是对象, 如果需要JSON.stringify 转换接口才能正确接收, 可以增加一个 needJsonString: true 参数, 会进行内部转换

    • [method] String optional

      "GET" || "POST"

    • [headers] Object optional

      通过header传输的参数 {}

    • [dataType] String optional

      默认 json | jsonp | script | xml | html | text

    • [contentType] String optional

      get默认 "", 由$.ajax处理 | post默认: 'application/x-www-form-urlencoded'(表单,接口跨域需要设置这个) | 'multipart/form-data'(表单里有file文件) | 'application/json'(后端要用@requestbody接收) 前端传过去的参数要用 JSON.stringify 转换下

    • [timeout] Number optional

      默认:20000

    • [headers] Object optional

      {}

    • [localData] Object optional

      1.4.5新增,本地数据,格式保持跟接口返回数据一致,如果有本地数据,不再请求

    • [field] Object optional

      请求及返回的真实字段, 例如: 请求的分页字段为 "pagination", 大小字段名为: "psize" , 返回的数据为 {"result":null}, 则filed={ page:"pagination",size:"psize",data:"result"};

      • [page] String optional
        默认: "page", 分页的字段名, 如果分页的字段名不是"page",需要更改
      • [size] String optional
        默认: "pageSize", 每页多少条的字段名, 如果条数的字段名不是"pageSize",需要更改,但不能为"length"
      • [data] String optional
        默认: "", 返回的字段的数组在哪个字段, 例如, 返回的数据为 {"result":null}, 则filed = {data:"result"} , 返回的数据有层级,则使用对象字符串, 例如 {"result":{ data: null }} 则 filed = {data:"result.data"}
    • [page] Number optional

      映射的请求的数据页数, 默认:1

    • [pageSize] Number optional

      映射的请求每页多少条, 默认:10

    • [children] String optional

      列表的选择器,默认: ".bui-list"

    • [handle] String optional

      列表的循环子元素,默认: ".bui-btn"

    • [direction] String optional

      1.5.6新增 滚动的方向,默认 y || x ;

    • [distance] String optional

      默认 100,下拉的距离大于100才会触发刷新

    • [backDistance] String optional

      默认 50,下拉后回去的距离,1.8.0新增

    • [handleMove] String optional

      1.6.3 默认 "main" || "head", 下拉的时候一起拖动的位置, 数据量较多建议选择head

    • [loading] Object optional

      1.8.0 loading的配置

    • [stopHandle] String optional

      1.4.2新增,样式名,默认为空,支持多个样式名,以逗号间隔. 当这个值等于下拉刷新里面的某个样式,不触发下拉刷新,一般用于事件冲突,比方 input type=range 无法滑动的时候

    • [height] Number optional

      列表的高度,默认适应,如果高度不对,自行计算后传给列表即可。

    • [cacheHeight] Boolean optional

      1.6.2新增, 默认 true | false 使用缓存的高度计算,false 则动态获取页面高度计算

    • [urlrule] Boolean optional

      1.6.2新增, 默认false | true (替换url的内容) 例如: 网易新闻的url规则 http://url.com/data-(page)-(size).json 替换成 http://url.com/data-1-10.json

    • [relative] Boolean optional

      请求的路径是否使用相对模块路径,默认: false(相对项目路径) | true(相对模块路径)

    • [commandRefresh] String optional

      刷新的操作,跟jquery操作dom一样, 默认是"html"|"append"|"prepend"|

    • [commandLoad] String optional

      加载的操作,跟jquery操作dom一样, 默认是"append"|"prepend"|

    • [needJsonString] Boolean optional

      1.4.6新增,默认 false|true. true时会尝试把数据转换为string. 这个主要配合list控件的特殊请求使用,正常都是一个对象, 如果为true,后台一般以@requestBody 接收,postman的body 是raw 的形式

    • autoNext Boolean

      [ 默认true 当高度不足时,会继续请求下一页,直到高度出现滚动条 ]

    • autoScroll Boolean

      [ 默认true 滚动到底部触发, false 自己监听 ]

    • autoUpdatePage Boolean

      [ 1.5.3 新增, 默认true 自动更新分页, 如果不是,则需要自己手动调用一次 uiList.updatePage()]

    • refresh Boolean

      [ 允许下拉刷新, 默认true | false ]

    • [scroll] Boolean optional

      1.5.6新增 默认true(允许滚动加载) | false

    • [template] Function optional

      请求到数据以后生成的模板,需要返回html字符串

    • [delayTime] Number optional

      1.8.5新增 默认 100,滚动结束后才触发onScrolling 0 则实时触发onScrolling

    • [onScrolling] Function optional

      1.8.5新增 滚动时触发

    • [onBeforeInit] Function optional

      1.5.1新增 初始化前触发

    • [onInited] Function optional

      1.5.1新增 初始化以后触发

    • [onBeforeRefresh] Function optional

      1.5.2新增, 刷新前执行

    • [proxy] String optional

      1.5.5新增, 内部修改接口为相对路径,值为:代理的二级目录,例如: 接口地址 http://easybui.com/api/getUser?id=123 配置 proxy: "/api" 这样接口请求就变成 api/getUser?id=123, 结合工程的 app.json 使用

    • [onRefresh] Function optional

      1.7.4后不推荐 刷新数据以后的回调, 第一个参数是实例本身

    • [onRefreshed] Function optional

      1.7.4 推荐 刷新数据以后的回调,,第一个参数是接口返回数据

    • [onBeforeLoad] Function optional

      1.5.2新增, 加载前执行

    • [onFirstLoad] Function optional

      1.7.4 新增,只有第一次初始化并取到数据的时候会执行

    • [onLoad] Function optional

      1.7.4后不推荐 请求数据后执行,第一个参数是实例本身

    • [onLoaded] Function optional

      1.7.4 推荐,请求数据后执行,第一个参数是接口返回数据

    • [onFail] Function optional

      失败的回调

    • [callback] Function optional

      点击每个handle的回调

    • [refreshTips] Object optional
      • [start] String optional
        开始加载的文本提醒,"刷新中.."
      • [release] String optional
        下拉的文本提醒,"松开刷新"
      • [end] String optional
        下拉高度不足提醒,"下拉刷新"
      • [fail] String optional
        下拉加载失败提醒,"点击加载"
      • [success] String optional
        成功提醒,"刷新成功"
    • [scrollTips] Object optional
      • [start] String optional
        开始加载的文本提醒,"努力加载中.."
      • [end] String optional
        上拉加载的提醒,"上拉加载更多"
      • [fail] String optional
        上拉加载失败提醒,"点击重新加载"
      • [last] String optional
        最后一页的提醒,"没有更多内容"
      • [nodata] String optional
        没有数据的提醒,"没有更多内容"

Example:

html:

        <div id="scrollList" class="bui-scroll">
                                                <div class="bui-scroll-head"></div>
                                                <div class="bui-scroll-main">
                                                    <ul class="bui-list">
                                                    </ul>
                                                </div>
                                                <div class="bui-scroll-foot"></div>
                                            </div>
                                    

js:

      // 假设: userlist.json 返回的数据格式为: { status:200, list:[] }, 配置 field: {data:"list"}
                                           // 初始化
                                            var uiList = bui.list({
                                                id: "#scrollList",
                                                url: "http://www.easybui.com/demo/json/shop.json",
                                                pageSize:5,
                                                data: {},
                                                // 如果返回的数组字段不在data,通过field重新定义
                                                field: {
                                                    page: "page",
                                                    size: "pageSize",
                                                    data: "data"
                                                },
                                                template: function (data) {
                                                    var html = "";
                                                    data.forEach(function(el, index) {
                                                       html +=`<li class="bui-btn bui-box">
                                                            <div class="bui-thumbnail"><img src="${el.image}" alt=""></div>
                                                            <div class="span1">
                                                                <h3 class="item-title">${el.name}</h3>
                                                                <p class="item-text">${el.address}</p>
                                                                <p class="item-text">${el.distance}公里</p>
                                                            </div>
                                                            <span class="price"><i>¥</i>${el.price}</span>
                                                        </li>`
                                                    });
                                                   return html;
                                                }
                                            })
                                    

Methods

abort

()

Defined in src/scripts/ui/bui.list.js:720

Available since 1.8.4

停止请求

Example:

       //停止请求
                                                       uiList.abort();
                                                

destroy

(
  • [bool]
)

Defined in src/scripts/ui/bui.list.js:897

Available since 1.4.2

[销毁控件]

Parameters:

  • [bool] Boolean optional

    默认: false 销毁部分 | true 销毁全部

Example:

       //销毁
                                                       uiList.destroy();
                                                

disable

()

Defined in src/scripts/ui/bui.list.js:925

Available since 1.8.6

禁止滚动

Example:

empty

(
  • [bool]
)

Defined in src/scripts/ui/bui.list.js:877

Available since 1.4.7

[清空数据]

Parameters:

  • [bool] Boolean optional

    默认: false 销毁部分 | true 销毁全部

Example:

       //清空数据
                                                       uiList.empty();
                                                

enable

()

Defined in src/scripts/ui/bui.list.js:938

Available since 1.8.6

允许滚动

Example:

getData

()

Defined in src/scripts/ui/bui.list.js:607

Available since 1.6.6

获取已经加载的数据

Example:

       //获取已经加载的总数据
                                                       let data = uiList.getData();
                                                

getItem

(
  • [page] [ 获取第几页数据,最小为1, 不传则获取所有]
  • [field] [ 获取指定某个字段的数据]
)

Defined in src/scripts/ui/bui.list.js:624

Available since 1.6.7

指定值的数据

Parameters:

  • [page] [ 获取第几页数据,最小为1, 不传则获取所有] Number optional
  • [field] [ 获取指定某个字段的数据] String optional

Example:

       //获取第一页数据
                                                       let data = uiList.getItem(1);
                                                
                                                       //1.6.7 新增获取第几条数据,通过索引处理
                                                       let data = uiList.getItem(10,"index");
                                                
                                                       //获取指定某个数据
                                                       let data = uiList.getItem("easybui","id");
                                                

getPage

()

Defined in src/scripts/ui/bui.list.js:433

Available since 1.7.0

获取已经加载的分页

Example:

       //获取已经加载的总数据
                                                       let data = uiList.getPage();
                                                

init

(
  • [option]
)
chainable

初始化方法,用于重新初始化结构,事件只初始化一次

Parameters:

  • [option] Object optional

    参数控件本身

last

()

Defined in src/scripts/ui/bui.list.js:951

Available since 1.8.6

最后一页

Example:

lock

() chainable

Defined in src/scripts/ui/bui.list.js:804

Available since 1.6.3

不允许滚动加载

Example:

       //uiScroll基于顶部例子
                                                       uiScroll.lock();
                                                

lockrefresh

() chainable

Defined in src/scripts/ui/bui.list.js:822

Available since 1.6.3

不允许下拉刷新

Example:

       //uiScroll基于顶部例子
                                                       uiScroll.lockrefresh();
                                                

modify

(
  • [option]
)
chainable

修改多个参数,但不执行初始化

Parameters:

  • [option] Object optional

    修改参数,跟初始化一样是一个对象.

Example:

       //修改多个参数
                                                       uiList.modify( {url:"", data:{"keyword":"关键字"}  );
                                                

option

(
  • [key]
  • [value]
)
chainable

获取设置参数

Parameters:

  • [key] String | object optional

    不传则获取所有参数, 类型为string,没有第2个参数则获取某个参数

  • [value] String | number | boolean | function optional

    设置参数的时候要传,设置多个参数不用传,获取参数的时候也不用传

Example:

       //获取所有参数
                                                       var option = uiList.option();
                                                
                                                       //获取某个参数
                                                       var id = uiList.option( "id" );
                                                
                                                       //修改data参数,只是修改,不初始化. 如果修改多个参数,会自动初始化, 在onLoad 参数里面变成死循环.
                                                       uiList.option( "data",{"keyword":"关键字"} );
                                                
                                                       //修改多个参数
                                                       uiList.option( {"height":200} );
                                                

refresh

()

Defined in src/scripts/ui/bui.list.js:702

Available since 1.3.0

刷新方法,有动画效果

Example:

       //获取依赖控件
                                                       uiList.refresh();
                                                

reload

()

Defined in src/scripts/ui/bui.list.js:766

Available since 1.5.4

重新加载,无动画

Example:

       //获取依赖控件
                                                       uiList.reload();
                                                

replace

()

Defined in src/scripts/ui/bui.list.js:737

Available since 1.6.6

刷新并替换参数

Example:

       uiList.replace({
                                                           data: {
                                                               "keyword": "test"
                                                           }
                                                       });
                                                

resize

(
  • [option]
)
chainable

Defined in src/scripts/ui/bui.list.js:1041

Available since 1.5.3

重新计算高度

Parameters:

  • [option] Object optional

    可以不传

    • [width] Number optional

      如果不传则自动计算

    • [height] Number optional

      如果不传则自动计算,一些特殊情况需要告诉它在哪个高度下自动计算

Example:

       //重新计算高度
                                                       uiList.resize();
                                                

scrollTop

(
  • [num]
)
chainable

Defined in src/scripts/ui/bui.list.js:366

Available since 1.4.3

跳到指定的滚动高度值

Parameters:

  • [num] Number | Object optional

    非必须,默认:0

Example:

           uiList.scrollTop(2);
                                                

to

(
  • index
  • callback
)
chainable

跳到指定元素

Parameters:

  • index Number

    内容的索引,例如第3个li 则 index=2

  • callback Function

    跳转后执行

Example:

           uiList.to(2);
                                                

toBottom

(
  • callback
)
chainable

跳到底部

Parameters:

  • callback Function

    跳转后执行

Example:

           uiList.toBottom();
                                                

unlock

() chainable

Defined in src/scripts/ui/bui.list.js:858

Available since 1.6.3

允许滚动加载

Example:

       //uiScroll基于顶部例子
                                                       uiScroll.unlock();
                                                

unlockrefresh

() chainable

Defined in src/scripts/ui/bui.list.js:840

Available since 1.6.3

不允许下拉刷新

Example:

       //uiScroll基于顶部例子
                                                       uiScroll.unlockrefresh();
                                                

updatePage

()

Defined in src/scripts/ui/bui.list.js:660

Available since 1.5.3

更新分页以判断是否最后一页. 一般用于autoUpdatePage:false下使用, 比方数据渲染有延迟,等渲染以后再调用该方法

Example:

       //更新分页
                                                       uiList.updatePage();
                                                

widget

(
  • [name]
)

获取依赖的控件

Parameters:

  • [name] String optional

    依赖控件名 scroll

Example:

       //获取依赖控件
                                                       var uiListScroll = uiList.widget("scroll");
                                                
                                                       //使用scroll的方法
                                                       uiListScroll.nextPage();
                                                

Events

off

Defined in src/scripts/ui/bui.list.js:1083

Available since 1.3.0

为控件取消绑定事件

Event Payload:

  • [type] String optional

    事件类型: "refreshbefore"(刷新前触发) | "refresh"(刷新后触发) | "success"(请求成功时触发) | "fail" (请求失败时触发) | "onloadbefore" | "onload"

  • [callback] Function optional

    绑定的事件, this 为当前点击的菜单

Example:

       uiListScroll.off("refresh");
                                                

on

Defined in src/scripts/ui/bui.list.js:1063

Available since 1.3.0

为控件绑定事件

Event Payload:

  • [type] String optional

    事件类型: "refreshbefore"(刷新前触发) | "refresh"(刷新后触发) | "success"(请求成功时触发) | "fail" (请求失败时触发) | "onload"

  • [callback] Function optional

    绑定的事件, this 为当前点击的菜单

Example:

       uiList.on("refresh",function () {
                                                           // 点击的菜单
                                                           console.log(this);
                                                       });