表格组件 table

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

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

静态表格是指内容已经存在于页面中的 元素，且可通过一些特定属性设定不同风格。

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

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

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

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

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

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

table.render(options);

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

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

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

table.init(filter, options);

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

属性是指 table 渲染、重载 时的配置选项（options），它本身是一个 object 参数。如：

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

url

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

cols

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

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

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

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

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

false

设置头部工具栏右侧图标。值是一个数组，可选成员有: filter,exports,print （分别代表：筛选图标、导出图标、打印图标）。图标可根据数组值的顺序排列，如：defaultToolbar: ['filter','print','exports'] 支持自定义图标及事件，用法详见示例: #综合演示

height

函数写法 2.9.1+

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

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

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

60

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

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

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

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

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

60

true

false

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

false

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

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

10

[10,…,90]

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

true

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

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

click

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

true

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

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

grid

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

md

是否开启隔行背景。

false

before 2.7+

done

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

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

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

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

请求的方式，默认：get

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

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

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

请求的数据类型，默认 json。

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

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

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

parseData

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

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

该函数非常实用

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

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

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

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

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

设置列的标题。

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

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

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

60

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

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

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

优先级高于 cellExpandedMode 基础属性

设置列类型。可选值有：

normal

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

false

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

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

templet

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

该方式必须在内容中包裹一层 ，否则无法读取模板。

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

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

totalRow

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

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

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

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

edit

函数写法 2.7+

false

是否初始隐藏列

false

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

是否对当前列进行内容编码（转义 html），优先级大于基础属性中的 escape。

true

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

false

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

false

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

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

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

left

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

1

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

1

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

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

table.reload(id, options, deep);

由于 2.6 之前的版本是采用深度重载，所以如果您之前利用了该机制，那么升级 Layui 时，需通过以下任一方式进行相应的兼容性适配：

追加参数兼容：

方法重写兼容。将以下代码放入您的公共 JS 代码中

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

table.reloadData(id, options, deep);

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

table.renderData(id);

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

table.updateRow(id, opts);

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

table.checkStatus(id);

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

table.setRowChecked(id, opts);

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

table.getData(id);

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

var tableCache = table.cache;

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

table.resize(id);

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

table.exportFile(id, data, opts);

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

table.getOptions(id);

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

table.hideCol(id, cols);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

右键单击行时触发。

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

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

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

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

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

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

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

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

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

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