table模块/数据表格文档 - layui.table

table 模块是我们的又一走心之作,在 layui 2.0 的版本中全新推出,是 layui 最核心的组成之一。它用于对表格进行一些列功能和动态化数据操作,涵盖了日常业务所涉及的几乎全部需求。支持固定表头、固定行、固定列左/列右,支持拖拽改变列宽度,支持排序,支持多级表头,支持单元格的自定义模板,支持对表格重载(比如搜索、条件筛选等),支持复选框,支持分页,支持单元格编辑等等一些列功能。尽管如此,我们仍将对其进行完善,在控制代码量和性能的前提下,不定期增加更多人性化功能。table 模块也将是 layui 重点维护的项目之一。

模块加载名称:table

快速使用

创建一个table实例最简单的方式是,在页面给一个带有 class="layui-table"<table> 标签设好一些基本属性,一切都将自动完成,如下所示:

ID 用户名 性别 城市 签名 积分 评分 职业 财富

上面你已经看到了一个简单数据表格的基本样子,你一定迫不及待地想知道它的使用方式。鉴于你的猴急心态,我们还是直接看代码吧:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>table模块快速使用</title>
  <link rel="stylesheet" href="/static/build/layui.css" media="all">
</head>
<body>
 
<table class="layui-table" lay-data="{height:315, url:'/demo/table/user/', page:true, id:'test'}" lay-filter="test">
  <thead>
    <tr>
      <th lay-data="{field:'id', width:80, sort: true}">ID</th>
      <th lay-data="{field:'username', width:80}">用户名</th>
      <th lay-data="{field:'sex', width:80, sort: true}">性别</th>
      <th lay-data="{field:'city', width:80}">城市</th>
      <th lay-data="{field:'sign', width:177}">签名</th>
      <th lay-data="{field:'experience', width:80, sort: true}">积分</th>
      <th lay-data="{field:'score', width:80, sort: true}">评分</th>
      <th lay-data="{field:'classify', width:80}">职业</th>
      <th lay-data="{field:'wealth', width:135, sort: true}">财富</th>
    </tr>
  </thead>
</table>
 
<script src="/static/build/layui.js"></script>
<script>
layui.use('table', function(){
  var table = layui.table;
});
</script>
</body>
</html>

这是一种被广泛应用的方式,在实际测试中,也的确发现这样的方式非常高效。你仅仅只需关注数据接口和表头的各项配置,就能轻松呈现我们精心雕琢的动态表格了。你的牛刀是否早已饥渴难耐?那么不妨现在就去小试一波吧。数据接口可参考:返回的数据,规则在下文也有讲解。

三种初始化渲染方式

在上述“快速使用”的介绍中,你已经初步见证了 table 模块的信手拈来,但其使用方式并不止那一种。我们为了满足各种情况下的需求,对 table 模块做了三种初始化的支持,你可按照个人喜好和实际情况灵活使用。

方式 机制 适用场景
01. 自动化渲染 HTML配置,自动渲染 无需写JS,可专注于HTML表头部分
02. 方法级渲染 用JS方法的配置完成渲染 无需写HTML,在JS中指定原始元素,再设定各项参数即可
03. 转换静态表格 转化一段已有的表格元素 无需配置数据接口,在JS中指定表格元素,并简单地给表头加上自定义属性即可

下面逐一详细介绍。

自动化渲染

你在“快速使用”所看到的,即为我们所谓的表格“自动化渲染”,其特点在上文也有阐述。你需要关注的是以下三点:

1) 带有 class="layui-table"<table> 标签。
2) 对标签设置属性 lay-data="" 用于配置一些基础参数
3) 在 <th> 标签中设置属性lay-data=""用于配置表头信息

<table class="layui-table" lay-data="{基础参数,详见右侧目录:基础参数选项}" lay-filter="test">
  <thead>
    <tr>
      <th lay-data="{表头基础参数,详见右侧目录:设置表头}">标题</th>
      ……
    </tr>
  </thead>
</table>
    

按照上述的规范写好table原始容器后,只要你加载了layui 的 table 模块,就会自动对其建立动态的数据表格。

方法级渲染

其实这是“自动化渲染”的手动模式,本质类似,只是“方法级渲染”将基础参数的设定放在了JS代码中,且原始的table标签只需要一个 选择器

          
<table id="demo" lay-filter="test"></table>
    
var table = layui.table;
 
