LayUI-06-摩杜云开发者社区

4.3 数据表格table

是 layui 最核心的组成之一。它用于对表格进行一些列功能和动态化数据操作，涵盖了日常业务所涉及的几乎全部需求。支持固定表头、固定行、固定列左/列右，支持拖拽改变列宽度，支持排序，支持多级表头，支持单元格的自定义模板，支持对表格重载（比如搜索、条件筛选等），支持复选框，支持分页，支持单元格编辑等等一些列功能

4.3.1 快速使用

创建一个table实例最简单的方式是，在页面放置一个元素，然后通过 table.render() 方法指定该容器，如下所示：

<!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: '/demo/table/user/' //数据接口
    ,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: 'wealth', title: '财富', width: 135, sort: true}
    ]]
  });
  
});
</script>
</body>
</html>

4.3.2 表格渲染

三种初始化渲染方式

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

4.3.2.1 方法渲染

其实这是“自动化渲染”的手动模式，本质类似，只是“方法级渲染”将基础参数的设定放在了JS代码中，且原始的 table 标签只需要一个 选择器：

<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' //指定原始表格元素选择器（推荐id选择器）
  ,height: 315 //容器高度
  ,cols: [{}] //设置表头
  //,…… //更多参数参考右侧目录：基本参数选项
});
});
</script>

事实上我们更推荐采用“方法级渲染”的做法，其最大的优势在于你可以脱离HTML文件，而专注于JS本身。尤其对于项目的频繁改动及发布，其便捷性会体现得更为明显。而究竟它与“自动化渲染”的方式谁更简单，也只能由各位猿猿们自行体味了。

备注：table.render()方法返回一个对象：var tableIns = table.render(options)，可用于对当前表格进行“重载”等操作

4.3.2.2 自动渲染

即：在一段 table 容器中配置好相应的参数，由 table 模块内部自动对其完成渲染，而无需你写初始的渲染方法。其特点在上文也有阐述。你需要关注的是以下三点：

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

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

<table class="layui-table" lay-data="{height:315, url:'/demo/table/user/', 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:'wealth', sort: true}">财富</th>
    </tr>
  </thead>
</table>

4.3.2.3 静态表格渲染

假设你的页面已经存在了一段有内容的表格，它由原始的table标签组成，这时你需要赋予它一些动态元素，比如拖拽调整列宽？比如排序等等？那么你同样可以很轻松地去实现。如下所示：

转换后

<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>

<script src="/layui/layui.js"></script>
<script>
layui.use('table', function(){
var table = layui.table;

 
//转换静态表格
table.init('demo', {
  height: 315 //设置高度
  ,limit: 10 //注意：请务必确保 limit 参数（默认：10）是与你服务端限定的数据条数一致
  //支持所有基础参数
}); 
});
</script>

4.3.3 基础参数

基础参数并非所有都要出现，有必选也有可选，结合你的实际需求自由设定。基础参数一般出现在以下几种场景中：

场景一：下述方法中的键值即为基础参数项
table.render({
  height: 300
  ,url: '/api/data'
});
       
场景二：下述 lay-data 里面的内容即为基础参数项，切记：值要用单引号
<table lay-data="{height:300, url:'/api/data'}" lay-filter="demo"> …… </table>
 
更多场景：下述 options 即为含有基础参数项的对象
> table.init('filter', options); //转化静态表格
> var tableObj = table.render({});
  tableObj.reload(options); //重载表格

下面是目前 table 模块所支持的全部参数一览表，我们对重点参数进行了的详细说明，你可以点击下述表格最右侧的“示例”去查看

参数	类型	说明	示例值
elem	String/DOM	指定原始 table 容器的选择器或 DOM，方法渲染方式必填	"#demo"
cols	Array	设置表头。值是一个二维数组。方法渲染方式必填	详见表头参数
url（等）	-	异步数据接口相关参数。其中 url 参数为必填项	详见异步接口
toolbar	String/DOM/Boolean	开启表格头部工具栏区域，该参数支持四种类型值：toolbar: '#toolbarDemo' //指向自定义工具栏模板选择器toolbar: '<div>xxx</div>' //直接传入工具栏模板字符toolbar: true //仅开启工具栏，不显示左侧模板toolbar: 'default' //让工具栏左侧显示默认的内置模板注意： 1. 该参数为 layui 2.4.0 开始新增。 2. 若需要“列显示隐藏”、“导出”、“打印”等功能，则必须开启该参数	false
defaultToolbar	Array	该参数可自由配置头部工具栏右侧的图标按钮	详见头工具栏图标
width	Number	设定容器宽度。table容器的默认宽度是跟随它的父元素铺满，你也可以设定一个固定值，当容器中的内容超出了该宽度时，会自动出现横向滚动条。	1000
height	Number/String	设定容器高度	详见height
cellMinWidth	Number	（layui 2.2.1 新增）全局定义所有常规单元格的最小宽度（默认：60），一般用于列宽自动分配的情况。其优先级低于表头参数中的 minWidth	100
done	Function	数据渲染完的回调。你可以借此做一些其它的操作	详见done回调
data	Array	直接赋值数据。既适用于只展示一页数据，也非常适用于对一段已知数据进行多页展示。	[{}, {}, {}, {}, …]
totalRow	Boolean	是否开启合计行区域。layui 2.4.0 新增	false
page	Boolean/Object	开启分页（默认：false）注：从 layui 2.2.0 开始，支持传入一个对象，里面可包含 laypage 组件所有支持的参数（jump、elem除外）	{theme: '#c00'}
limit	Number	每页显示的条数（默认：10）。值务必对应 limits 参数的选项。注意：优先级低于 page 参数中的 limit 参数	30
limits	Array	每页条数的选择项，默认：[10,20,30,40,50,60,70,80,90]。注意：优先级低于 page 参数中的 limits 参数	[30,60,90]
loading	Boolean	是否显示加载条（默认：true）。如果设置 false，则在切换分页时，不会出现加载条。该参数只适用于 url 参数开启的方式	false
title	String	定义 table 的大标题（在文件导出等地方会用到）layui 2.4.0 新增	"用户表"
text	Object	自定义文本，如空数据时的异常提示等。注：layui 2.2.5 开始新增。	详见自定义文本
autoSort	Boolean	默认 true，即直接由 table 组件在前端自动处理排序。若为 false，则需自主排序，通常由服务端直接返回排序好的数据。注意：该参数为 layui 2.4.4 新增	详见监听排序
initSort	Object	初始排序状态。用于在数据表格渲染完毕时，默认按某个字段排序。	详见初始排序
id	String	设定容器唯一 id。id 是对表格的数据操作方法上是必要的传递条件，它是表格容器的索引，你在下文诸多地方都将会见识它的存在。值得注意的是：从 layui 2.2.0 开始，该参数也可以自动从 ** 中的 id 参数中获取。	test
skin（等）	-	设定表格各种外观、尺寸等	详见表格风格

