table 数据表格文档 - layui.table

table 是 layui 中使用频率非常高的一个组件，用于在表格中对数据进行一系列动态化的操作，涵盖了日常业务所涉及的大部分需求

模块加载名称：table

上面你已经看到了一个简单数据表格的基本样子，你一定迫不及待地想知道它的使用方式：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>table 模块快速使用</title>
  <link rel="stylesheet" href="/layui/css/layui.css" media="all">
</head>
<body>
 
<table id="demo" lay-filter="test"></table>
 
<script src="/layui/layui.js"></script>
<script>
layui.use('table', function(){
  var table = layui.table;
  
  //第一个实例
  table.render({
    elem: '#demo'
    ,height: 312
    ,url: '/static/json/table/user.json' //数据接口
    ,page: true //开启分页
    ,cols: [[ //表头
      {field: 'id', title: 'ID', width:80, sort: true, fixed: 'left'}
      ,{field: 'username', title: '用户名', width:80}
      ,{field: 'sex', title: '性别', width:80, sort: true}
      ,{field: 'city', title: '城市', width:80} 
      ,{field: 'sign', title: '签名', width: 177}
      ,{field: 'experience', title: '积分', width: 80, sort: true}
      ,{field: 'score', title: '评分', width: 80, sort: true}
      ,{field: 'classify', title: '职业', width: 80}
      ,{field: 'words', title: '字数', width: 135, sort: true}
    ]]
  });
  
});
</script>
</body>
</html>

配置好对应选项后，layui 将自动完成渲染。其中数据格式可参考：返回的数据，规则在下文也有详细讲解。

渲染方式

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

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

方法渲染

其实这是“自动化渲染”的手动模式，本质类似，只是“方法级渲染”将基础参数的设定放在了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 容器中配置好相应的参数，由 table 模块内部自动对其完成渲染，而无需你写初始的渲染方法。其特点在上文也有阐述。你需要关注的是以下三点：

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

按照上述的规范写好table原始容器后，只要你加载了layui 的 table 模块，就会自动对其建立动态的数据表格。下面是一个示例：

<table class="layui-table" lay-data="{height:315, url:'/2.7/static/json/table/user.json', 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'}">城市</th>
      <th lay-data="{field:'sign'}">签名</th>
      <th lay-data="{field:'experience', sort: true}">积分</th>
      <th lay-data="{field:'score', sort: true}">评分</th>
      <th lay-data="{field:'classify'}">职业</th>
      <th lay-data="{field:'words', sort: true}">字数</th>
    </tr>
  </thead>
</table>

转换静态表格

假设你的页面已经存在了一段有内容的表格，它由原始的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'}">签名</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 //设置高度
  ,limit: 10 //注意：请务必确保 limit 参数（默认：10）是与你服务端限定的数据条数一致
  //支持所有基础参数
});

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

基础参数

基础参数选项可结合你的实际需求自由设定：

// options 即为基础参数项，它是一个 object 类型
table.render(options); // 方法渲染
table.reload(id, options); // 重载
       
若为静态渲染，则 lay-data 里面的内容即为基础参数项（值要用单引号）：
<table lay-data="{url:''}"> … </table>

下面是目前 table 模块所支持的全部基础参数项一览表：

