必须同时修改DOM和table.config.cols才能生效,仅改其一会导致导出、筛选、隐藏列或排序时标题不一致;操作须在render的done回调中进行,并注意多级表头索引及autoSort重绘问题。

只改单个列标题,必须同步 DOM 和 table.config.cols
仅改 $('th[data-field="score"]').text('考评得分') 看似生效,但导出 Excel、列筛选、右键隐藏列仍用旧名;仅改 table.config.cols[0][2].title 又不会刷新页面显示。两者必须同时操作,缺一不可。
实操要点:
- 务必在
table.render()的done回调里执行,确保<th>已挂载 - 推荐用
data-field定位:$('th[data-field="score"]').text('考评得分') - 紧接着同步配置:
table.config.cols[0][2].title = '考评得分'(注意cols[0]是第一组表头,[2]是第 3 列) - 文字变长时加
table.resize()防止截断 - 如果启用了
autoSort: true,点击该列排序图标会重绘<th>并刷回原始标题——因为排序逻辑只读config.cols,不查 DOM
table.reload() 传 cols 会被静默忽略
这是最常踩的坑:table.reload('id', { cols: newCols }) 执行后表头纹丝不动,控制台也无报错。Layui 源码明确跳过 opts.cols 合并逻辑,设计初衷就是“换数据不换结构”。
常见误操作:
- 把列配置写死在
render()里,后续找不到引用,无法复用更新 - 用
map()或解构生成新数组传给reload(),实际改的是副本,不是原始配置 - 以为
table.config.cols = newCols再reload()就行——结果数据重载了,<th>还是旧的
整列结构要变(字段/模板/宽度不同),必须 table.destroy() 后重建
下拉切换“用户视图”和“订单视图”,字段完全不同,就不能只改文字。此时必须销毁旧实例,再用完整新配置重新 render()。
关键动作:
- 先调
table.destroy('userTable'),否则内存泄漏、事件重复绑定 - 新
cols必须是完整二维数组,field、width、templet、toolbar都得带全,不能只写title - 分页状态不继承,需手动恢复:
page: { curr: table.cache['userTable']?.page?.curr || 1, limit: 20 } -
where参数也要显式传入,否则搜索条件丢失
导出 Excel 标题还是旧的?检查 table.config.cols 是否已更新
table.exportFile() 读的是 table.config.cols,不是 DOM。很多人只改了 <th> 文字,导出时标题依旧没变。
排查重点:
- 确认
table.config.cols[0][i].title确实被赋了新值(别漏掉二维索引) - 多级表头(
colspan/rowspan)时,cols是嵌套结构,索引容易算错 - 导出失败或标题错位,优先核对
field是否与后端返回 key 完全一致(大小写、下划线都不能错) - 最容易被忽略的点:改完标题后没同步
config.cols,结果导出、列筛选、右键隐藏列都还用旧名;或者用了autoSort却没意识到点击排序会触发重绘并覆盖你的 DOM 修改


















