目录

Knockout分组列表控件

1.功能说明

支持数据列表功能的使用，列表可以是固定长度的列表也可以是不固定长度根据加载数据的多少来展示,支持上下拉加载数据，侧滑删除，长按和行点击。

列表对应的数据结构是二维JS数组，例如，下面的JSON结构：

var datas = [{
    'gname' : '游戏娱乐',
    'row' : [{
        'name' : '应用商店',
        'descri' : '这是一段关于应用的描述,可以点击进入查看详情',
        'img' : 'img/app_store.png'
    }]
}, {
    'gname' : '生活应用',
    'row' : [{
        'name' : '天气预报',
        'descri' : '这是一段关于应用的描述,可以点击进入查看详情',
        'img' : 'img/weather.png'
    }]
}];

2.HTML结构及图示

列表整体效果图如下：

列表每一行结构图示：

列表HTML结构如下：

<div class="um-listgroup-wrap" id="listgroup">
     <ul class="um-listgroup">
          <li class="um-listgroup-group">
               <a class="um-box-vc um-listgroup-title">
                    <span class="um-listgroup-icon">
                       <i class="ti-angle-down"></i>
                    </span>
                    <span>分组名称</span>
               </a>
               <ul class="um-list um-no-active">
                    <li class="um-listgroup-row">
                        <a href="#" class="um-list-item um-swipe-action">
                            <div class="um-swipe-btns">
                                <span class="um-swipe-btn um-delete">删除</span>
                                <！--此区域可自定义按钮，结构同上面删除按钮一样，其位置对应上图2.3的红色区域4-->
                            </div>
                            <div class="um-list-item-media">
                                 <!-- 此区域内容可自定义,其位置对应上图2.2的区域1，一般放置图片，单选框，复选框等等， -->
                            </div>
                            <div class="um-list-item-inner">
                               <div class="um-list-item-body">
                                  <!-- 此区域内容可自定义,其位置对应上图2.2的区域２，一般放置单行或多行文字 -->
                               </div>
                               <div class="um-list-item-right">
                                   <!-- 此区域可自定义,其位置对应上图2.2的区域３，一般放置次要内容，比如数字气泡，提示文字 -->
                               </div>
                            </div>
                          </a>
                      </li>
                  </ul>
             </li>
        </ul>
 </div>

3.控件初始化

 var listgroup = UM.listgroup(selector, opts);

其中UM.listgroup方法会根据列表控件的css选择器和相关配置对象opts,构造一个新的列表对象，并返回给变量listgroup(可自定义名字)，以第二节所示HTML结构为例，可用以下代码初始化控件：