参数	类型	说明	默认 / 用法
elem	String/DOM	指定原始 table 容器的选择器或 DOM，方法渲染方式必填	-
cols	Array	设置表头。值是一个二维数组。方法渲染方式必填	详见表头参数
url（系列）	-	异步数据接口相关参数。其中 url 参数为必填项	详见异步参数
data	Array	直接赋值数据。既适用于只展示一页数据，也能对一段已知数据进行多页展示。注：该参数与 url 参数只能二选一	null
id	String	设定容器唯一 id。id 是对表格的数据操作方法上是必要的传递条件，它是表格示例的重要索引，许多 API 都会用到它。若该参数未设置，则默认从 <table id="test"></table> 中的 id 属性值中获取。	-
toolbar	String/DOM/Boolean	开启表格头部工具栏区域，该参数支持四种类型值： toolbar: '#toolbarDemo' //指向自定义工具栏模板选择器 toolbar: '<div>xxx</div>' //直接传入工具栏模板字符 toolbar: true //仅开启工具栏，不显示左侧模板 toolbar: 'default' //让工具栏左侧显示默认的内置模板	false
defaultToolbar	Array	该参数可自由配置头部工具栏右侧的图标按钮	详见头工具栏图标
width	Number	设定容器宽度。table容器的默认宽度是跟随它的父元素铺满，你也可以设定一个固定值，当容器中的内容超出了该宽度时，会自动出现横向滚动条。	auto
height	Number/String	设定容器高度	详见 height
cellMinWidth	Number	全局定义所有常规单元格的最小宽度，一般用于列宽自动分配的情况。其优先级低于表头参数中的 minWidth	60
lineStyle	String	用于定义表格的多行样式，如每行的高度等。该参数一旦设置，单元格将会开启多行模式，且鼠标 hover 时会通过显示滚动条的方式查看到更多内容。请按实际场景使用。示例：`lineStyle: 'height: 95px;'` 注：v2.7.0 新增	-
className	String	用于给表格主容器追加 css 类名，以便更好地扩展表格样式注：v2.7.0 新增	-
css	String	用于给当前表格主容器直接设定 css 样式，样式值只会对所在容器有效，不会影响其他表格实例。如： `css: '.layui-table-page{text-align: right;}'` 注：v2.7.0 新增	-
escape	Boolean	是否开启对内容的编码（转义 html）。注：v2.6.8 新增注：从 v2.6.11 开始，默认开启。	true
totalRow	Boolean/String	是否开启合计行区域	false
page	Boolean/Object	开启分页。支持传入一个对象，里面可包含 laypage 组件所有支持的参数（jump、elem 除外）	false
pagebar	String/DOM	用于开启分页区域的自定义模板，用法同 toolbar 注：v2.7.0 新增	-
limit	Number	每页显示的条数。值需对应 limits 参数的选项。注意：优先级低于 page 参数中的 limit 参数	10
limits	Array	每页条数的选择项。注意：优先级低于 page 参数中的 limits 参数	[10,…,90]
loading	Boolean	是否显示加载条。若为 false，则在切换分页时，不会出现加载条。该参数只适用于 url 参数开启的方式	true
scrollPos	String	用于设定重载数据或切换分页时的滚动条的位置状态。可选值如下： scrollPos: 'fixed' //重载数据时，保持滚动条位置不变 scrollPos: 'reset' //重载数据时，滚动条位置恢复置顶若采用默认方式（即重载数据或切换分页时，纵向滚动条恢复置顶，横向滚动条位置不变），则无需设置改参数注：v2.7.3 新增	-
editTrigger	String	是用于设定单元格编辑的事件触发方式。如双击：dblclick 注：v2.7.0 新增	click
title	String	定义 table 的大标题（在文件导出等地方会用到）	-
text	Object	自定义文本，如空数据时的异常提示等。	详见自定义文本
autoSort	Boolean	默认 true，即直接由 table 组件在前端自动处理排序。若为 false，则需自主排序，即由服务端返回排序好的数据	详见事件排序
initSort	Object	初始排序状态。用于在数据表格渲染完毕时，默认按某个字段排序。	详见初始排序
skin（系列）	-	设定表格各种外观、尺寸等	详见表格风格
before	Function	数据拉取之前的回调。注：v2.7.3 新增	-
done	Function	数据渲染完毕的回调。可借此做一些其它操作	详见 done 回调
error	Function	数据请求失败的回调，返回两个参数：错误对象、内容注：v2.6.0 新增	-

cols - 表头参数一览表