//执行渲染
table.render({
  elem: '#demo' //指定原始表格元素选择器(推荐id选择器)
  ,height: 315 //容器高度
  ,cols: [{}] //设置表头
  //,…… //更多参数参考右侧目录:基本参数选项
});
    

事实上我们更推荐采用“方法级渲染”的做法,其最大的优势在于你可以脱离HTML文件,而专注于JS本身。尤其对于项目的频繁改动及发布,其便捷性会体现得更为明显。而究竟它与“自动化渲染”的方式谁更简单,也只能由各位猿猿们自行体味了。

备注:table.render()方法返回一个对象:var tableIns = table.render(options),可用于对当前表格进行“重载”等操作,详见目录:表格重载

转换静态表格

假设你的页面已经存在了一段有内容的表格,它由原始的table标签组成,这时你需要赋予它一些动态元素,比如拖拽调整列宽?比如排序等等?那么你同样可以很轻松地去实现。如下所示:

昵称 积分 签名
贤心1 66 人生就像是一场修行a
贤心2 88 人生就像是一场修行b
贤心3 33 人生就像是一场修行c

通过上面的小例子,你已经初步见识了这一功能的实际意义。尝试在你的静态表格的 th 标签中加上 lay-data="" 属性,代码如下:

<table lay-filter="demo">
  <thead>
    <tr>
      <th lay-data="{field:'username', width:100}">昵称</th>
      <th lay-data="{field:'experience', width:80, sort:true}">积分</th>
      <th lay-data="{field:'sign', width:300}">签名</th>
    </tr> 
  </thead>
  <tbody>
    <tr>
      <td>贤心1</td>
      <td>66</td>
      <td>人生就像是一场修行a</td>
    </tr>
    <tr>
      <td>贤心2</td>
      <td>88</td>
      <td>人生就像是一场修行b</td>
    </tr>
    <tr>
      <td>贤心3</td>
      <td>33</td>
      <td>人生就像是一场修行c</td>
    </tr>
  </tbody>
</table>
    

然后执行用于转换表格的JS方法,就可以达到目的了:

var table = layui.table;
 
//转换静态表格
table.init('demo', {
  height: 315 //设置高度
  //支持所有基础参数
}); 
    

在前面的“自动化渲染”和“方法级渲染”两种方式中,你的数据都来源于异步的接口,这可能并不利于所谓的seo(当然是针对于前台页面)。而在这里,你的数据已和页面同步输出,却仍然可以转换成动态表格,是否感受到一丝惬意呢?

基础参数选项

这可能是整篇文档的主角,至少在右侧的目录中,它占据了如此多的面积。我们并不认为基础参数的数量越多就越好,所以合理的设计就显得格外重要了。如你所见,layui 的 table模块 在基础参数方面尽可能地做到友好,即:保证功能的前提而又避免过于繁杂的配置。基础参数一般出现在以下几种场景中:

场景一:下述 lay-data 里面的内容即为基础参数项,切记:值要用单引号
<table lay-data="{height:300, url:'/api/data'}" lay-filter="demo"> …… </table>
 
场景二:下述方法中的键值即为基础参数项
table.render({
  height: 300
  ,url: '/api/data'
});
 
更多场景:下述options即为含有基础参数项的对象
> table.init('filter', options); //转化静态表格
> var tableObj = table.render({});
  tableObj.reload(options); //重载表格
      

基础参数并非所有都要出现,有必选也有可选,结合你的实际需求,去自由设定吧。

elem - 绑定元素

类型:String/DOM,默认值:

指定原始table容器,只适用于 table.render()的渲染方式,如:

HTML:
<table id="test"></table>     
 
JS:
table.render({ //其它参数在此省略
  elem: '#test' //或 elem: document.getElementById('test') 等
});
      
cols - 设置表头

类型:Array,默认值:

值是一个二维数组。如果你采用表格的“方法级渲染”,那么你需要借助该参数来设定表格。如:

JS:
table.render({
  cols:  [[ //标题栏
    {checkbox: true}
    ,{field: 'id', title: 'ID', width: 80}
    ,{field: 'username', title: '用户名', width: 120}
  ]]
});
 
它等价于:
<table class="layui-table" lay-data="{基础参数}" lay-filter="test">
  <thead>
    <tr>
      <th lay-data="{checkbox:true}"></th>
      <th lay-data="{field:'id', width:80}">ID</th>
      <th lay-data="{field:'username', width:180}">用户名</th>
    </tr>
  </thead>