var listgroup = UM.listgroup(‘#listgroup’, {});

opts配置对象支持属性如下(除非特殊说明，一般情况下配置对象属性的属性值不带单位)：

4.控件方法

为了阐述方便，下面的listgroup变量都表示经过UM.listgroup方法初始化之后的列表实例对象。

4.1 监听方法

4.1.1 itemclick(行点击)

调用示例：

listgroup.itemClick(function(sender, args){});
//等效于以下代码
listgroup.on(‘itemClick’,function(sender,args){});

参数说明：sender指代listgroup实例对象，args对象具有rowIndex（二维数组变为一维数组后的绝对行索引号）、childIndex(目标行所在分组的索引)、groupIndex(分组在整个列表的索引)、target（目标行DOM的jquery对象）

4.1.2 itemDelete(行删除）

调用示例：

listgroup.itemDelete(function(sender, args){});
//等效于以下代码
listgroup.on(‘itemDelete’,function(sender,args){});

参数说明：sender指代listgroup实例对象，args对象具有rowIndex（二维数组变为一维数组后的绝对行索引号）、childIndex(目标行所在分组的索引)、groupIndex(分组在整个列表的索引)、$target（目标行DOM的jquery对象）

4.1.3 itemSwipeLeft(行左滑)

调用示例：

listgroup.itemSwipeLeft(function(sender, args){});
//等效于以下代码
listgroup.on(‘itemSwipeLeft’,function(sender,args){});

参数说明：sender指代listgroup实例对象，args对象具有rowIndex（二维数组变为一维数组后的绝对行索引号）、childIndex(目标行所在分组的索引)、groupIndex(分组在整个列表的索引)、$target（目标行DOM的jquery对象）

4.1.4 itemSwipeRight(行右滑)

调用示例：

listgroup.itemSwipeRight(function(sender, args){});
//等效于以下代码
listgroup.on(‘itemSwipeRight’,function(sender,args){});

参数说明：sender指代listgroup实例对象，args对象具有rowIndex（二维数组变为一维数组后的绝对行索引号）、childIndex(目标行所在分组的索引)、groupIndex(分组在整个列表的索引)、$target（目标行DOM的jquery对象）

4.1.5 pullUp(上拉列表)

调用示例：

listgroup.pullUp(function(sender){});
//等效于以下代码
listgroup.on(‘pullUp’,function(sender){});

参数说明：sender指代listgroup实例对象

4.1.6 pullDown(下拉列表)

调用示例：

listgroup.pullDown(function(sender){});
//等效于以下代码
listgroup.on(‘pullDown’,function(sender){});

参数说明：sender指代listgroup实例对象

4.1.7 tapHold(长按列表)

调用示例：

listgroup.tapHold(function(sender){});
//等效于以下代码
listgroup.on(‘tapHold’,function(sender){});

参数说明：sender指代listgroup实例对象

4.1.8 on(监听列表事件)

调用示例：

listgroup.on(‘itemClick’,function(sender,args){}); //监听行点击
listgroup.on(‘tapHold’,function(sender){}); //监听列表长按

参数说明：sender指代listgroup实例对象

4.2 工具方法

4.2.1 showItemMenu(显示列表行菜单）

调用示例：

listgroup.showMenuItem($elem);

参数说明：请注意上面红色字体标注部分， $elem表示目标行DOM结构的jquery化后的对象

该方法通常与itemSwipeLeft方法一起使用,如下所示：

listgroup.itemSwipeLeft(function(sender, args){
    sender.showMenuItem(args.$target);
});

4.2.2 hideMenuItem(隐藏列表行菜单)

调用示例：

listgroup.hideMenuItem($elem);

参数说明：请注意上面红色字体标注部分， $elem表示目标行DOM结构的jquery化后的对象

该方法通常与itemSwipeRight方法一起使用,如下所示：

listgroup.itemSwipeRight(function(sender, args){
    sender.hideMenuItem(args.$target);
});

4.2.3 refresh(上下拉之后更新列表)

调用示例：

listgroup.refresh();

该方法通常与pullUp或者pullDown方法一起使用,如下所示：

listgroup.pullUp(function(sender){
    //这里书写自己的代码
    sender.refresh();
}); 
listgroup.pullDown(function(sender){
    //这里书写自己的代码
    sender.refresh();
});

5.一个完整示例

以下是一个完整的实例，ＤＯＭ结构使用KnockoutJS渲染，结构与本文第2节有差异的地方，就是多了几个绑定字段。假设json结构如下：

var datas = [{
    'gname' : '游戏娱乐',
    'row' : [{
        'name' : '应用商店',
        'descri' : '这是一段关于应用的描述,可以点击进入查看详情',
        'img' : 'img/app_store.png'
    }]
}, {
    'gname' : '生活应用',
    'row' : [{
        'name' : '天气预报',
        'descri' : '这是一段关于应用的描述,可以点击进入查看详情',
        'img' : 'img/weather.png'
    }]
}];

这是最终效果：

5.1 DOM结构

<div class="um-listgroup-wrap" id="listgroup">
    <ul class="um-listgroup" data-bind="foreach:datas">
        <li class="um-listgroup-group">
            <a class="um-box-vc um-listgroup-title"> <span class="um-listgroup-icon"> <i class="ti-angle-down"></i> </span> <span data-bind="text:gname"></span> </a>
            <ul class="um-list um-no-active" data-bind="foreach:row">
                <li class="um-listgroup-row">
                    <a href="#" class="um-list-item um-swipe-action">
                    <div class="um-swipe-btns">
                        <span class="um-swipe-btn">自定义</span>
                        <span class="um-swipe-btn um-delete">删除</span>
                    </div>
                    <div class="um-list-item-media">
                        <img alt="" width=50 data-bind="attr:{src: img}">
                    </div>
                    <div class="um-list-item-inner">
                        <div class="um-list-item-body">
                            <h4 data-bind="text:name" class="f16"></h4>
                            <p data-bind="text:descri" class="f14 um-text-overflow"></p>
                        </div>
                        <div class="um-list-item-right">
                            <span class="um-badge um-btn-success mr10">3</span>
                        </div>
                    </div> </a>
                </li>
            </ul>
        </li>
    </ul>
</div>

5.2 Knockout加载数据

var ViewModel = function (data) {
    var self = this;
    self.mailbox = ko.observableArray(datas);
};
var viewModel = new ViewModel(datas);
ko.applyBindings(viewModel);

注：data为第5.1节所示数据对象。

5.3 列表控件初始化

var listgroup = UM.listgroup('#listgroup'，{
    //此处可对照本文第3节设置配置对象属性
});

5.4 添加控件方法

listgroup.on('pullDown', function(sender) {
    var item = {
        'gname' : '新增类别',
        'row' : [{
            'name' : '应用名称一',
            'img' : 'img/app_default1.png',
            'descri' : '这是一段关于应用的描述'
        }, {
            'name' : '应用名称二',
            'img' : 'img/app_default2.png',
            'descri' : '这是一段关于应用的描述'
        }]
    };
    viewModel.datas.unshift(item);
    sender.refresh();
}).on('pullUp', function(sender) {
    var item = {
        'gname' : '新增类别',
        'row' : [{
            'name' : '应用名称一',
            'img' : 'img/app_default1.png',
            'descri' : '这是一段关于应用的描述'
        }, {
            'name' : '应用名称二',
            'img' : 'img/app_default2.png',
            'descri' : '这是一段关于应用的描述'
        }]
    };
    viewModel.datas.push(item);
    sender.refresh();
}).on('itemDelete', function(sender, args) {
    args.$target.slideUp(500, function() {
    });
}).on('itemClick', function(sender, args) {
    //console.log(args);
}).on('itemSwipeLeft', function(sender, args) {
    sender.showItemMenu(args.$target);
}).on('tapHold', function() {
    //console.log('yes');
});

至此一个完整的示例就实现了。