4.3.4 表头参数

如果你采用的是方法渲染，cols 是一个二维数组，表头参数设定在数组内；如果你采用的自动渲染，表头参数的设定应放在th标签上

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

totalRow	Boolean/Object	是否开启该列的自动合计功能，默认：false。当开启时，则默认由前端自动合计当前行数据。从 layui 2.5.6 开始：若接口直接返回了合计行数据，则优先读取接口合计行数据，格式如下：`codelayui.code{ "code": 0, "msg": "", "count": 1000, "data": [{}, {}] "totalRow": { "score": "666" ,"experience": "999" }}`如上，在 totalRow 中返回所需统计的列字段名和值即可。另外，totalRow 字段同样可以通过 parseData 回调来解析成为 table 组件所规定的数据格式。	true
totalRowText	String	用于显示自定义的合计文本。layui 2.4.0 新增	"合计："
sort	Boolean	是否允许排序（默认：false）。如果设置 true，则在对应的表头显示排序icon，从而对列开启排序功能。注意：不推荐对值同时存在“数字和普通字符”的列开启排序，因为会进入字典序比对。比如：'贤心' > '2' > '100'，这可能并不是你想要的结果，但字典序排列算法（ASCII码比对）就是如此。	true
unresize	Boolean	是否禁用拖拽列宽（默认：false）。默认情况下会根据列类型（type）来决定是否禁用，如复选框列，会自动禁用。而其它普通列，默认允许拖拽列宽，当然你也可以设置 true 来禁用该功能。	false
edit	String	单元格编辑类型（默认不开启）目前只支持：text（输入框）	text
event	String	自定义单元格点击事件名，以便在 tool 事件中完成对该单元格的业务处理	任意字符
style	String	自定义单元格样式。即传入 CSS 样式	background-color: #5FB878; color: #fff;
align	String	单元格排列方式。可选值有：left（默认）、center（居中）、right（居右）	center
colspan	Number	单元格所占列数（默认：1）。一般用于多级表头	3
rowspan	Number	单元格所占行数（默认：1）。一般用于多级表头	2
templet	String	自定义列模板，模板遵循 laytpl 语法。这是一个非常实用的功能，你可借助它实现逻辑处理，以及将原始数据转化成其它格式，如时间戳转化为日期字符等	详见自定义模板
toolbar	String	绑定工具条模板。可在每行对应的列中出现一些自定义的操作性按钮	详见行工具事件

//方法渲染：
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>

4.3.5 异步数据接口

数据的异步请求由以下几个参数组成：

参数名	功能
url	接口地址。默认会自动传递两个参数：?page=1&limit=30（该参数可通过 request 自定义） page 代表当前页码、limit 代表每页数据量
method	接口http请求类型，默认：get
where	接口的其它参数。如：where: {token: 'sasasas', id: 123}
contentType	发送到服务端的内容编码类型。如果你要发送 json 内容，可以设置：contentType: 'application/json'
headers	接口的请求头。如：headers: {token: 'sasasas'}
parseData	数据格式解析的回调函数，用于将返回的任意数据格式解析成 table 组件规定的数据格式。table 组件默认规定的数据格式为（参考：/demo/table/user/）

很多时候，您接口返回的数据格式并不一定都符合 table 默认规定的格式，比如：
{
  "status": 0,
  "message": "", 
  "total": 180, 
  "data": {
    "item": [{}, {}]
  }
}
那么你需要借助 parseData 回调函数将其解析成 table 组件所规定的数据格式。转换为标准格式
{
  "code": 0,
  "msg": "",
  "count": 1000,
  "data": [{}, {}]
} 
------------------------------------------------------------------------------

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