</table>
      

以下是一个二级表头的例子:

JS:
table.render({
  cols:  [[ //标题栏
    {field: 'username', title: '联系人', width: 80, rowspan: 2} //rowspan即纵向跨越的单元格数
    ,{field: 'amount', title: '金额', width: 80, rowspan: 2}
    ,{align: 'center', title: '地址', colspan: 3} //colspan即横跨的单元格数,这种情况下不用设置field和width
  ], [
    {field: 'province', title: '省', width: 80}
    ,{field: 'city', title: '市', width: 120}
    ,{field: 'county', title: '详细', width: 300}
  ]]
});
 
它等价于:
<table class="layui-table" lay-data="{基础参数}">
  <thead>
    <tr>
      <th lay-data="{field:'username', width:80}" rowspan="2">联系人</th>
      <th lay-data="{field:'amount', width:120}" rowspan="2">金额</th>
      <th lay-data="{align:'center'}" colspan="3">地址</th>
    </tr>
    <tr>
      <th lay-data="{field:'province', width:80}">省</th>
      <th lay-data="{field:'city', width:120}">市</th>
      <th lay-data="{field:'county', width:300}">详细</th>
    </tr>
  </thead>
</table>
      

需要说明的是,table模块支持无限极表头,你可按照上述的方式继续扩充。核心点在于 rowspancolspan 两个参数的使用。

field - 设定字段名

类型:String,默认值:

字段名的设定非常重要,且是表格数据列的唯一标识:

table.render({
  cols: [[
    {field: 'id'} //其它参数在此省略
    ,{field: 'username'}
  ]]
});
 
等价于:
<th lay-data="{field:'id'}"></th>
<th lay-data="{field:'username'}"></th>
      
title - 设定标题名称

类型:String,默认值:

即表头各列的标题

table.render({
  cols: [[
    {title: '邮箱'} //其它参数在此省略
    ,{title: '签名'}
  ]]
});
 
等价于:
<th lay-data="{}">邮箱</th> (PS:也可以把标题写在lay-data里面,即 title:'邮箱')
<th lay-data="{}">签名</th>
      
width - 设定列宽

类型:Number,默认值:50

列宽的设定也通常是必须的(“特殊列”除外,如:复选框列、工具列等),它关系到表格的整体美观程度。

table.render({
  cols: [[
    {width: 80} //其它参数在此省略
    ,{width: 120}
  ]]
});
 
等价于:
<th lay-data="{width:80}"></th>
<th lay-data="{width:120}"></th>
      
checkbox - 设定复选框列

类型:Boolean,默认值:false

如果设置 true,则表示该列内容为复选框,通常它被放在第一列。

table.render({
  cols: [[
    {checkbox: true} //其它参数在此省略
    ,{field: 'id', title:'ID', width: 100}
  ]]
});
 
等价于:
<th lay-data="{checkbox:true}"></th>
<th lay-data="{field:'id', width:100}">ID</th>
      
space - 设定空隙列

类型:Boolean,默认值:false

如果设置 true,则定义一个 15px 宽度无任何内容的列。

table.render({
  cols: [[ //其它参数在此省略
    {space: true}
    ,{field: 'id', title:'ID', width: 100}
  ]]
});
 
等价于:
<th lay-data="{space:true}"></th>
<th lay-data="{field:'id', width:100}">ID</th>
      
LAY_CHECKED - 设定复选框列

类型:Boolean,默认值:false

checkbox 参数搭配使用,如果设置 true,则表示复选框默认全部选中。

table.render({
  cols: [[
    {checkbox: true, LAY_CHECKED: true} //其它参数在此省略
    ,{field: 'id', title:'ID', width: 100}
  ]]
});
 
等价于:
<th lay-data="{checkbox:true, LAY_CHECKED: true}"></th>
<th lay-data="{field:'id', width:100}">ID</th>
      
sort - 是否允许排序

类型:Boolean,默认值:false
如果设置 true,则在对应的表头显示排序icon,从而对列开启排序功能。

注意:不推荐对值存在:数字和普通字符的列开启排序,因为会进入字典序比对。比如:'贤心' > '2' > '100',这可能并不是你想要的结果,但字典序排列算法(ASCII码比对)就是这样的,具体你也可以去了解一下字典序方面的知识。

table.render({
  cols: [[
    {sort:true} //其它参数在此省略
    ,{field:'id', title:'ID', width:100}
  ]]
});
 
