简介layui v2.5.5 是一套面向 Web 前端开发者的开源 UI 框架资源包适合需要快速搭建后台管理界面、企业级中后台系统的初中级开发者使用。它遵循原生 HTML/CSS/JS 规范兼容 jQuery 语法低门槛易上手能有效解决界面组件重复开发、响应式适配繁琐等问题。压缩包共 114 个文件约 615KB以 75 个 gif 图标动效、22 个 js 模块脚本、5 个 css 样式文件为主另含字体图标 ttf、woff、eot、svg 等资源覆盖核心样式、组件模块与图标素材。资源内含表格、表单、弹窗、日期选择、分页等常用组件并附带文档与示例代码便于理解 API 调用与二次开发。目前已有 1221 人学习下载可作为前端项目快速落地的组件库参考。1. 拿到一份 layui-v2.5.5.rar先别急着解压后台管理系统改版产品经理丢过来一个压缩包文件名就一行字layui-v2.5.5.rar。这种场景做前端的人多少都遇到过——不是 npm 装包不是 CDN 引一行链接而是一个实打实的离线包。它解决的是内网环境、老旧项目、或者不想引入构建工具时的 UI 层需求。layui 本身是一套经典模块化前端 UI 框架v2.5.5 属于 2.x 系列里相对稳定的一个版本自带 jQuery、layer 弹层、table 数据表格、form 表单、laydate 日期选择这些高频组件。适合谁适合维护 JSP、Thymeleaf、原生 HTML 后台的开发者也适合刚接手一个没有工程化体系的老系统、需要快速把页面撑起来的人。但拿到 rar 之后第一件事不是双击解压而是先确认版本号和目录结构否则后面引入路径全是坑。2. 解压后先认清目录layui 的模块加载机制与文件构成2.1 为什么 layui 不靠 npm 也能跑layui 的核心设计思路是「模块按需加载 全局注册」。它没有走 ES Module 那套 import/export而是自己实现了一个轻量的模块加载器挂在layui.use()上。你只需要引入一个layui.js和一份layui.css剩下的组件在用到的时候通过layui.use([table, form], function(){...})动态拉取。这也是为什么一个 rar 包就能独立运行——所有模块的 JS 文件都躺在layui/目录下加载器按模块名去对应路径取文件。解压 layui-v2.5.5.rar 之后标准目录结构大致是这样layui-v2.5.5/ ├── layui/ │ ├── css/ │ │ └── layui.css │ ├── font/ │ │ ├── iconfont.eot │ │ ├── iconfont.svg │ │ ├── iconfont.ttf │ │ └── iconfont.woff │ ├── images/ │ │ └── face/ │ ├── layui.js │ └── lay/ │ └── modules/ │ ├── table.js │ ├── form.js │ ├── layer.js │ ├── laydate.js │ ├── laypage.js │ ├── upload.js │ └── ... ├── examples/ └── docs/这里有个关键点layui.js是加载器入口lay/modules/下才是各个组件的实际实现。很多人解压后只把layui.js和layui.css拷进项目结果一调table就报 404就是因为没把lay/modules/整个目录带过去。2.2 最小引入示例与路径参数假设你把整个layui/目录放到了项目的static/下页面里这样写!DOCTYPE html html head meta charsetutf-8 title后台管理/title !-- 引入 layui 样式路径按实际部署调整 -- link relstylesheet href/static/layui/css/layui.css /head body div idapp/div !-- 引入 layui.js它是模块加载器入口 -- script src/static/layui/layui.js/script script // 配置模块基础路径默认就是 layui.js 所在目录 layui.config({ base: /static/layui/lay/modules/ // 模块实际存放路径 }).use([layer, table], function () { var layer layui.layer; var table layui.table; // 弹一个提示验证模块加载成功 layer.msg(layui 模块加载完成); // 渲染一个简单表格 table.render({ elem: #app, cols: [[ { field: id, title: ID, width: 80 }, { field: name, title: 名称, minWidth: 120 } ]], data: [ { id: 1, name: 测试项 A }, { id: 2, name: 测试项 B } ] }); }); /script /body /html逻辑说明layui.config({ base: ... })告诉加载器去哪里找模块文件默认它会以layui.js所在目录为基准去拼lay/modules/。如果你把layui.js和lay/modules/的相对位置改了就必须显式配base否则table.js加载不出来。layui.use([...], callback)里的数组是模块名callback 在所有模块加载完后执行参数顺序和模块名顺序无关统一通过layui.xxx取。参数上要留意base必须以斜杠结尾否则拼接出来的路径会变成.../modules table.js这种错误形式。另外table.render的elem如果指向一个已有内容的容器layui 会直接替换内部 HTML不会追加。2.3 版本确认与兼容性检查v2.5.5 这个版本号不是随便标的。2.5.x 系列对 2.4 之前的 API 做了一些调整比如table模块的page参数结构、layer的btn回调参数顺序。如果你从旧项目迁移过来先打开layui.js顶部注释确认版本/*! * layui v2.5.5 * ... */常见做法是在控制台执行layui.v它会返回当前版本字符串。如果返回undefined说明layui.js没加载成功或者被其他同名变量覆盖了。这一步花十秒钟能省掉后面半小时的「为什么 API 不生效」排查。3. 把 layui 接进真实项目表格渲染、表单监听与弹层联动3.1 table 模块的数据渲染与分页参数后台系统里用得最多的就是数据表格。layui 的table.render支持两种数据模式本地数据data直接给数组和远程数据url给接口地址。远程模式下layui 默认会向接口发送page和limit两个参数并期望返回{ code: 0, msg: , count: 总数, data: [...] }这种结构。layui.use([table], function () { var table layui.table; table.render({ elem: #userTable, url: /api/user/list, // 远程数据接口 method: get, page: true, // 开启分页 limit: 15, // 每页条数 limits: [10, 15, 30, 50], // 每页条数可选值 request: { pageName: pageNum, // 自定义分页参数名默认 page limitName: pageSize // 自定义每页条数参数名默认 limit }, response: { statusCode: 200 // 成功状态码默认 0 }, cols: [[ { type: checkbox, fixed: left }, { field: id, title: ID, width: 80, sort: true }, { field: username, title: 用户名, minWidth: 120 }, { field: status, title: 状态, width: 100, templet: function (d) { return d.status 1 ? 启用 : 禁用; }}, { fixed: right, title: 操作, width: 150, toolbar: #rowBar } ]] }); });逻辑说明request和response这两个配置项是接老接口时的救命参数。很多后端接口的分页字段不叫page/limit返回结构也不是code: 0这时候不改后端就得改前端。templet支持函数和模板字符串两种写法函数方式适合做简单条件渲染复杂结构建议用script typetext/html模板。参数上注意limit和limits要匹配如果limit设了 20 但limits里没有 20分页条上不会高亮当前每页条数。fixed: left或right在列多的时候能固定列但和table.reload配合时偶尔会出现列宽错位这是 2.5.x 的一个已知表现后面避坑章节会细说。3.2 form 模块的表单监听与提交表单这块layui 的form.on(submit(filterName), callback)是标准用法。关键在于lay-filter属性的设置它相当于给表单或按钮起一个标识form.on靠这个标识绑定事件。form classlayui-form lay-filteruserForm div classlayui-form-item label classlayui-form-label用户名/label div classlayui-input-block input typetext nameusername required lay-verifyrequired classlayui-input /div /div div classlayui-form-item label classlayui-form-label角色/label div classlayui-input-block select namerole lay-verifyrequired option value请选择/option option valueadmin管理员/option option valueuser普通用户/option /select /div /div div classlayui-form-item button classlayui-btn lay-submit lay-filterdoSubmit提交/button /div /formlayui.use([form, layer], function () { var form layui.form; var layer layui.layer; // 监听提交doSubmit 对应按钮的 lay-filter form.on(submit(doSubmit), function (data) { // data.field 是表单字段对象 console.log(data.field); // 模拟异步提交 fetch(/api/user/save, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(data.field) }).then(function (res) { return res.json(); }).then(function (ret) { if (ret.code 200) { layer.msg(保存成功, { icon: 1 }); } else { layer.msg(ret.msg || 保存失败, { icon: 2 }); } }); return false; // 阻止表单默认跳转 }); });逻辑说明lay-verifyrequired是内置校验规则提交前 layui 会自动校验并提示。form.on的回调里data.field已经帮你把表单字段整理成对象了不需要手动serialize。return false必须写否则表单会走原生提交导致页面刷新。参数上lay-filter的值要和form.on(submit(xxx))里的xxx完全一致大小写敏感。如果表单里有动态插入的 select 或 checkbox插入后要调form.render(select)或form.render(checkbox)重新渲染否则样式不生效。3.3 layer 弹层与父页面数据回传layer 是 layui 里独立度最高的组件弹层、提示、加载遮罩都用它。常见场景是列表页点「编辑」弹出一个表单层保存后关闭并刷新父页面的表格。// 父页面打开编辑弹层 function openEdit(id) { layui.use([layer], function () { var layer layui.layer; layer.open({ type: 2, // iframe 模式 title: 编辑用户, area: [600px, 400px], content: /user/edit?id id, end: function () { // 弹层关闭后刷新表格 layui.table.reload(userTable); } }); }); } // 子页面保存后关闭自身并回传 layui.use([form, layer], function () { var form layui.form; var layer layui.layer; form.on(submit(saveEdit), function (data) { // ... 提交逻辑 var index parent.layer.getFrameIndex(window.name); // 获取当前 iframe 层索引 parent.layer.close(index); // 关闭自身 return false; }); });逻辑说明type: 2是 iframe 模式适合弹层里放独立表单页。end回调在弹层关闭后触发用来刷新父表格。子页面里parent.layer.getFrameIndex(window.name)是固定写法window.name是 layui 给 iframe 自动分配的标识。参数上area支持像素和百分比但 iframe 模式下高度设百分比有时在低版本浏览器里表现不一致建议用固定像素或[600px, 80%]这种混合写法。end和cancel的区别是end无论怎么关闭都触发cancel只在点右上角关闭按钮时触发。4. 避坑与排查layui 离线包最容易翻车的五个地方4.1 模块 404现象是控制台报lay/modules/xxx.js加载失败原因通常是base路径没配或者配错。layui 默认以layui.js所在目录为基准去拼lay/modules/。如果你把layui.js放在js/下但lay/modules/放在了lib/下加载器就找不到了。解决要么保持layui.js和lay/目录的相对位置不变要么显式layui.config({ base: /实际路径/lay/modules/ })。注意base末尾的斜杠不能省。4.2 表格列宽错位现象是固定列和主体列对不齐这个在 2.5.x 里比较常见尤其是表格容器宽度是百分比、又开了fixed列的时候。原因是 layui 在渲染时计算了一次列宽但容器后续因为滚动条出现或窗口 resize 导致宽度变化固定列没有同步重算。解决给表格外层容器一个明确的宽度或者在table.render的done回调里手动调table.resize()。如果用了table.reload在 reload 的done里也补一次 resize。4.3 表单 select 不显示现象是下拉框样式丢失或点不开动态往表单里插入select后没有重新渲染。layui 的 form 模块在页面初始化时扫描一次表单元素后续动态插入的需要手动触发。解决插入 DOM 后执行form.render(select)。如果是 layui 2.5.5form.render支持传select、checkbox、radio等类型参数不传则全部重渲染。4.4 layer 弹层在 iframe 里被遮挡现象是弹层显示在父页面内容下方原因是 z-index 层级问题。iframe 内部的 layer 默认 z-index 是 19891014但如果父页面有其他元素 z-index 更高或者 iframe 本身被设置了较低的层叠上下文弹层就会「沉下去」。解决在layer.open里显式指定zIndex比如zIndex: 99999999。更稳妥的做法是弹层统一在父页面打开子页面通过parent.layer.open调用。4.5 日期组件 laydate 在弹层里点不开现象是点击输入框无反应laydate 在 iframe 弹层里初始化时如果elem指向的元素在弹层打开前还不存在绑定会失败。另外 laydate 的trigger: click在某些浏览器里和 iframe 焦点机制冲突。解决把 laydate 的初始化放在弹层success回调里确保 DOM 已经渲染。或者改用trigger: focus减少点击事件冲突。5. 进阶技巧用 layui 的模块扩展机制做二次封装5.1 自定义模块的写法与注册layui 允许你扩展自己的模块放在lay/modules/下通过layui.define注册。这样团队里可以把常用的业务组件封装成模块和 layui 原生模块一样用layui.use加载。// lay/modules/myTable.js layui.define([table, layer], function (exports) { var table layui.table; var layer layui.layer; var myTable { // 封装一个带默认配置的表格渲染方法 render: function (options) { var defaults { page: true, limit: 15, text: { none: 暂无数据 } }; var opts Object.assign({}, defaults, options); return table.render(opts); }, // 封装一个删除确认 confirmDelete: function (url, callback) { layer.confirm(确定删除, { icon: 3, title: 提示 }, function (index) { fetch(url, { method: DELETE }).then(function (res) { return res.json(); }).then(function (ret) { if (ret.code 200) { layer.msg(删除成功, { icon: 1 }); callback callback(); } else { layer.msg(ret.msg || 删除失败, { icon: 2 }); } layer.close(index); }); }); } }; exports(myTable, myTable); });逻辑说明layui.define([依赖模块], callback)是模块定义入口exports(模块名, 模块对象)把模块暴露出去。依赖的模块会在 callback 执行前加载好通过layui.xxx取用。参数上模块名要和文件名一致不含.js这样加载器才能按名找到文件。Object.assign做默认配置合并时是浅合并如果options里有嵌套对象需要自己处理深合并。5.2 用 table 的 toolbar 和 templet 做行内操作列表页每行都有「编辑」「删除」按钮用toolbar配置比在templet里拼 HTML 更规范。!-- 行操作模板 -- script typetext/html idrowBar a classlayui-btn layui-btn-xs lay-eventedit编辑/a a classlayui-btn layui-btn-xs layui-btn-danger lay-eventdel删除/a /script// 监听行工具事件 table.on(tool(userTable), function (obj) { var data obj.data; // 当前行数据 var event obj.event; // lay-event 的值 if (event edit) { openEdit(data.id); } else if (event del) { myTable.confirmDelete(/api/user/ data.id, function () { obj.del(); // 删除当前行 DOM }); } });逻辑说明table.on(tool(表格 lay-filter 值))是行工具事件监听obj.data是当前行完整数据obj.del()只删 DOM 不删数据源适合删除成功后做局部刷新。参数上lay-event的值就是obj.event多个按钮用不同值区分。toolbar模板的id要和table.render里toolbar: #rowBar对应。5.3 验证清单上线前我会走一遍的检查项检查项验证方式常见问题模块路径控制台看 Network 有无 404base 未配或末尾缺斜杠表格分页点第二页看请求参数request 字段名和后端不匹配表单校验空提交看提示lay-verify 拼写错误弹层关闭点关闭看父页面是否刷新end 回调未写或 table.reload 的 id 不对日期组件弹层内点击输入框初始化时机早于 DOM 渲染图标显示看按钮图标是否方框font 目录未拷贝或路径不对这份清单是我每次部署 layui 项目前必过的尤其是 font 目录漏拷之后所有图标变成小方框排查起来反而最费时间。从那以后我每次拿到 layui 的离线包都先把layui.js、layui.css、font/、lay/modules/这四样单独拎出来确认一遍再动页面代码。希望帮到你。本文还有配套的精品资源点击获取