表格组件 🔥

表格组件 table 是 Layui 中使用率极高的一个组件,它以表格的承载方式对数据进行渲染、重载、排序、统计、分页等等一系列交互操作,并提供了丰富的 API 用于扩展,基本涵盖了日常业务所涉及的大部分需求。

示例

以下所有示例中演示的数据均为「静态模拟数据」,实际使用时换成您的真实接口即可。

综合演示 🔥

  

静态表格

静态表格是指内容已经存在于页面中的 <table class="layui-table"> 元素,且可通过一些特定属性设定不同风格。

  

模板配置渲染

在上文「综合演示」中,是通过组件核心方法完成的渲染。除此,还可以在模板上直接配置相关属性,让其自动完成渲染。

  

静态表格转换

  

已知数据渲染

  

自定义模板

  

自定义样式 2.7+

  

自定义分页

  
  

编辑的权限控制 2.7+

以下演示一个根据返回数据中某个字段来判断是否开启该行的编辑,单击对应行可进入单元格编辑。

  

实现多样化编辑

  

转换数据格式

  

筛选列记忆功能

即点击当前表格右上角筛选图标后,对表头进行显示隐藏勾选,再刷新页面依然保留当前筛选状态。

  

选中行操作

点击行任意处,通过行事件中执行相关选中方法,实现对整行的状态选中。如下以「单选」行为例:

  

多级表头

  

更多示例

API

API 描述
var table = layui.table 获得 table 模块。
table.set(options) 设定全局默认属性项。
table.render(options) table 组件渲染,核心方法。
table.init(filter, options) 初始化渲染静态表格。
table.reload(id, options, deep) 表格完整重载。
table.reloadData(id, options, deep) 2.7+ 表格数据重载。
table.renderData(id) 2.8.5+ 重新渲染数据。
table.updateRow(id, opts) 2.9.4+ 更新指定行数据。
table.checkStatus(id) 获取选中行相关数据。
table.setRowChecked(id, opts) 2.8+ 设置行选中状态。
table.getData(id) 获取当前页所有行表格数据。
table.cache 获取表格缓存数据集(包含特定字段)。
table.resize(id) 重置表格尺寸。
table.exportFile(id, data, opts) 导出表格数据到本地文件。
table.getOptions(id) 2.8+ 获取表格实例配置项。
table.hideCol(id, cols) 2.8+ 设置表格列的显示隐藏属性。
table.on('event(filter)', callback) table 相关事件。

全局设置

该方法主要用于初始化设置属性默认值。实际应用时,必须先设置该方法,再执行渲染、重载等操作。

layui.use(function(){
  var table = layui.table;
  // 全局设置
  table.set({
    headers: {token: '123'}
  });
  // 渲染
  table.render(options);
});

渲染

table 提供了以下三种渲染模式,在实际使用时,一般按情况选择其中一种即可。

渲染方式 描述
方法配置渲染 通过 table 组件提供的核心方法 table.render(options) 完成的渲染。推荐
模板配置渲染 通过 <table> 标签的 lay-options="{}" 属性定义模板,组件自动对其进行解析并完成渲染。
静态表格渲染 对一段已经包含数据内容的静态表格进行动态化转换,使其具备 table 组件的相关功能。

方法配置渲染

table.render(options);

该方法返回当前实例对象,包含可操作当前表格的一些成员方法。

<table id="test"></table>
 
<!-- import layui -->
<script>
layui.use(function(){
  var table = layui.table;
  
  // 渲染,并获得实例对象
  var inst = table.render({
    elem: '#test', // 绑定元素选择器
    // 其他属性
    // …
  });
 
  // 实例对象成员
  inst.config; // 当前表格配置属性
  inst.reload(options, deep); // 对当前表格的完整重载。参数 deep 表示是否深度重载。
  inst.reloadData(options, deep); // 对当前表格的数据重载。参数 deep 同上。
  inst.resize(); // 对当前表格重新适配尺寸
  inst.setColsWidth() // 对当前表格重新分配列宽
})
</script>

模板配置渲染

<table> 元素中直接书写 lay-options="{}" 属性,组件将自动对其进行解析并完成渲染。

<!-- 此处 `lay-options` 定义基础属性 -->
<table class="layui-table" lay-options="{url: ''}" id="test">
  <thead>
    <tr>
      <!-- 此处 `lay-options` 定义表头属性 -->
      <th lay-options="{field: 'title'}">Title</th> 
    </tr>
  </thead>
</table>

2.8 之前版本通过 lay-data="{}" 定义属性配置项;
2.8+ 版本推荐采用 lay-options,但同时兼容 lay-data

静态表格渲染

table.init(filter, options);

  • 参数 filter : <table> 元素对应的 lay-filter 属性值
  • 参数 options : 基础属性配置项。#详见属性

该方法用于将已输出在页面中的静态表格内容转换为动态 table 组件。#参考相关示例

<table lay-filter="test">
  表格内容
</table>
 
<!-- import layui -->
<script>
layui.use(function(){
  var table = layui.table;
  // 将静态表格进行动态化
  table.init('test', {
    height: 366,
    // 其他属性
    // …
  });
});
</script>

属性 🔥