等价于:
<th lay-data="{sort:true}"></th>
<th lay-data="{field:'id', width:100}">ID</th>
      
fixed - 是否固定列

类型:Boolean/String,默认值:false

如果设置 true'right',则对应的列将会被固定在左或右,不随滚动条而滚动。

table.render({
  cols: [[
    {fixed:true} //其它参数在此省略
    ,{field:'id', title:'ID', width:100}
    ,{field:'username', title:'姓名', width:120, fixed:'right'} //固定列在右
  ]]
});
 
等价于:
<th lay-data="{sort:true}"></th>
<th lay-data="{field:'id', width:100}">ID</th>
<th lay-data="{field:'username', width:120, fixed:'right'}">姓名</th>
      

备注:true等价于 'left',即固定在左的意思

edit - 是否允许编辑

类型:Boolean/String,默认值:false

如果设置 true,则对应列的单元格将会被允许编辑,目前只支持type="text"的input编辑。

table.render({
  cols: [[
    {edit:'text'} //其它参数在此省略
    ,{field:'id', title:'ID', width:100}
  ]]
});
 
等价于:
<th lay-data="{edit:'text'}"></th>
<th lay-data="{field:'id', width:100}">ID</th>
      
templet - 自定义模板

类型:String,默认值:

在默认情况下,单元格的内容是完全按照数据接口返回的content原样输出的,如果你想对某列的单元格添加链接等其它元素,你可以借助该参数来轻松实现。这是一个非常实用的功能,你的表格内容会因此而丰富多样。

table.render({
  cols: [[
    {field:'title', title: '文章标题', width: 200, templet: '#titleTpl'} //这里的templet值是模板元素的选择器
    ,{field:'id', title:'ID', width:100}
  ]]
});
 
等价于:
<th lay-data="{field:'title', width: 200, templet: '#titleTpl'}">文章标题</th>
<th lay-data="{field:'id', width:100}">ID</th>
      

下述是templet对应的模板,它可以存放在页面的任意位置。模板遵循于 laytpl 语法,可读取到返回的所有数据

<script type="text/html" id="titleTpl">
  <a href="/detail/{{d.id}}" class="layui-table-link">{{d.title}}</a>
</script>
注意:这里的 {{d.id}}、{{d.title}} 是动态内容,它对应数据接口返回的字段名
 