相信我，在你还尚无法驾驭 layui table 的时候，你的所有焦点都应放在这里，它带引领你完成许多可见和不可见甚至你无法想象的工作。如果你采用的是方法渲染，cols 是一个二维数组，表头参数设定在数组内；如果你采用的自动渲染，表头参数的设定应放在 <th> 标签上

参数	类型	说明	默认 / 用法
field	String	设定字段名。非常重要，且是表格数据列的唯一标识	field: '昵称'
title	String	设定标题名称	title: 'nickname'
width	Number/String	设定列宽，若不填写，则自动分配；若填写，则支持值为：数字、百分比。请结合实际情况，对不同列做不同设定。	width: 200 width: '30%'
minWidth	Number	局部定义当前常规单元格的最小宽度，一般用于列宽自动分配的情况。其优先级高于基础参数中的 cellMinWidth	60
type	String	设定列类型。可选值有： normal（常规列，无需设定） checkbox（复选框列） radio（单选框列） numbers（序号列） space（空列）	-
LAY_CHECKED	Boolean	是否全选状态（。必须复选框列开启后才有效，如果设置 true，则表示复选框默认全部选中。	false
fixed	String	固定列。可选值有：left（固定在左）、right（固定在右）。一旦设定，对应的列将会被固定在左或右，不随滚动条而滚动。注意：如果是固定在左，该列必须放在表头最前面；如果是固定在右，该列必须放在表头最后面。	-
hide	Boolean	是否初始隐藏列	false
escape	Boolean	当前列是否开启编码（转义 html），优先级大于基础参数项。注：v2.7.5 新增	true

totalRow	Boolean/String	是否开启该列的自动合计功能，默认：false。当开启时，则默认由前端自动合计当前行数据。从 layui 2.5.6 开始：若接口直接返回了合计行数据，则优先读取接口合计行数据，格式如下： { "code": 0, "totalRow": { "score": "777" ,"experience": "999" }, "data": [{}, {}], "msg": "", "count": 1000 } 如上，在 totalRow 中返回所需统计的列字段名和值即可。另外，totalRow 字段同样可以通过 parseData 回调来解析成为 table 组件所规定的数据格式。从 layui 2.6.3 开始，如果 totalRow 为一个 string 类型，则可解析为合计行的动态模板，如： totalRow: '{{= d.TOTAL_NUMS }} 单位' //还比如只取整：'{{= parseInt(d.TOTAL_NUMS) }}'	true

sort	Boolean	是否允许排序。如果设置 true，则在对应的表头显示排序icon，从而对列开启排序功能。注意：不推荐对值同时存在“数字和普通字符”的列开启排序，因为会进入字典序比对。比如：'张三' > '2' > '100'，这可能并不是你想要的结果，但字典序排列算法（ASCII码比对）就是如此。	false
unresize	Boolean	是否禁用拖拽列宽。默认情况下会根据列类型（type）来决定是否禁用，如复选框列，会自动禁用。而其它普通列，默认允许拖拽列宽，当然你也可以设置 true 来禁用该功能。	false
edit	String	单元格开启编辑的方式（默认不开启），支持的值有： text（单行输入框） textarea（多行输入框）注：v2.7.0 新增	-
event	String	自定义单元格点击事件名，以便在 tool 事件中完成对该单元格的业务处理	-
style	String	自定义单元格样式。即传入任意的 CSS 字符
align	String	单元格排列方式。可选值有：left、center、right	left
colspan	Number	单元格所占列数。一般用于多级表头	1
rowspan	Number	单元格所占行数。一般用于多级表头	1
templet	String/Function	自定义列模板，模板遵循 laytpl 语法。这是一个非常实用的功能，你可借助它实现逻辑处理，以及将原始数据转化成其它格式，如时间戳转化为日期字符等	详见自定义模板
exportTemplet	String/Function	专用于表格导出时的内容输出。当上述 templet 较复杂时建议使用，如下以模板存在 select 元素为例： exportTemplet: function(d, obj){ //当前 td var td = obj.td(this.field); //返回 select 选中值 return td.find('select').val(); } 表格导出时，将优先以对应表头的 exportTemplet 的返回内容为导出结果。注：v2.6.9 新增	用法同 templet
toolbar	String/Function	绑定行工具模板。用法同 templet 参数完全相同（因为历史兼容问题所以保留）。可在每行对应的列中出现一些自定义的操作性按钮	-

下面是一些方法渲染和自动渲染的配置方式：

//方法渲染：
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 组件支持无限极表头，你可按照上述的方式继续扩充。核心点在于 rowspan 和 colspan 两个参数的使用。

templet - 自定义列模板

类型：String，默认值：无

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

templet 提供了三种使用方式，请结合实际场景选择最合适的一种：

如果自定义模版的字符量太大，我们推荐你采用【方式一】；

如果自定义模板的字符量适中，或者想更方便地调用外部方法，我们推荐你采用【方式二】；

如果自定义模板的字符量很小，我们推荐你采用【方式三】

方式一：绑定模版选择器。

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}} 是动态输出语句，它对应数据接口返回的字段名。
除此之外，你还可以读取到以下额外字段：
     序号：{{= d.LAY_INDEX }} 
     当前列的表头信息：{{= d.LAY_COL }} （layui 2.6.8 新增）
 