属性是指 table 渲染、重载 时的配置选项(options),它本身是一个 object 参数。如:

// 渲染
table.render({
  // options
  elem: '',
  cols: [[]],
  // …
}); 
// 重载
table.reload(id, {
  // options
});
       
若为模板配置渲染,则 lay-options 或 lay-data 的属性值即为属性的配置选项(:
<table lay-options="{url: ''}"> … </table> 

table 的属性众多,我们大致分为以下几种:

属性类别 描述
基础属性 -
异步属性 用于和异步数据请求相关的基础属性,由于相关属性成员较多,所以单独提取介绍。
表头属性 基础属性 cols 的子属性集。

基础属性

属性名 描述 类型 默认值
elem 绑定原始 table 元素,方法渲染方式必填。 string/DOM -

url

发送异步请求的 URL。更多异步相关属性见 : #异步属性

- -

cols

表头属性集,通过二维数组定义多级表头。方法渲染时必填。 更多表头属性见 : #表头属性

array -
data

直接赋值数据。既适用于只展示一页数据,也能对一段已知数据进行多页展示。该属性与 url 属性只能二选一。


:当设置 data 模式时,count 的值取 data.length,即对一段已知数据进行分页展示。 此时在 page 属性中设置 count 无效。 若要在同一页显示所有数据,可将 limit 设置成 data.length,即与 count 等同即可,那么默认的分页栏只会显示 1 页,若要自定义分页结构,可通过 pagebar 属性结合 laypage 组件来重新自定义分页排版。

array -
id

设定实例唯一索引,以便用于其他方法对 table 实例进行相关操作。若该属性未设置,则默认从 elem 属性绑定的原始 table 元素中的 id 属性值中获取。

string -
toolbar

开启表格头部工具栏。支持以下几种值写法:

  • toolbar: '#template-id' 自定义工具栏模板选择器
  • toolbar: '<div>xxx</div>' 直接传入模板字符
  • toolbar: true 仅开启工具栏右侧,不显示左侧模板
  • toolbar: 'default' 开启工具栏并显示默认模板
string
boolean

false

defaultToolbar

设置头部工具栏右上角工具图标,值为一个数组,图标将根据数组值的顺序排列。

默认内置工具

defaultToolbar: [
  'filter', // 列筛选
  'exports', // 导出
  'print' // 打印
]

重写内置工具 2.9.12+,以自定义导出为例:

defaultToolbar: [
  'filter',
  {
    name: 'exports',
    onClick: function(obj) {
      // 获得数据并清除临时字段
      var data = table.clearCacheKey(obj.data);
      // 当前示例配置项
      var options = obj.config;
      // 弹出面板
      obj.openPanel({
        list: [ // 列表
          '<li data-type="csv">导出 CSV 文件</li>',
          '<li data-type="xlsx">导出 XLSX 文件</li>'
        ].join(''),
        done: function(panel, list) { // 操作列表
          list.on('click', function() {
            var type = $(this).data('type')
            if (type === 'csv') {
               // 调用内置导出方法
              table.exportFile(options.id, null, type);
            } else if(type === 'xlsx') {
              // 自助处理导出 - 如借助 sheetjs 库或服务端导出
              // …
            }
          });
        }
      });
    }
  },
  'print'
]

扩展工具图标

defaultToolbar: [
  'filter', 'exports', 'print', // 内置工具
  {
    // 扩展工具
    title: '提示', // 标题
    name: 'tips', // name
    layEvent: 'LAYTABLE_TIPS', // 事件标识
    icon: 'layui-icon-tips', // 图标 className
    onClick: function(obj) { // 点击事件 - 2.9.12+
      console.log(obj); // 查看返回的对象成员
    }
  }
]
width 设置容器宽度,默认自适应。 number -

height

设置表格容器高度,默认自适应。其他可选值的规则如下:
  • height: 315 设置固定高度
  • height: 'full-30' 设置相对可视屏幕的高度铺满。这是一个特定的语法格式:full 表示铺满;后面的数字表示当前 table 之外的元素占用的高度,如:表格头部到页面最顶部表格底部距离页面最底部的“距离和”
  • height: '#id-30' 设置相对父元素的高度铺满,其中 #id 即父元素的 ID 选择器,其计算原理和上述 full 相同。

函数写法 2.9.1+

当需要动态改变表格高度时建议使用,如下以等效 full-xx 的写法为例:

height: function(){
   // 自定义其他区域的高度
  var otherHeight = $('#search-content').outerHeight();
  return $(window).height() - otherHeight; // 返回 number 类型
}
maxHeight 2.8+

设置表格容器的最大高度,设置该属性后,height 属性将被认定为默认的自适应值。

number -
cellMinWidth

设置所有普通单元格的最小宽度,一般用于列宽自动分配的情况。其优先级低于表头属性中的 minWidth

number

60

cellMaxWidth 2.8+

设置所有普通单元格的最大宽度。其优先级低于表头属性中的 maxWidth

number -
lineStyle 2.7+

用于定义表格的多行样式,如每行的高度等。该参数一旦设置,单元格将会开启多行模式,且鼠标 hover 时会通过显示滚动条的方式查看到更多内容。 请按实际场景使用。
示例:lineStyle: 'height: 95px;'

string -
className 2.7+ 用于给表格主容器追加 css 类名,以便更好地扩展表格样式 string -
css 2.7+

用于给当前表格主容器直接设定 css 样式,样式值只会对所在容器有效,不会影响其他表格实例。如:css: '.layui-table-page{text-align: right;}'

string -
cellExpandedMode 2.8.17+

用于设置所有单元格默认展开方式,可选值有:

  • tips 悬浮展开方式
  • default 多行展开方式(默认)
string -
cellExpandedWidth 2.8.17+

用于设置所有单元格默认展开后的宽度。当 cellExpandedMode 属性为默认值时有效。

number

60

escape 2.6+ 是否开启对内容的编码(转义 html) boolean

true

totalRow 是否开启合计行区域 string

false

page

用于开启分页。
支持传入 laypage 组件的基础属性(jump,elem 除外)

boolean
object

false

pagebar 2.7+

用于开启分页区域的自定义模板,用法同 toolbar 属性。

string -
limit

每页显示的条数。值需对应 limits 参数的选项。优先级低于 page 属性中的 limit 属性。

number

10

limits 每页条数的选择项。 array

[10,…,90]

loading

设置数据请求时的加载动画,需开启 url 选项才生效。

  • 若值为 boolean 类型,表示是否显示加载条,如:
loading: true // 显示默认加载条
loading: false // 禁用加载条
  • 若值为 string 类型 2.9.10+,表示自定义加载模板,此时可添加任意动画元素,如:
loading: '<i class="layui-icon layui-icon-loading-1 layui-anim layui-anim-rotate layui-anim-loop"></i>'
boolean
string

true

scrollPos 2.7+

用于设置重载数据或切换分页时的滚动条位置状态。可选值:

  • fixed 重载数据时,保持滚动条位置不变
  • reset 重载数据时,滚动条位置恢复置顶
  • default 默认方式,无需设置。即重载数据或切换分页时,纵向滚动条置顶,横向滚动条位置不变。
string -
editTrigger 2.7+

是用于设定单元格编辑的事件触发方式。如双击: dblclick

string

click

title 定义 table 的大标题(在文件导出等地方会用到) string -
text 自定义文本,如空数据时的异常提示等。 object
`text: {none: '无数据'}`
autoSort

是否由组件自动进行前端排序。若为 false,则需自主排序,即由后端直接返回排序好的数据。#详细用法

boolean

true

initSort

初始排序状态。用于在数据表格渲染完毕时,按某个字段排序显示。它接受一个 object 类型的值,包含属性有:

  • field 排序字段。对应 cols 设定的各字段名
  • type 排序方式。可选值 : 'asc','desc',null,即:升序、降序、默认
initSort: {
  field: 'id', // 按 id 字段排序
  type: 'desc' // 降序排序
}
object -
skin

设置表格边框风格。可选值:grid|line|row|nob

string

grid

size

设置表格其他尺寸。可选值:sm|md|lg

string

md

even

是否开启隔行背景。

string

false

before 2.7+

数据渲染之前的回调函数。
table.render({
  before: function(options){
    console.log(options); // 当前实例属性配置项
    options.where.abc = 123; // 修改或额外追加 where 属性
  },
  // …  // 其它属性
});

done

数据渲染完毕的回调函数。返回的参数如下:
table.render({
  done: function(res, curr, count, origin){
    console.log(res); // 得到当前渲染的数据
    console.log(curr);  // 得到当前页码
    console.log(count); // 得到数据总量
    console.log(origin); // 回调函数所执行的来源 --- 2.8.7+
  },
  // …  // 其它属性
});
error 2.6+

数据请求失败的回调函数。返回两个参数:错误对象、内容。

error: function(e, msg) {
  console.log(e, msg)
}
complete 2.8.18+

数据接口请求完成后执行,无论成功还是失败均会触发

complete: function(xhr, ts) {
  console.log(xhr, ts)
}

异步属性

异步属性本质也是基础属性,当开启 url 属性时才有效,由于相关属性成员较多,所以单独提取介绍。

属性名 描述
url

发送异步请求的 URL。默认会自动传递两个参数:?page=1&limit=30(该参数可通过 request 属性自定义)
page 代表当前页码、limit 代表每页数据条数。

method

请求的方式,默认:get

where

请求的其他参数。如:where: {token: 'sasasas', id: 123}

headers

请求的数据头参数。如:headers: {token: 'sasasas'}

contentType

请求的内容编码类型。若要发送 json 内容,可设置:
contentType: 'application/json'

dataType 2.7+

请求的数据类型,默认 json

jsonpCallback 2.7+

设置当 dataType: 'jsonp' 时的回调函数名。

request

用于对默认的分页相关的请求参数 page,limit 重新设定名称。如:

request: {
  pageName: 'curr', // 页码的参数名称,默认:page
  limitName: 'nums' // 每页数据条数的参数名,默认:limit
}

那么请求数据时的参数将会变为 ?curr=1&nums=30

parseData

数据格式解析的回调函数,用于将返回的任意数据格式解析成 table 组件规定的数据格式:
{
  "code": 0,
  "msg": "",
  "count": 1000,
  "data": [{}, {}]
} 

很多时候,您接口返回的数据格式并不一定都符合 table 默认规定的格式,比如:

{
  "status": 0,
  "message": "", 
  "total": 180, 
  "data": {
    "item": [{}, {}]
  }
}

此时我们可以借助 parseData 回调函数将数据解析并转换为默认规定的格式:

table.render({
  elem: '',
  url: '',
  parseData: function(res){ // res 即为原始返回的数据
    return {
      "code": res.status, // 解析接口状态
      "msg": res.message, // 解析提示文本
      "count": res.total, // 解析数据长度
      "data": res.data.item // 解析数据列表
    };
  },
  // … //其他参数
}); 

该函数非常实用

返回数据中的特定字段

在返回的数据中,允许规定某些特定字段,以便 table 组件进行相应的特定解析。

特定字段名 描述 读写状态
LAY_CHECKED 当前行的选中状态 可读可写
LAY_DISABLED 当前行是否禁止选择 可读可写
LAY_INDEX 当前行下标。每页重新从零开始计算 只读
LAY_NUM 当前行序号 只读
LAY_COL 当前列的表头属性配置项 只读

示例一: 在返回的数据中设置特定字段:

{
  "code": 0,
  "count": 1000,
  "data": [{},{
    LAY_DISABLED: true
  }]
}

示例二: 在模板中读取特定字段示例:

<script type="text/html" id="TPL-demo-xxx">
  当前行下标: {{= d.LAY_INDEX }} 
  当前列的某个表头属性:  {{= d.LAY_COL.field }}
</script>

表头属性

表头属性是基础属性 cols 的子集,其使用频率甚至超过基础属性本身。

属性名 描述 类型 默认值
field

设置字段名。通常是表格数据列的唯一标识

string -
title

设置列的标题。

string -
fieldTitle 2.8+

设置列的字段标题。该属性在筛选列和导出场景中优先级高于 title 属性

string -
width

设置列宽。若不填写,则自动分配;若填写,则支持值为:数字、百分比。如: width: 200 / width: '30%'

number/string -
minWidth

设置当前列的最小宽度,一般用于列宽自动分配的情况。其优先级高于基础属性中的 cellMinWidth

number

60

maxWidth 2.8+

设置当前列的最大宽度。其优先级高于基础属性中的 cellMaxWidth

number -
expandedWidth 2.8.15+

设置单元格被展开后的宽度。若设置的值的小于当前列宽,则展开后的列宽保持不变。注:当 expandedMode 属性为默认值时有效。

number -
expandedMode 2.8.17+

用于设置所有单元格默认展开方式,可选值有:

  • tips 悬浮展开方式
  • default 多行展开方式(默认)

优先级高于 cellExpandedMode 基础属性

string -
type

设置列类型。可选值有:

  • normal 常规列,无需设定
  • checkbox 复选框列
  • radio 单选框列
  • numbers 序号列
  • space 空列
string

normal

LAY_CHECKED

设置全选状态,当列设置 type: 'checkbox' 时才有效。

boolean

false

fixed

设置固定列,即不跟随 table 横向滚动条而滚动。可选值有:

  • left 固定在左
  • right 固定在右

多级表头设置固定列时,父列和子列均需设置。

string -

templet

设置列的自定义模板,核心属性。模板遵循 laytpl 组件语法。

templet 提供了三种使用方式,选择任一用法即可:

  • 设置模版选择器

<script type="text/html" id="TPL-demo-title">
  <a href="/detail/{{= d.id }}" class="layui-table-link">
    {{= d.title }} 
  </a>
</script>
 
<!-- 
模板中的 `d` 不仅包含当前行数据,还包含特定字段,如:
{{= d.LAY_INDEX }} {{= d.LAY_COL }} 等 
-->
table.render({
  cols: [[
    {field: 'title', templet: '#TPL-demo-title'}
    // …
  ]],
  // …
});

  • 设置模板内容

该方式必须在内容中包裹一层 <div></div>,否则无法读取模板。

table.render({
  cols: [[
    {field: 'title', templet: '<div><a href="/detail/{{= d.id }}" class="layui-table-link">{{= d.title }}</a></div>'}
    // …
  ]],
  // …
});

  • 设置模板函数

函数将返回一个 d 参数,包含当前行数据及特定的额外字段。

table.render({
  cols: [[
    {field: 'title', templet: function(d){
      console.log(d); // 得到当前行数据
      console.log(this); // 得到表头当前列配置项
      console.log(d.LAY_NUM); // 得到序号。或其他特定字段
      
      // 返回模板内容
      return '<a href="/detail/'+ d.id +'" class="layui-table-link">'+ d.title +'</a>'
    }}
    // …
  ]],
  // …
});
exportTemplet 2.6.9+

设置表格导出时的模板,用法同 templet 属性。当 templet 指向的模板内容较复杂时建议使用,如下以模板存在 select 元素为例:

exportTemplet: function(d, obj){
  // 当前 td
  var td = obj.td(this.field);
  // 返回 select 选中值
  return td.find('select').val();
}

totalRow

是否开启该列的自动合计功能,默认不开启。
  • 采用前端合计

// 开启并输出合计行前端合计结果
totalRow: true
// 开启并输出合计行自定义模板。此处 TOTAL_NUMS 即为合计结果的固定特定字段
totalRow: '{{= d.TOTAL_NUMS }} 单位' 
// 取整或其他运算
totalRow: '{{= parseInt(d.TOTAL_NUMS) }}'

注意:合计行模板仅支持字符写法,不支持函数写法,请勿与 templet 用法混淆。

  • 采用后端合计

前端合计的数据有限,因此常需要后端直接返回合计结果,组件将优先读取。数据格式如下:

{
  "code": 0,
  "totalRow": {
    "score": "777",
    "experience": "999"
  },
  "data": [{}, {}],
  "msg": "",
  "count": 1000
}

在合计行自定义模板中输出后端返回的合计数据

// 获取后端接口返回数据中的统计字段。此处 TOTAL_ROW 即对应返回据中的 totalRow
totalRow: '分数:{{= d.TOTAL_ROW.score }}'

如上,在 totalRow 中返回所需统计的列字段名和值即可。 totalRow 字段同样可以通过 parseData 回调来解析成为 table 组件所规定的数据格式。

edit

用于对列所在的单元格开启编辑功能。可选值有:
  • edit: 'text' 单行输入模式
  • edit: 'textarea' 多行输入模式 2.7+

函数写法 2.7+

edit: function(d){
  // d 即为当前行数据,此时可根据行相关字段来开启该行是否编辑的权限
  if(d.editable){ // editable 为任意字段名
    return 'text'; // 编辑模式
  }
}
string
function

false

hide

是否初始隐藏列

boolean

false

ignoreExport 2.8.3+

是否导出时忽略该列。支持以下可选值:

  • true : 忽略导出
  • false : 强制导出,对所有列适用
  • null : 只对常规列导出(默认)
boolean -
escape

是否对当前列进行内容编码(转义 html),优先级大于基础属性中的 escape

boolean

true

sort

是否开启列的排序功能。
注意:不推荐对值同时存在“数字和普通字符”的列开启排序,因为会进入字典序排序计算中,如:'张三' > '2' > '100',这可能并不是你想要的结果,但字典序排列采用的是 ASCII 码比对。

boolean

false

unresize

是否禁用拖拽列宽。默认情况下会根据列类型 type 属性来决定是否禁用,如复选框列,会自动禁用。而其它普通列,默认允许拖拽列宽,当然你也可以设置 true 来禁用该功能。

boolean

false

event

自定义单元格点击事件名,以便在 单元格工具事件 中完成对该单元格的事件处理。

string -
style

自定义单元格样式。可传入任意的 CSS 内容,如:style: 'font-size: 13px; color: red;'

string -
align

单元格排列方式。可选值有:left | center | right

string

left

colspan

单元格所占列数。一般用于多级表头

number

1

rowspan

单元格所占行数。一般用于多级表头

number

1

重载

即对一段已经渲染好的表格重新设置属性并渲染,可分为以下几种重载方式:

重载方式 API
完整重载 table.reload(id, options, deep)
仅数据重载 table.reloadData(id, options, deep)

重载的使用方式完全相同,区别只是在于参与重载时的属性差异及其对应的效果差异。一般按照实际需求选择使用。

完整重载

table.reload(id, options, deep);

  • 参数 id : table 渲染时的 id 属性值
  • 参数 options : 为基础属性配置项
  • 参数 deep 2.6+ : 是否采用深度重载(即重载时始终携带初始时及上一次重载时的参数),默认 false。

该方法用于对表格的视图和数据在内的全部重载,所有属性均会参与到重载中,对应的表格会有一个直观的刷新效果。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 完整重载 -  所有属性属性(options)均可参与到重载中
table.reload('test', {
  where: { // 传递数据异步请求时携带的字段
    aaa: '111',
    bbb: '222'
    //…
  },
  height: 1000 // 重设高度
});

仅数据重载 2.7+

table.reloadData(id, options, deep);

  • 参数同 table.reload(id, options, deep) 参数

该方法用于对表格的数据重载,与数据无关的属性不会参与到重载中。因此若只是更新数据,该方法可大幅提升体验。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 数据重载 - 仅与数据相关的属性(options)能参与到重载中
table.reloadData('test', {
  where: {}, // 数据异步请求时携带的字段集 --- 属性设置有效,因属于数据相关属性
  scrollPos: true, // 设定重载数据或切换分页时的滚动条的位置状态 --- 属性设置有效
  // …
  height: 2000 // 高度  --- 属性设置无效,因不属于数据相关属性
});

重新渲染数据 2.8.5+

table.renderData(id);

  • 参数 id : table 渲染时的 id 属性值

该方法用于重新渲染数据,一般在修改 table.cache 后使用。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取当前实例的数据缓存
var data = table.cache['test'];
// 获取某行数据,并从 data 中移除该行
var item = data.splice(index, 1) // index 为当前行下标,一般可在事件中通过 obj.index 得到
// 将某行数据移动到另外某行
data.splice(newIndex, 0, item[0]);
// 根据 table.cache 重新渲染数据
table.renderData('test');

更新指定行数据 2.9.4+

table.updateRow(id, opts);

  • 参数 id : table 渲染时的 id 属性值
  • 参数 opts : 更新指定行时的可选属性,详见下表
opts 描述 类型 默认值
index 行索引 number -
data 行数据 object -
related 是否更新其他包含自定义模板且可能有所关联的列视图 boolean/function -

该方法用于更新指定行数据。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 更新指定行数据
table.updateRow('test', {
  index: 0,
  data: {
    id: 1,
    username: 'name'
  }
  // 是否更新关联的列视图
  related: function(field, index){
    return ['score', '5'].indexOf(field) !== -1;
  }
});

获取选中行

table.checkStatus(id);

  • 参数 id : table 渲染时的 id 属性值

该方法用于获取表格当前选中行相关数据

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取选中行相关数据
var tableStatus = table.checkStatus('test');
console.log(tableStatus.data) // 选中行的数据
console.log(tableStatus.data.length) // 选中行数量,可作为是否有选中行的条件
console.log(tableStatus.dataCache) // 选中的原始缓存数据,包含内部特定字段 --- 2.9.17+
console.log(tableStatus.isAll ) // 表格是否全选

设置行选中状态 2.8+

table.setRowChecked(id, opts);

  • 参数 id : table 渲染时的 id 属性值
  • 参数 opts : 设置行选中时的可选属性,详见下表
opts 描述 类型 默认值
type 选中方式。可选值: checkbox,radio string checkbox
index 选中行的下标。支持以下几种情况:
  • 若值为 number 类型,则表示行所在的数组下标(0 开头)
  • 若值为 array 类型 2.9.1+,则表示多选下标。
  • 若值为 string 类型,则可设置 all 操作全选。
number
array
string
-
checked 选中状态值。
  • 若传递该属性,则赋值固定值。
  • 若不传递该属性(默认),则 checkbox 将在 true|false 中自动切换值,而 radio 将赋值 true 固定值。2.8.4+
    注意:若 index 指定为多选或全选,checked 应当显式传递固定值
boolean -

该方法用于设置行的选中样式及相关的特定属性值 LAY_CHECKED

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
 
// 设置某行选中
table.setRowChecked('test', {
  index: 0, // 选中行的下标。 0 表示第一行
});
// 批量选中行
table.setRowChecked('test', {
  index: [1,3,5] // 2.9.1+
});
// 取消选中行
table.setRowChecked('test', {
  index: 'all', // 所有行
  checked: false // 此处若设置 true,则表示全选
});

获取当前页接口数据

table.getData(id);

  • 参数 id : table 渲染时的 id 属性值

该方法用于获取表格当前页的数据,它对应的是接口返回的原始数据,不包含 table 组件内部的特定字段。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取当前页接口数据
var data = table.getData('test');
console.log(data);

获取表格缓存数据集

var tableCache = table.cache;

table.cache 是一段存储当前页表格所有实例的当前页的临时数据,通过 id 作为索引,它包含接口返回的原始数据和组件内部的特定字段。 使用该静态属性可对表格数据进行读写操作。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取对应 table 的临时数据
var thisCache = table.cache['test'] || {};
 
// 变更对应 table 的临时数据中的某个字段值
thisCache.fieldName = 123;

重置尺寸

table.resize(id);

  • 参数 id : table 渲染时的 id 属性值

该方法用于重置表格尺寸和结构,其内部完成了固定列高度平铺、动态分配列宽、容器滚动条宽高补丁 等适配。它一般用于修复特殊情况下导致的列宽适配异常(如浏览器窗口尺寸改变导致的表格父容器宽度变化),以保证表格尺寸依旧能友好展示。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 重置对应 table 的尺寸,一般写在表格外部容器宽高发生变化后的段落
table.resize('test');

导出数据

table.exportFile(id, data, opts);

  • 参数 id : table 渲染时的 id 要导出的数据表头(当 idarray 类型时)。
  • 参数 data : 要导出的自定义数据,参数可选。
  • 参数 opts 2.7+: 导出数据时的属性可选项,支持: type,title

该方法用于外部导出对应 table 的数据和任意自定义数据。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 外部导出对应 table 的数据
table.exportFile('test');
 
// 导出自定义数据
table.exportFile(['名字','性别','年龄'], [
  ['张三','男','20'],
  ['李四','女','18'],
  ['王五','女','19']
], {
  type: 'csv', // 导出的文件格式,支持: csv,xls
  title: '导出的文件标题'
}); 

获取配置项 2.8+

table.getOptions(id);

  • 参数 id : table 渲染时的 id 属性值

该方法用于外部获取对应 table 实例的属性配置项。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 获取配置项
var thisOptions = table.getOptions('test');
console.log(thisOptions);

设置列显示或隐藏 2.8+

table.hideCol(id, cols);

  • 参数 id : table 渲染时的 id 属性值
  • 参数 cols : 设置列(表头)显示或隐藏状态

该方法用于外部设置对应 table 列的显示与隐藏状态。

// 渲染
table.render({
  elem: '', // 绑定元素选择器
  id: 'test', // 自定义 id 索引
  // 其他属性 …
});
// 设置对应列的显示或隐藏
table.hideCol('test', {
  field: 'title', // 对应表头的 field 属性值
  hide: true // `true` or `false`
});
// 同时设置多列的显示或隐藏
table.hideCol('test', [{
  field: 'title1',
  hide: true
}, {
  field: 'title2',
  hide: false
}, {
  field: 'title3',
  hide: false
}]);
// 显示或隐藏全部列
table.hideCol('test', false); // `true` or `false`

事件

table.on('event(filter)', callback);

  • 参数 event(filter) 是事件的特定结构。 event 为事件名,支持的事件见下表。filter 为元素属性 lay-filter 对应的值。
  • 参数 callback 为事件执行时的回调函数,并返回一个包含各项成员的 object 类型的参数。
event 描述
toolbar 头部工具栏事件
sort 表头排序切换事件
colTool 2.8.8+ 表头自定义元素工具事件
colResized 2.8+ 列拖拽宽度后的事件
colToggled 2.8+ 列筛选(显示或隐藏)后的事件
row / rowDouble 行单击和双击事件
rowContextmenu 2.8+ 行右键菜单事件
edit 单元格编辑事件
tool / toolDouble 🔥 单元格工具事件。可在该事件中实现行的更新与删除操作。
checkbox 复选框事件
radio 单选框事件
pagebar 2.7+ 尾部分页栏事件

头部工具栏事件

table.on('toolbar(filter)', callback);

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

<!-- 原始容器 -->
<table id="test" 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>
 
<!-- import layui -->
<script>
layui.use(function(){
  var table = layui.table;
  // 渲染
  table.render({
    elem: '#test',
    toolbar: '#toolbarDemo',
    // … // 其他属性
  });
   
  // 头部工具栏事件
  table.on('toolbar(test)', function(obj){
    var options = obj.config; // 获取当前表格属性配置项
    var checkStatus = table.checkStatus(options.id); // 获取选中行相关数据
    console.log(obj); // 查看对象所有成员
    
    // 根据不同的事件名进行相应的操作
    switch(obj.event){ // 对应模板元素中的 lay-event 属性值
      case 'add':
        layer.msg('添加');
      break;
      case 'delete':
        layer.msg('删除');
      break;
      case 'update':
        layer.msg('编辑');
      break;
    };
  });
});
</script>

排序切换事件

table.on('sort(filter)', callback);

点击表头排序时触发,它通常在设置 autoSort: false 基础属性时使用,以呈现后端的排序,而不是默认的前端排序。

var table = layui.table;
 
// 禁用前端自动排序,以便由服务端直接返回排序好的数据
table.render({
  elem: '#test',
  autoSort: false, // 禁用前端自动排序。
  // … // 其他属性
});
 
// 触发排序事件 
table.on('sort(test)', function(obj){
  console.log(obj.field); // 当前排序的字段名
  console.log(obj.type); // 当前排序类型:desc(降序)、asc(升序)、null(空对象,默认排序)
  console.log(this); // 当前排序的 th 对象
 
  // 尽管我们的 table 自带排序功能,但并没有请求服务端。
  // 有些时候,你可能需要根据当前排序的字段,重新向后端发送请求,从而实现服务端排序,如:
  table.reload('test', {
    initSort: obj, // 记录初始排序,如果不设的话,将无法标记表头的排序状态。
    where: { // 请求参数(注意:这里面的参数可任意定义,并非下面固定的格式)
      field: obj.field, // 排序字段
      order: obj.type // 排序方式
    }
  });
});

表头自定义元素工具事件 2.8.8+

table.on('colTool(filter)', callback);

点击表头单元格中带有 lay-event 属性的自定义元素触发,可充分借助该事件扩展 table 更多的操作空间。

var table = layui.table;
 
// 渲染
table.render({
  elem: '#test',
  cols: [[
    {field:'username', title:'用户名 <i class="layui-icon layui-icon-username" lay-event="username"></i>'
  ]]
  // … // 其他属性
});
 
// 表头自定义元素工具事件
table.on('colTool(test)', function(obj){
  var col = obj.col; // 获取当前列属性配置项
  var options = obj.config; // 获取当前表格基础属性配置项
  var layEvent = obj.event; // 获得自定义元素对应的 lay-event 属性值
  console.log(obj); // 查看对象所有成员
});

列拖拽宽度后的事件 2.8+

table.on('colResized(filter)', callback);

在表头列分割线拖拽宽度后触发。

var table = layui.table;
 
// 渲染
table.render({
  elem: '#test',
  // … // 其他属性
});
 
// 列拖拽宽度后的事件
table.on('colResized(test)', function(obj){
  var col = obj.col; // 获取当前列属性配置项
  var options = obj.config; // 获取当前表格基础属性配置项
  console.log(obj); // 查看对象所有成员
});

列筛选(显示或隐藏)后的事件 2.8+

table.on('colToggled(filter)', callback);

点击头部工具栏右上角的字段筛选列表时触发。

var table = layui.table;
 
// 渲染
table.render({
  elem: '#test',
  // … // 其他属性
});
 
// 列筛选(显示或隐藏)后的事件
table.on('colToggled(test)', function(obj){
  var col = obj.col; // 获取当前列属性配置项
  var options = obj.config; // 获取当前表格基础属性配置项
  console.log(obj); // 查看对象所有成员
});

行单击和双击事件

  • 行单击事件:table.on('row(filter)', callback);
  • 行双击事件:table.on('rowDouble(filter)', callback);

单击或双击 table 行任意区域触发,两者用法相同。
2.8.4+:在 table 模板中或任意内部元素中设置 lay-unrow 属性,可阻止该元素执行 row 事件

var table = layui.table;
 
// 渲染
table.render({
  elem: '#test',
  // … // 其他属性
});
 
// 行单击事件
table.on('row(test)', function(obj) {
  var data = obj.data; // 得到当前行数据
  var dataCache = obj.dataCache; // 得到当前行缓存数据,包含特定字段 --- 2.8.8+
  var index = obj.index; // 得到当前行索引
  var tr = obj.tr; // 得到当前行 <tr> 元素的 jQuery 对象
  var options = obj.config; // 获取当前表格基础属性配置项
  var e = obj.e; // 当前的 jQuery 事件对象 --- 2.9.14+
  console.log('onrow', obj); // 查看返回对象的所有成员
  
  // obj.del() // 删除当前行
  // obj.update(fields, related);  // 修改行数据
  // obj.setRowChecked(opts); // 设置行选中状态
});
// 行双击事件
table.on('rowDouble(test)', function(obj) {
  console.log('onrowDouble', obj); // 查看返回对象的所有成员 - 同 row 事件
});

行右键菜单事件 2.8+

table.on('rowContextmenu(filter)', callback);

右键单击行时触发。

  

单元格编辑事件

table.on('edit(filter)', callback);

单元格被编辑,且值发生改变时触发。

var table = layui.table;
var layer = layui.layer;
 
// 单元格编辑事件
table.on('edit(test)', function(obj){
  var field = obj.field; // 得到修改的字段
  var value = obj.value // 得到修改后的值
  var oldValue = obj.oldValue // 得到修改前的值 -- v2.8.0 新增
  var data = obj.data // 得到所在行所有键值
  var col = obj.getCol(); // 得到当前列的表头配置属性 -- v2.8.0 新增
  console.log(obj); // 查看对象所有成员
  
  // 值的校验
  if(value.replace(/\s/g, '') === ''){
    layer.tips('值不能为空', this, {tips: 1});
    return obj.reedit(); // 重新编辑 -- v2.8.0 新增
  }
  // 编辑后续操作,如提交更新请求,以完成真实的数据更新
  // …
  
  // 更新当前缓存数据
  var update = {};
  update[field] = value;
  obj.update(update, true); // 参数 true 为 v2.7 新增功能,即同步更新其他包含自定义模板并可能存在关联的列视图
});

单元格工具事件

  • 单元格工具事件「单击触发」: table.on('tool(filter)', callback);
  • 单元格工具事件「双击触发」: table.on('toolDouble(filter)', callback);

单击或双击单元格中带有 lay-event="" 属性的元素时触发。在表格主体的单元格中,经常需要进行很多的动态操作,比如编辑、删除等操作,这些均可以在单元格工具事件中完成。

<!-- 表头某列 templet 属性指向的模板 -->
<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="test" lay-filter="test"></table> 
 
<!-- import layui -->
<script>
layui.use(function(){
  var table = layui.table;
  // 渲染
  table.render({
    elem: '#test',
    cols: [[
      {title: '操作', width: 200, templet: '#toolEventDemo'}
    ]]
    // … // 其他属性
  });
  // 单元格工具事件
  table.on('tool(test)', function(obj){
    var data = obj.data; // 得到当前行数据
    var dataCache = obj.dataCache; // 得到当前行缓存数据,包含特定字段 --- 2.8.8+
    var index = obj.index; // 得到当前行索引
    var layEvent = obj.event; // 获得元素对应的 lay-event 属性值
    var tr = obj.tr; // 得到当前行 <tr> 元素的 jQuery 对象
    var options = obj.config; // 获取当前表格基础属性配置项
    var col = obj.getCol(); // 得到当前列的表头配置属性 -- v2.8.3 新增
    console.log(obj); // 查看对象所有成员
    
    // 根据 lay-event 的值执行不同操作
    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 新增
      });
      */
    }
  });
});
</script> 

复选框事件

table.on('checkbox(filter)', callback);

当 table 开启复选框,且点击复选框时触发。

var table = layui.table;
 
// 复选框事件
table.on('checkbox(test)', function(obj){
  console.log(obj); // 查看对象所有成员
  console.log(obj.checked); // 当前是否选中状态
  console.log(obj.data); // 选中行的相关数据
  console.log(obj.type); // 若触发的是全选,则为:all;若触发的是单选,则为:one
});

单选框事件

table.on('radio(filter)', callback);

当 table 开启单选框,且点击单选框时触发。

var table = layui.table;
 
// 单选框事件
table.on('radio(test)', function(obj){
  console.log(obj); // 当前行的一些常用操作集合
  console.log(obj.checked); // 当前是否选中状态
  console.log(obj.data); // 选中行的相关数据
});

尾部分页栏事件 2.7+

table.on('pagebar(filter)', callback);

点击尾部分页栏自定义模板中属性为 lay-event="" 的元素时触发。用法跟 toolbar 完全一致。

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

小贴士

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