由于模板遵循 laytpl 语法(建议细读 laytpl文档 ),因此在模板中你可以写任意脚本语句(如 if else/for等):
<script type="text/html" id="titleTpl">
  {{#  if(d.id < 100){ }}
    <a href="/detail/{{d.id}}" class="layui-table-link">{{d.title}}</a>
  {{#  } else { }}
    {{d.title}}(普通用户)
  {{#  } }}
</script>
      

事实上,templet也可以直接是一段html内容,如:

       
templet: '<div><a href="/detail/{{d.id}}" class="layui-table-link">{{d.title}}</a></div>'
 
注意:这里一定要被一层 <div></div> 包裹,否则无法读取到模板
      
toolbar - 绑定工具条

类型:String,默认值:

通常你需要在表格的每一行加上 查看编辑删除 这样类似的操作按钮,而 tool 参数就是为此而生,你因此可以非常便捷地实现各种操作功能。tool 参数和 templet 参数的使用方式完全类似,通常接受的是一个选择器,也可以是一段HTML字符。

table.render({
  cols: [[
    {field:'id', title:'ID', width:100}
    ,{fixed: 'right', width:150, align:'center', toolbar: '#barDemo'} //这里的toolbar值是模板元素的选择器
  ]]
});
 
等价于:
<th lay-data="{field:'id', width:100}">ID</th>
<th lay-data="{fixed: 'right', width:150, align:'center', toolbar: '#barDemo'}"></th>
      

下述是 toolbar 对应的模板,它可以存放在页面的任意位置:

<script type="text/html" id="barDemo">
  <a class="layui-btn layui-btn-mini" lay-event="detail">查看</a>
  <a class="layui-btn layui-btn-mini" lay-event="edit">编辑</a>
  <a class="layui-btn layui-btn-danger layui-btn-mini" lay-event="del">删除</a>
  
  <!-- 这里同样支持 laytpl 语法,如: -->
  {{#  if(d.auth > 2){ }}
    <a class="layui-btn layui-btn-mini" lay-event="check">审核</a>
  {{#  } }}
</script>
 
注意:属性 lay-event="" 是模板的关键所在,值可随意定义。
      

接下来我们可以借助 table模块的工具条事件,完成不同的操作功能:

//监听工具条
table.on('tool(test)', function(obj){ //注:tool是工具条事件名,test是table原始容器的属性 lay-filter="对应的值"
  var data = obj.data; //获得当前行数据
  var layEvent = obj.event; //获得 lay-event 对应的值
  var tr = obj.tr; //获得当前行 tr 的DOM对象
 
  if(layEvent === 'detail'){ //查看
    //do somehing
  } else if(layEvent === 'del'){ //删除
    layer.confirm('真的删除行么', function(index){
      obj.del(); //删除对应行(tr)的DOM结构,并更新缓存
      layer.close(index);
      //向服务端发送删除指令
    });
  } else if(layEvent === 'edit'){ //编辑
    //do something
    
    //同步更新缓存对应的值
    obj.update({
      username: '123'
      ,title: 'xxx'
    });
  }
});
      
异步数据接口

数据的异步请求由以下几个参数组成:

参数名 功能
url 接口地址。默认会自动传递两个参数:?page=1&limit=30(该参数可通过 request 自定义)
page 代表当前页码、limit 代表每页数据量
method 接口http请求类型,默认:get
where 接口的其它参数。如:where: {token: 'sasasas', id: 123}
request 用于对分页请求的参数:page、limit重新设定名称,如:
request: {
  pageName: 'curr' //页码的参数名称,默认:page
  ,limitName: 'nums' //每页数据量的参数名,默认:limit
}              
              
那么请求数据时的参数将会变为:?curr=1&nums=30
response 用于对返回的数据格式的自定义,如:
response: {
  statusName: 'status' //数据状态的字段名称,默认:code
  ,statusCode: 200 //成功的状态码,默认:0
  ,msgName: 'hint' //状态信息的字段名称,默认:msg
  ,countName: 'total' //数据总数的字段名称,默认:count
  ,dataName: 'rows' //数据列表的字段名称,默认:data
}      
              
你接口返回的数据格式,比如遵循 response 对应的字段名称。比如上面对应的格式为:
{
  status: 200,
  hint: "",
  total: 1000,
  rows: []
} 
              
下面是默认接受的数据格式:
{
  code: 0,
  msg: "",
  count: 1000,
  data: []
} 
              

接口参考:/demo/table/user/

注意:request 和 response 参数均为 layui 2.1.0 版本新增

调用示例:

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  url: '/api/data/'
  //where: {token: 'sasasas', id: 123} //如果无需传递额外参数,可不加该参数
  //method: 'post' //如果无需自定义HTTP类型,可不加该参数
  //request: {} //如果无需自定义请求参数,可不加该参数
  //response: {} //如果无需自定义数据响应名称,可不加该参数
}); 
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{url:'/api/data/'}" lay-filter="test"> …… </table>
      
done - 数据渲染完的回调

类型:Function,默认值:

无论是异步请求数据,还是直接赋值数据,都会触发该回调。你可以利用该回调做一些表格以外元素的渲染。

table.render({ //其它参数在此省略
  done: function(res, curr, count){
    //如果是异步请求数据方式,res即为你接口返回的信息。
    //如果是直接赋值的方式,res即为:{data: [], count: 99} data为当前页数据、count为数据总长度
    console.log(res);
    
    //得到当前页码
    console.log(curr); 
    
    //得到数据总量
    console.log(count);
  }
});
      
data - 直接赋值数据

类型:Array,默认值:

你也可以对表格直接赋值,而无需配置异步数据请求接口。他既适用于只展示一页数据,也非常适用于对一段已知数据进行多页展示。

table.render({ //其它参数在此省略
  data: [{}, {}, {}, {}, …] //赋值数据
  ,page: true //开启分页
});
      
initSort - 初始排序

类型:Object,默认值:

用于在数据表格渲染完毕时,默认按某个字段排序。注:该参数为 layui 2.1.1 新增

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  initSort: {
    field: 'id' //排序字段,对应 cols 设定的各字段名
    ,type: 'desc' //排序方式  asc: 升序、desc: 降序、null: 默认排序
  }
});
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{initSort:{field:'id', type:'desc'}}" lay-filter="test"> …… </table>
      
page - 是否开启分页

类型:Boolean,默认值:false

如果设置 true,则会出现表格的分页组件。

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  page: true
});
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{page:true}" lay-filter="test"> …… </table>
      
limits - 每页数据量可选项

类型:Array,默认值:[10,20,30,40,50,70,80,90]

你可以任意自定义每页展示多少数据量的选项,譬如:

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  limits: [30,60,90,150,300]
  ,limit: 60 //默认采用60
});
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{limits:[30,60,90,150,300], limit:60}" lay-filter="test"> …… </table>
      
loading - 是否显示加载条

类型:Boolean,默认值:true

如果设置 false,则在切换分页时,不会出现加载条。该参数只适用于“异步数据请求”的方式(即设置了url的情况下)

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  loading: false
});
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{loading:false}" lay-filter="test"> …… </table>
      
