layui table复杂表头 layui多级表头如何实现

layui table 原生不支持多级表头，cols 仅识别单层数组，跨行/跨列需在 done 回调中用 jQuery 手动重写 thead 并保留 data-field 属性，否则排序、导出等功能异常。

layui table 的 cols 原生配置无法支持多级表头

在 layui 2.8.x 及更早版本的 table.render() 中，cols 采用二维数组结构，虽然表面上可以嵌套，实际上却只把第一层，也就是最外层数组识别成“行”；内层数组则会作为“同一行的列”直接展开。它根本不具备「跨行/跨列」的语义解析能力，因此所谓“复杂表头”只能通过手动干预 dom 或 hack 渲染流程来实现。

常见错误现象：cols: [[{title: '用户'}, [{field: 'name'}, {field: 'age'}]], [{title: '订单'}, [{field: 'id'}, {field: 'amount'}]]] 这种写法看似分组，结果是表头只渲染出 4 列，且所有 title 全丢，因为 layui 把内层数组当成了无效配置直接跳过。

• 真正能起作用的只有形如 cols: [[{title: '用户信息', colspan: 2}, {title: '订单信息', colspan: 2}], [{field: 'name'}, {field: 'age'}, {field: 'id'}, {field: 'amount'}]] 的结构（注意：这是伪代码，layui 原生不认 colspan）
• 因此，你看到的“多级表头”几乎都是后续借助 jQuery 操作 <th> 的 colspan/rowspan 属性强制调整出来的
• 若表格启用了 height 或 scrollbar，手动修改 DOM 后还需要主动调用 table.resize()，不然表体列宽会出现错位

采用 done 回调配合 jQuery 重写 <thead>

目前兼容性最好且最稳定的方式是：先等待 layui 完成默认单层表头的渲染，再通过 done 钩子将 <thead> 整体替换为手写的 HTML 结构。需要特别注意，原始列的 data-field 和 data-key 属性必须保留，否则筛选、排序和导出功能都会失效。

适用场景包括：需要 2 级及以上表头，例如「部门 → 员工姓名 / 入职时间」或「财务 → 应收 / 实收」，并且还要确保 layui 的交互功能能够正常使用。

• 在 table.render() 配置中加入 done: function(res, curr, count) { ... }
• 先通过 $('table[lay-id="yourTableId"] thead') 找到目标表头容器
• 构造新 HTML 字符串，例如：<tr><th colspan="2">用户</th><th colspan="2">订单</th></tr><tr><th data-field="name">姓名</th><th data-field="age">年龄</th><th data-field="id">ID</th><th data-field="amount">金额</th></tr>
• 执行 $thead.html(newHtml) 替换，然后立刻调用 table.resize('yourTableId')

注意 data-field 必须与原始列定义完全一致

layui 表格内部靠 data-field 绑定数据字段和列行为。如果你在重写的 <th> 里漏了这个属性，或者拼写大小写不一致（比如原始是 userName，你写了 username），点击列排序会报错 Uncaught TypeError: Cannot read property 'sort' of undefined，导出 Excel 时该列数据为空，甚至 checkbox 全选逻辑也会异常。

性能方面，这种 DOM 替换是在渲染结束后执行的，因此不会影响首屏时间；不过每次调用 table.reload() 以后，done 都会再次触发，所以重写逻辑必须保证幂等，例如先清空再写入，或者先判断自定义结构是否已经存在。

• 检查时可右键单击表头并选择“检查元素”，确认每个 <th> 均有 data-field，并且其值与 cols 中相应列的 field 保持完全相同
• 如果列使用了 templet 或 toolbar，相应 <th> 的 data-field 应设置为 '' 或唯一字符串，例如 action，同时在 cols 中保持一致
• 不要为合并单元格的 <th> 添加 data-field，例如「用户信息」这一总标题，否则 layui 会尝试绑定数据，进而造成错乱

layui 3.0 仍未发布，不要等待“官方支持”

社区经常有人询问“新版会不会原生支持”，但实际情况是 layui 官方 GitHub 已经接近 2 年没有实质性更新，3.0 仍停留在“传闻中”。任何依赖“未来版本修复”的方案，都会耽误当前项目的推进。

还有一个容易忽略的问题：合并表头以后，列宽拖拽调整和固定列（fixed: 'left'）可能失效或发生错位。这并不是 bug，而是因为 layui 的列宽计算完全依据单层 cols 进行推导，强行修改 DOM 后，它无法识别真实结构。若业务高度依赖列宽调整和固定列，建议不要使用多级表头，可改为卡片式布局，或利用折叠面板对数据进行分组展示。