由于模板遵循 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 若未函数，则返回一个参数 d（包含当前行数据及特定的额外字段）。如下所示：

table.render({
  cols: [[
    {field:'title', title: '文章标题', width: 200
      ,templet: function(d){
        console.log(d); // 得到当前行数据
        console.log(this); // 得到表头当前列配置项
        console.log(d.LAY_INDEX); //得到序号。一般不常用
        console.log(d.LAY_COL); //得到表头当前列配置项，同 this
        
        //得到当前行数据，并拼接成自定义模板
        return 'ID：'+ d.id +'，标题：<span style="color: #c00;">'+ d.title +'</span>'
      }
    }
    ,{field:'id', title:'ID', width:100}
  ]]
});

方式三：直接赋值模版字符。事实上，templet 也可以直接是一段 html 内容，如：

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

基础参数 - 异步参数系列

表格数据的异步请求由以下基础参数组成：

参数名	功能
url	接口地址。默认会自动传递两个参数：?page=1&limit=30（该参数可通过 request 自定义） page 代表当前页码、limit 代表每页数据量
method	接口http请求类型，默认：get
where	接口的其它参数。如：where: {token: 'sasasas', id: 123}
contentType	发送到服务端的内容编码类型。如果你要发送 json 内容，可以设置：contentType: 'application/json'
dataType	用于设定数据的请求类型。默认：json 。注：v2.7.3 新增
jsonpCallback	用于设定当 dataType 为 jsonp 时的回调函数名。注：v2.7.3 新增
headers	接口的请求头。如：headers: {token: 'sasasas'}