id - 设定容器唯一ID

类型:String,默认值:

该参数在对表格的数据操作方法上是必要的传递条件,它是表格容器的索引。

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  id: 'idTest'
});
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{id:'idTest'}" lay-filter="test"> …… </table>
      

在以下方法中会用到它(后文也有详细介绍):

//获取表格选中行
var checkStatus = table.checkStatus('idTest'); //test即为基础参数id对应的值
 
//表格重载
table.reload('idTest', options);
      
width - 设定容器宽度

类型:Number,默认值:'auto'

table容器的默认宽度是 auto,你可以借助该参数设置一个固定值,当容器中的内容超出了该宽度时,会自动出现横向滚动条。

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  width: 1000
}); 
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{width:1000}" lay-filter="test"> …… </table>
      
height - 设定容器高度

类型:Number/String,可选值如下:

可选值 说明 示例
auto 默认值,高度随数据列表而适应,表格容器不会出现纵向滚动条 -
固定值 设定一个数字,用于定义容器高度,当容器中的内容超出了该高度时,会自动出现纵向滚动条 height: 315
full-差值 高度将始终铺满,无论浏览器尺寸如何。这是一个特定的语法格式,其中 full 是固定的,而 差值 则是一个数值,这需要你来预估,比如:表格容器距离浏览器顶部和底部的距离“和”
PS:该功能为 layui 2.1.0 版本中新增
height: 'full-20'

示例:

//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  height: 315 //固定值
}); 
table.render({ //其它参数在此省略
  height: 'full-20' //高度最大化减去差值
}); 
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{height:315}" lay-filter="test"> …… </table>
<table class="layui-table" lay-data="{height:'full-20'}" lay-filter="test"> …… </table>
      
设定表格外观

控制表格外观的主要由以下参数组成:

参数名 可选值 备注
skin line (行边框风格)
row (列边框风格)
nob (无边框风格)
用于设定表格风格,若使用默认风格不设置该属性即可
even true/false 若不开启隔行背景,不设置该参数即可
size sm (小尺寸)
lg (大尺寸)
用于设定表格尺寸,若使用默认尺寸不设置该属性即可
//“方法级渲染”配置方式
table.render({ //其它参数在此省略
  skin: 'line' //行边框风格
  ,even: true //开启隔行背景
  ,size: 'sm' //小尺寸的表格
}); 
 
等价于(“自动化渲染”配置方式)
<table class="layui-table" lay-data="{skin:'line', even:true, size:'sm'}" lay-filter="test"> …… </table>
      
基础方法

基础用法是table模块的关键组成部分,目前所开放的所有方法如下:

> table.set(options); //设定全局默认参数。options即各项基础参数
> table.on('event(filter)', callback); //事件监听。event为内置事件名(详见下文),filter为容器lay-filter设定的值
> table.init(filter, options); //filter为容器lay-filter设定的值,options即各项基础参数。例子见:转换静态表格
> table.checkStatus(id); //获取表格选中行(下文会有详细介绍)。id即为id参数对应的值
> table.render(options); //用于表格方法级渲染,核心方法。应该不用再过多解释了,详见:方法级渲染
      
获取选中行

该方法可获取到表格所有的选中行相关数据
语法:table.checkStatus('idTest') test为基础参数id对应的值(见:设定容器唯一ID),如:

【自动化渲染】
<table class="layui-table" lay-data="{id: 'idTest'}"> …… </table>
 
【方法渲染】
table.render({ //其它参数省略
  id: 'idTest'
});
      
var checkStatus = table.checkStatus('idTest'); //test即为基础参数id对应的值
 
