-

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:'/v2/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 单元格排列方式。可选值有:leftcenterright 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 组件支持无限极表头,你可按照上述的方式继续扩充。核心点在于 rowspancolspan 两个参数的使用。

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 - 在每一个细节中,用心与你沟通