Layui 开发常见坑点

SpringBoot + Thymeleaf + Layui 配套开发高频踩坑汇总

一、模块化坑（最常见）

1. 所有组件必须在 layui.use() 内部使用
   ❌ 错误：直接在外部写 var layer = layui.layer;，会报找不到layer
   ✅ 正确：

   layui.use(function(){
   var layer = layui.layer;
   // 所有layer/form/table代码写在这里
   })

原理：layui是按需加载模块，use回调执行后模块才加载完成。

2. 多个模块可以一次性引入

layui.use(['layer','form','laydate'],function(){
    var layer = layui.layer;
    var form = layui.form;
})

二、表单相关坑

1. 表单美化不生效 原因：缺少 class="layui-form" 放在form标签上；或者动态js生成表单后没有重新渲染。

• 静态表单：form必须加 layui-form
• JS动态生成表单元素，必须执行 form.render(); 重新渲染，否则样式失效

form.render(); // 全部表单重新渲染
form.render('select'); // 只刷新下拉框

2. form.on 监听过滤器 lay-filter="xxx" 必须严格匹配

<button lay-submit lay-filter="submitForm">提交</button>

// 引号内必须完全一致，大小写敏感
form.on('submit(submitForm)',function(data){})

3. return false; 不能忘 form提交监听事件不加return false，浏览器会执行表单默认提交，页面直接刷新。

三、选择器、ID坑

1. id不能重复，同一个页面多个DOM不能用相同id，否则table/laydate只识别第一个。
2. layui绑定元素时 elem:"#id"，#后面写元素id，不要写class。

四、table动态表格坑

1. 字段 field 属性必须和数据源里的key大小写完全一致，否则列无数据。

data:[{userName:"张三"}]
cols:[[{field:"username",title:"姓名"}]] // ❌ 大小写不匹配，空

2. 表头cols是二维数组 [[{}]]，外面一层[]代表一个表头行。 ❌ cols:[{field:'id'}] 少一层中括号，表格渲染失败。

五、layer弹窗坑

1. layer.confirm 回调参数index，关闭弹窗必须 layer.close(index) 忘记关闭，弹窗会堆积。
2. layer.msg默认3秒自动消失；如果想手动关闭，可设置时间 layer.msg('提示',{time:0})
3. 弹窗内的表单，点击事件失效：弹窗DOM是动态追加，直接绑定onclick会失效，需要事件委托。

六、静态资源路径 + Thymeleaf搭配坑

1. layui的css/js是静态资源，放在 resources/static，不能放在templates templates文件夹是thymeleaf模板目录，不能直接访问静态文件。
2. 使用Thymeleaf引入layui资源，推荐用 th:href / th:src

<link rel="stylesheet" th:href="@{/layui/css/layui.css}">
<script th:src="@{/layui/layui.js}"></script>

@{} 自动适配项目上下文路径，部署项目不容易404。

七、栅格布局坑

• layui-col-md* 必须包裹在 layui-row 里面，否则栅格失效。
• md代表大屏PC；如果需要手机适配，可以加上 xs sm 等多尺寸。

<div class="layui-row">
    <div class="layui-col-md6 layui-col-xs12">大屏半宽，手机占满</div>
</div>

八、laydate日期选择器坑

1. 绑定的elem必须是输入框，或者可点击元素。
2. 同一个页面多个日期框，id不能重复。
3. 动态生成的输入框，必须在DOM生成完成后，再执行laydate.render。

九、事件绑定时机坑

页面DOM还没加载完成就执行js，获取不到元素。

• 把script代码放在页面body最末尾（推荐）
• 或者原生js用DOMContentLoaded等待页面加载完毕

十、样式冲突问题

1. 自己写的css选择器优先级太高，覆盖layui自带样式，导致按钮、表单样式错乱。
2. layui引入顺序：先引入layui.css，再引入自己写的css。

十一、版本与CDN坑

CDN地址版本不对会出现组件缺失。 当前稳定版本CDN：

<link rel="stylesheet" href="[https://cdn.jsdelivr.net/npm/layui-src@2.9.6/dist/css/layui.css](https://cdn.jsdelivr.net/npm/layui-src@2.9.6/dist/css/layui.css)">
<script src="[https://cdn.jsdelivr.net/npm/layui-src@2.9.6/dist/layui.js](https://cdn.jsdelivr.net/npm/layui-src@2.9.6/dist/layui.js)"></script>

十二、其他小坑

1. 中文乱码：页面头部设置 <meta charset="UTF-8">
2. 表单提交拿到的数据 data.field 里面的key，等于表单元素的name属性，不是id！

<input name="realName" id="rName" class="layui-input">
<!-- data.field.realName 取值，不是 rName -->

3. layui不支持IE低版本，项目如果需要兼容老旧浏览器不要使用。