console.log(checkStatus.data) //获取选中行的数据
console.log(checkStatus.data.length) //获取选中行数量,可作为是否有选中行的条件
console.log(checkStatus.isAll ) //表格是否全选
      
事件监听

语法:table.on('event(filter)', callback); 注:event为内置事件名,filter为容器lay-filter设定的值
table模块在Layui事件机制中注册了专属事件,如果你使用layui.onevent()自定义模块事件,请勿占用table名。目前所支持的所有事件见下文

默认情况下,事件所监听的是全部的table模块容器,但如果你只想监听某一个容器,使用事件过滤器即可。
假设原始容器为:<table class="layui-table" lay-filter="test"></table> 那么你的事件监听写法如下:

//以复选框事件为例
table.on('checkbox(test)', function(obj){
  console.log(obj)
});
      
监听复选框选择

点击复选框时触发,回调函数返回一个object参数,携带的成员如下:

table.on('checkbox(test)', function(obj){
  console.log(obj.checked); //当前是否选中状态
  console.log(obj.data); //选中行的相关数据
  console.log(obj.type); //如果触发的是全选,则为:all,如果触发的是单选,则为:one
});
      
监听单元格编辑

单元格被编辑,且值发生改变时触发,回调函数返回一个object参数,携带的成员如下:

table.on('edit(test)', function(obj){ //注:tool是工具条事件名,test是table原始容器的属性 lay-filter="对应的值"
  console.log(obj.value); //得到修改后的值
  console.log(obj.field); //当前编辑的字段名
  console.log(obj.data); //所在行的所有相关数据  
  
  data[field] = value; //更新缓存中的值
});
      
监听工具条点击

具体用法见:绑定工具条

监听排序切换

点击表头排序时触发,回调函数返回一个object参数,携带的成员如下:

table.on('sort(test)', function(obj){ //注:tool是工具条事件名,test是table原始容器的属性 lay-filter="对应的值"
  console.log(obj.field); //当前排序的字段名
  console.log(obj.type); //当前排序类型:desc(降序)、asc(升序)、null(空对象,默认排序)
  console.log(this); //当前排序的 th 对象
  
  //尽管我们的 table 自带排序功能,但并没有请求服务端。
  //有些时候,你可能需要根据当前排序的字段,重新向服务端发送请求,如:
  table.reload('idTest', {
    initSort: obj //记录初始排序,如果不设的话,将无法标记表头的排序状态。 layui 2.1.1 新增参数
    ,where: { //请求参数
      field: obj.field //排序字段
      ,order: obj.type //排序方式
    }
  });
});
      
表格重载

很多时候,你需要对表格进行重载。比如数据全局搜索。以下方法可以帮你轻松实现这类需求(可任选一种)。

语法 说明 适用场景
table.reload(ID, options) 参数 ID 即为基础参数id对应的值,见:设定容器唯一ID
参数 options 即为各项基础参数
注意:该方法为 2.1.0 版本中新增
所有渲染方式
tableIns.reload(options) 对象 tableIns 来源于 table.render() 方法的实例
参数 options 即为各项基础参数
仅限方法级渲染
【HTML】
<table class="layui-table" lay-data="{id: 'idTest'}"> …… </table>
 
【JS】
table.reload('idTest', {
  url: '/api/table/search'
  ,where: {} //设定异步数据接口的额外参数
  //,height: 300
});
      
//所获得的 tableIns 即为当前容器的实例
var tableIns = table.render({
  elem: '#id'
  ,clos: [] //设置表头
  ,url: '/api/data' //设置异步接口
  ,id: 'idTest'
}); 
 
//这里以搜索为例
tableIns.reload({
  where: { //设定异步数据接口的额外参数,任意设
    aaaaaa: 'xxx'
    ,bbb: 'yyy'
    //…
  }
});
//上述方法等价于
table.reload('idTest', {
  where: { //设定异步数据接口的额外参数,任意设
    aaaaaa: 'xxx'
    ,bbb: 'yyy'
    //…
  }
});
      

注意:这里的表格重载是指对表格重新进行渲染,包括数据请求和基础参数的读取

结语

这是一篇耗费5天5夜完成的文档,其内容的用心程度堪称 layui 的所有模块之最。为了迎合layui开箱即用的理念,我们所做的工作并不是那么轻松。准确地说是信仰支撑了这一切,无论这事在他人看来是否屑于或者不屑于,我们始终毅然坚持。因为,这总有它的价值!

Layui - 用心与你沟通