parseData	数据格式解析的回调函数，用于将返回的任意数据格式解析成 table 组件规定的数据格式。 table 组件默认规定的数据格式为： { "code": 0, "msg": "", "count": 1000, "data": [{}, {}] } 很多时候，您接口返回的数据格式并不一定都符合 table 默认规定的格式，比如： { "status": 0, "message": "", "total": 180, "data": { "item": [{}, {}] } } 那么你需要借助 parseData 回调函数将其解析成 table 组件所规定的数据格式 table.render({ elem: '#demp' ,url: '' ,parseData: function(res){ //res 即为原始返回的数据 return { "code": res.status, //解析接口状态 "msg": res.message, //解析提示文本 "count": res.total, //解析数据长度 "data": res.data.item //解析数据列表 }; } //,…… //其他参数 }); 该函数非常实用
request	用于对分页请求的参数：page、limit重新设定名称，如： table.render({ elem: '#demp' ,url: '' ,request: { pageName: 'curr' //页码的参数名称，默认：page ,limitName: 'nums' //每页数据量的参数名，默认：limit } //,…… //其他参数 }); 那么请求数据时的参数将会变为：?curr=1&nums=30
response	您还可以借助 response 参数来重新设定返回的数据格式，如： table.render({ elem: '#demp' ,url: '' ,response: { statusName: 'status' //规定数据状态的字段名称，默认：code ,statusCode: 200 //规定成功的状态码，默认：0 ,msgName: 'hint' //规定状态信息的字段名称，默认：msg ,countName: 'total' //规定数据总数的字段名称，默认：count ,dataName: 'rows' //规定数据列表的字段名称，默认：data } //,…… //其他参数 }); 那么上面所规定的格式为： { "status": 200, "hint": "", "total": 1000, "rows": [] }

返回数据中的特定字段

在返回的数据中，你还可以传入某些特定字段，以便 table 组件进行相应的特定解析。

LAY_CHECKED: 该行数据初始选中
LAY_DISABLED: 该行数据禁止选择    
 
示例：
{
  "code": 0,
  "count": 1000,
  "data": [{},{
    LAY_DISABLED: true
  }]
}

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);
  }
});

defaultToolbar - 头部工具栏右侧图标

类型：Array，默认值：["filter","exports","print"]

该参数可自由配置头部工具栏右侧的图标按钮，值为一个数组，支持以下可选值：

filter: 显示筛选图标
exports: 显示导出图标
print: 显示打印图标

可根据值的顺序显示排版图标，如：
defaultToolbar: ['filter', 'print', 'exports']

另外你还可以无限扩展图标按钮：

table.render({ //其它参数在此省略      
  defaultToolbar: ['filter', 'print', 'exports', {
    title: '提示' //标题
    ,layEvent: 'LAYTABLE_TIPS' //事件名，用于 toolbar 事件中使用
    ,icon: 'layui-icon-tips' //图标类名
  }]
});

扩展的图标可通过 toolbar 事件回调（详见单元格工具事件），其中 layEvent 的值会在事件的回调参数中返回，以便区分不同的触发动作。

text - 自定义文本

类型：Object

table 模块会内置一些默认的文本信息，如果想修改，你可以设置以下参数达到目的。

table.render({ //其它参数在此省略
  text: {
    none: '暂无相关数据' //默认：无数据。
  }
});

initSort - 初始排序

类型：Object，默认值：无

用于在数据表格渲染完毕时，默认按某个字段排序。

//“方法级渲染”配置方式
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>

height - 设定容器高度

类型：Number/String，可选值如下：

可选值	说明	示例
不填写	默认情况。高度随数据列表而适应，表格容器不会出现纵向滚动条	-
固定值	设定一个数字，用于定义容器高度，当容器中的内容超出了该高度时，会自动出现纵向滚动条	height: 315
full-差值	高度将始终铺满，无论浏览器尺寸如何。这是一个特定的语法格式，其中 full 是固定的，而差值则是一个数值，这需要你来预估，比如：表格容器距离浏览器顶部和底部的距离“和”	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>

基础 API

目前 table 组件的所有 API 如下：

var table = layui.table; // 获得 table 模块对象
 
table.set(options); //设定全局默认参数。options 即基础参数项
table.render(options); //用于表格方法级渲染，核心方法。详见：方法级渲染
table.init(filter, options); // filter 为容器 lay-filter 设定的值。 详见：转换静态表格
table.on('event(filter)', callback); //事件。event 为内置事件名（详见下文），filter 同上
table.reload(id, options, deep); //完整重载
table.reloadData(id, options, deep); //仅重载数据，跟数据无关的参数不会重置 注：v2.7.0 新增
table.checkStatus(id); //获取表格选中行（下文会有详细介绍）。id 即为 id 参数对应的值
table.getData(id); //用于获取表格当前页的所有行数据（layui 2.6.0 开始新增）
table.cache; // 获取当前表格的缓存数据（包含功能型特定状态属性在内的所有数据）
table.resize(id); //重置表格尺寸
table.exportFile(id, data, obj); //导出数据

获取选中行

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

【自动化渲染】
<table class="layui-table" lay-data="{id: 'idTest'}"> …… </table>
 
【方法渲染】
table.render({ //其它参数省略
  id: 'idTest'
});

var checkStatus = table.checkStatus('idTest'); //idTest 即为基础参数 id 对应的值
 
console.log(checkStatus.data) //获取选中行的数据
console.log(checkStatus.data.length) //获取选中行数量，可作为是否有选中行的条件
console.log(checkStatus.isAll ) //表格是否全选

重载

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

语法	说明
table.reload(id, options, deep)	对表格进行完整重载，包括数据请求和新的基础参数的读取。参数 id 即为基础参数id对应的值，见：设定容器唯一 id 参数 options 即为各项基础参数参数 deep：是否采用深度重载（即参数深度克隆，也就是重载时始终携带初始时及上一次重载时的参数），默认 false 注意：deep 参数为 v2.6.0 新增
table.reloadData(id, options, deep)	对表格仅进行数据重载。与数据无关的参数不会参与到重载，可大幅提升体验。参数及用法与 table.reload() 完全相同注：v2.7.0 新增

查看 v2.6.0 之前的版本兼容方案

请注意：如果你在 2.6.0 之前版本已经习惯深度重载模式的，现在请在第三个参数中，加上 true，如：

table.reload(ID, options, true); //这样就跟 v2.5.7 及之前版本处理机制完全一样。或者您也可以像下面这样做：

//由于 2.6.0 之前的版本是采用深重载，
//所以如果您之前真实采用了深重载机制，那么建议将以下代码放入您的全局位置，从而可对老项目起到兼容作用
var tableReload = table.reload;
table.reload = function(){
  var args = [];
  layui.each(arguments, function(index, item){
    args.push(item);
  });
  args[2] === undefined && (args[2] = true);
  return tableReload.apply(null, args);
};
//但如果你之前没有采用深重载机制，也可以不放。不放甚至可以解决你之前因为多次 reload 而带来的各种参数重叠问题

重载示例：

【HTML】
<table class="layui-table" lay-data="{id: 'idTest'}"> …… </table>
 
【JS】
table.reload('idTest', {
  url: '/api/table/search'
  ,where: {} //设定异步数据接口的额外参数
  //,height: 300
});

// 原始实例
table.render({
  elem: '#id'
  ,cols: [] //设置表头
  ,url: '/api/data' //设置异步接口
  ,id: 'idTest'
}); 
 
// 重载 - 这里以搜索为例
table.reload('idTest', {
  where: { //设定异步数据接口的额外参数，任意设
    aaaaaa: 'xxx'
    ,bbb: 'yyy'
    //…
  }
  ,page: {
    curr: 1 //重新从第 1 页开始
  }
}); 
 
// 只重载数据
table.reloadData('idTest', {}); // 用法同 table.reload(); 注：v2.7.0 新增

重置表格尺寸

该方法可重置表格尺寸和结构，其内部完成了：固定列高度平铺、动态分配列宽、容器滚动条宽高补丁 等操作。它一般用于特殊情况下（如“非窗口 resize”导致的表格父容器宽度变化而引发的列宽适配异常），以保证表格在此类特殊情况下依旧能友好展示。

语法：table.resize('ID')，其中 ID 为基础参数 id 对应的值（见：设定容器唯一ID），如：

table.render({ //其它参数省略
  ,elem: '#demo'
  //,…… //其它参数
  ,id: 'idTest'
});
 
//执行表格“尺寸结构”的重置，一般写在对应的事件中
table.resize('idTest');

导出任意数据

尽管 table 的工具栏内置了数据导出按钮，但有时你可能需要通过方法去导出任意数据，那么可以借助以下方法：
语法：table.exportFile(id, data, obj)

var ins1 = table.render({
  elem: '#demo'
  ,id: 'test'
  //,…… //其它参数
})      
      
//将上述表格示例导出为 csv 文件
table.exportFile(ins1.config.id, data); //data 为该实例中的任意数量的数据

事实上，该方法也可以不用依赖 table 的实例，可直接导出任意数据：

table.exportFile(['名字','性别','年龄'], [
  ['张三','男','20'],
  ['李四','女','18'],
  ['王五','女','19']
], 'csv'); // 默认导出 csv，也可以为：xls
 
// 自定义导出文件名 注：第三个参数 object 的类型为 v2.7.0 新增
table.exportFile(['A','B','C'], [[1,2,3]], {
  type: 'csv', // 导出格式
  title: '导出文件' 
});

事件

语法：table.on('event(filter)', callback);
注：event 为内置事件名，filter 为容器 lay-filter 设定的值
目前所支持的所有事件见下文

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

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

头部工具栏事件

点击头部工具栏区域设定了属性为 lay-event="" 的元素时触发。如：

原始容器
<table id="demo" lay-filter="test"></table>
 
工具栏模板：
<script type="text/html" id="toolbarDemo">
  <div class="layui-btn-container">
    <button class="layui-btn layui-btn-sm" lay-event="add">添加</button>
    <button class="layui-btn layui-btn-sm" lay-event="delete">删除</button>
    <button class="layui-btn layui-btn-sm" lay-event="update">编辑</button>
  </div>
</script>
 
<script;>
//JS 调用：
table.render({
  elem: '#demo'
  ,toolbar: '#toolbarDemo'
  //,…… //其他参数
});
 
//触发事件
table.on('toolbar(test)', function(obj){
  var checkStatus = table.checkStatus(obj.config.id);
  switch(obj.event){
    case 'add':
      layer.msg('添加');
    break;
    case 'delete':
      layer.msg('删除');
    break;
    case 'update':
      layer.msg('编辑');
    break;
  };
});
</script>

单元格工具事件

在表格主体的单元格中，需要进行很多的动态操作，比如编辑、删除，这时可借助单元格工具事件（tool）来实现，这是一个示例：

<!-- 假设下述为 templet 对应的模板，其中 lay-event="" 是获取「单元格工具事件」的关键所在，值可随意定义 -->
<script type="text/html" id="toolEventDemo">
  <a class="layui-btn layui-btn-xs" lay-event="detail">查看</a>
  <a class="layui-btn layui-btn-xs" lay-event="edit">编辑</a>
  <a class="layui-btn layui-btn-danger layui-btn-xs" lay-event="del">删除</a>
  
  <!-- 支持任意的 laytpl 语法，如： -->
  {{#  if(d.auth > 2){ }}
    <a class="layui-btn layui-btn-xs" lay-event="check">审核</a>
  {{#  } }}
</script>
 
<table id="demo" lay-filter="test"></table> 
 
<script>
table.render({
  elem: '#demo'
  ,cols: [[
    {title: '操作', width: 200, templet: '#toolEventDemo'}
  ]]
  //,…… //其他参数
});
</script>

接下来我们可以借助 table 模块的单元格工具事件，完成不同的操作功能：

//单元格工具事件
table.on('tool(test)', function(obj){ // 注：test 是 table 原始标签的属性 lay-filter="对应的值"
  var data = obj.data; //获得当前行数据
  var layEvent = obj.event; //获得 lay-event 对应的值（也可以是表头的 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);
      
      // 向服务端发送删除请求，执行完毕后，可通过 reloadData 方法完成数据重载
      /*
      table.reloadData(id, {
        scrollPos: 'fixed'  // 保持滚动条位置不变 - v2.7.3 新增
      });
      */
    });
  } else if(layEvent === 'edit'){ //编辑
    //do something
    
    // 同步更新缓存对应的值
    // 该方法仅为前端层面的临时更新，在实际业务中需提交后端请求完成真实的数据更新。
    obj.update({
      username: '123',
      title: 'abc'
    }); 
    // 若需更新其他包含自定义模板并可能存在关联的列视图，可在第二个参数传入 true
    obj.update({
      username: '123'
    }, true); // 注：参数二传入 true 功能为 v2.7.4 新增
 
    // 当发送后端请求成功后，可再通过 reloadData 方法完成数据重载
    /*
    table.reloadData(id, {
      scrollPos: 'fixed'  // 保持滚动条位置不变 - v2.7.3 新增
    });
    */
  }
});

上述 tool 事件为单击时触发，若需双击触发，采用 toolDouble 事件即可，如：

//单元格工具事件 - 双击触发 注：v2.7.0 新增
table.on('toolDouble(test)', function(obj){
  // 用法跟 tool 事件完全相同
});

排序切换事件

点击表头排序时触发，它通用在基础参数中设置 autoSort: false 时使用，以完成服务端的排序，而不是默认的前端排序。该事件的回调函数返回一个 object 参数，携带的成员如下：

//禁用前端自动排序，以便由服务端直接返回排序好的数据
table.render({
  elem: '#id'
  ,autoSort: false //禁用前端自动排序。
  //,… //其它参数省略
});
 
//触发排序事件 
table.on('sort(test)', function(obj){ //注：sort 是工具条事件名，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 //记录初始排序，如果不设的话，将无法标记表头的排序状态。
    ,where: { //请求参数（注意：这里面的参数可任意定义，并非下面固定的格式）
      field: obj.field //排序字段
      ,order: obj.type //排序方式
    }
  });
  
  layer.msg('服务端排序。order by '+ obj.field + ' ' + obj.type);
});

复选框事件

点击复选框时触发，回调函数返回一个 object 参数：

table.on('checkbox(test)', function(obj){
  console.log(obj); //当前行的一些常用操作集合
  console.log(obj.checked); //当前是否选中状态
  console.log(obj.data); //选中行的相关数据
  console.log(obj.type); //如果触发的是全选，则为：all，如果触发的是单选，则为：one
});

单选框事件

点击表格单选框时触发，回调函数返回一个 object 参数，携带的成员如下：

table.on('radio(test)', function(obj){ //test 是 table 标签对应的 lay-filter 属性
  console.log(obj); //当前行的一些常用操作集合
  console.log(obj.checked); //当前是否选中状态
  console.log(obj.data); //选中行的相关数据
});

单元格编辑事件

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

table.on('edit(test)', function(obj){ //注：edit是固定事件名，test是table原始容器的属性 lay-filter="对应的值"
  console.log(obj.value); //得到修改后的值
  console.log(obj.field); //当前编辑的字段名
  console.log(obj.data); //所在行的所有相关数据  
});

行单双击事件

点击或双击行时触发。

//触发行单击事件
table.on('row(test)', function(obj){
  console.log(obj.tr) //得到当前行元素对象
  console.log(obj.data) //得到当前行数据
  //obj.del(); //删除当前行
  //obj.update(fields) //修改当前行数据
});
 
//触发行双击事件
table.on('rowDouble(test)', function(obj){
  //obj 同上
});

尾部分页栏事件

点击尾部分页栏自定义模板中属性为 lay-event="" 的元素时触发。用法跟 toolbar 完全一致。注：该事件为 v2.7.0 新增

// 示例
table.render({
  elem: '#demo'
  ,pagebar: '#pagebarDemo' // 分页栏模板所在的选择器
  //,…… //其他参数
});
 
// 分页栏事件
table.on('pagebar(test)', function(obj){
  console.log(obj.config); // 当前实例的配置信息
  console.log(obj.event); // 属性 lay-event 对应的值
});

结语

温馨提示：若表头数量太多以及每页呈现的数据量太大，为了性能考虑，建议采用静态表格渲染，配合 laypage 组件实现分页。

layui - 在每一个细节中，用心与你沟通

 table 数据表格文档 - layui.table

查看 v2.6.0 之前的版本兼容方案

table 数据表格文档 - layui.table