Layui快速入门之第八节表格渲染与属性的使用

API	描述
var table = layui.table	获得 `table` 模块。
table.render(options)	table 组件渲染，核心方法。
table.init(filter, options)	初始化渲染静态表格。
table.reload(id, options, deep)	表格完整重载。
table.reloadData(id, options, deep) 2.7+	表格数据重载。
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 相关事件。

渲染

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

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

方法配置渲染

table.render(options);

参数 options : 基础属性配置项。#详见属性

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

<table id="test"></table>
 
<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>
 
<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` 属性只能二选一。	array	-
id	设定实例唯一索引，以便用于其他方法对 table 实例进行相关操作。若该属性未设置，则默认从 `elem` 属性绑定的原始 table 元素中的 `id` 属性值中获取。	string	-
toolbar	开启表格头部工具栏。支持以下几种值写法： `toolbar: '#template-id'` 自定义工具栏模板选择器 `toolbar: '<div>xxx</div>` 直接传入模板字符 `toolbar: true` 仅开启工具栏右侧，不显示左侧模板 `toolbar: 'default'` 开启工具栏并显示默认模板	string boolean	`false`
defaultToolbar	设置头部工具栏右侧图标。值是一个数组，可选成员有: `filter,exports,print` （分别代表：筛选图标、导出图标、打印图标）。图标可根据数组值的顺序排列，如：`defaultToolbar: ['filter','print','exports']` 支持自定义图标及事件，用法详见示例: #综合演示	array	-
width	设置容器宽度，默认自适应。	number	-
height	设置表格容器高度，默认自适应。其他可选值的规则如下： `height: 315` 设置固定高度 `height: 'full-30'` 设置自适应高度。这是一个特定的语法格式：`full` 表示铺满；后面的数字表示当前 table 之外的元素占用的高度，如：表格头部到页面最顶部加表格底部距离页面最底部的“距离和” `height: '#id-30'` 设置相对父元素的高度自适应，其中 `#id` 即父元素的 ID 选择器，其计算原理和上述 `full` 相同。	number string	-
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	-
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	是否显示加载条。若为 `false`，则在切换分页时，不会出现加载条。必须设置了 `url` 属性才生效。	boolean	`true`
scrollPos 2.7+	用于设置重载数据或切换分页时的滚动条位置状态。可选值： `fixed` 重载数据时，保持滚动条位置不变 `reset` 重载数据时，滚动条位置恢复置顶 `default` 默认方式，无需设置。即重载数据或切换分页时，纵向滚动条置顶，横向滚动条位置不变。	string	-
editTrigger 2.7+	是用于设定单元格编辑的事件触发方式。如双击: `dblclick`	string	`click`
title	定义 table 的大标题（在文件导出等地方会用到）	string	-
text	自定义文本，如空数据时的异常提示等。	object	查看默认值
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+	数据渲染之前的回调函数。	function	-
done	数据渲染完毕的回调函数。返回的参数如下： `table.render({` `done: function(res, curr, count){` `console.log(res); // 得到当前渲染的数据` `console.log(curr); // 得到当前页码` `console.log(count); // 得到数据总量` `}` `// … // 其它属性` `});`	function	-
error 2.6+	数据请求失败的回调函数。返回两个参数：错误对象、内容。	function	-

异步属性

异步属性本质也是基础属性，当开启 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	-
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();` `}`	string function	-
totalRow	是否开启该列的自动合计功能。前端合计 `totalRow: true // 开启合计行，并默认对当前所有行数据进行前端合计` 后端合计前端合计的数据有限，因此常常需要后端直接返回合计行结果，此时将优先读取后端的合计行返回结果，其格式如下： `{` `"code": 0,` `"totalRow": {` `"score": "777",` `"experience": "999"` `},` `"data": [{}, {}],` `"msg": "",` `"count": 1000` `}` 如上，在 `totalRow` 中返回所需统计的列字段名和值即可。 `totalRow` 字段同样可以通过 `parseData` 回调来解析成为 table 组件所规定的数据格式。合计行模板 `totalRow: '{ {= d.TOTAL_NUMS }} 单位' // 还比如只取整：'{ {= parseInt(d.TOTAL_NUMS) }}'`	boolean string	`false`
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`
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。
2.6 之前版本的 table.reload() 方法兼容性说明

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

// 渲染

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 // 高度 --- 属性设置无效，因不属于数据相关属性

});

获取选中行

table.checkStatus(id);

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

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

// 渲染

table.render({

elem: '', // 绑定元素选择器

id: 'test', // 自定义 id 索引

// 其他属性 …

});

// 获取选中行相关数据

var tableStatus = table.checkStatus('test');

console.log(checkStatus.data) // 选中行的数据

console.log(checkStatus.data.length) // 选中行数量，可作为是否有选中行的条件

console.log(checkStatus.isAll ) // 表格是否全选

设置行选中状态 2.8+

table.setRowChecked(id, opts);

参数 id : table 渲染时的 id 属性值
参数 opts : 设置行选中时的可选属性，详见下表

opts	描述	类型	默认值
type	选中方式。可选值: `checkbox,radio`	string	`checkbox`
index	选中行的下标。即数据的所在数组下标（`0` 开头）。可设置 `all` 表示全选。	number string	-
checked	选中状态值。若为 `false` 可取消选中。	boolean	`true`
selectedStyle	是否仅设置样式状态。若为 `true` 则只标注选中样式，不对数据中的 `LAY_CHECKED` 属性赋值。	boolean	`false`

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

// 渲染

table.render({

elem: '', // 绑定元素选择器

id: 'test', // 自定义 id 索引

// 其他属性 …

});

// 设置某行选中

table.setRowChecked('test', {

index: 0, // 选中行的下标。 0 表示第一行

});

// 取消选中行

table.setRowChecked('test', {

index: 'all', // 所有行

checked: false

});

获取当前页接口数据

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 或要导出的数据表头（当 id 为 array 类型时）。
参数 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`

});