Layui layer 弹层上手指南：5 类弹层场景一次讲清

Layui layer 弹层上手指南：5 类弹层场景一次讲清

【免费下载链接】layui一套遵循浏览器原生态开发模式的 Web UI 组件库。项目地址: https://gitcode.com/GitHub_Trending/la/layui

layer 是 Layui 内置的通用弹出层组件，一个模块覆盖提示、确认、加载、图片预览和自定义弹窗 5 类弹层场景，全部基于原生 JavaScript，不依赖其他框架。本文按"你要完成什么"来讲：先查能力表，再选 API，最后看配置和管理。

能力速查

常见需求都能对上 6 个 API，按场景查表即可：

6 个 API 中只有layer.open需要传配置对象，其余都是快捷写法，底层最终都走open，实现逻辑见 layer 组件源码。

选型建议

选 API 的原则：能用快捷方法就不用open，能传time自动关闭就不手动关。

• layer.msg：一句话提示，3 秒自动消失。不要用它：需要用户点按钮的场景，它没有按钮。
• layer.alert：只需一个"知道了"的确认框。不要用它：需要"确定/取消"两个出口时，改用confirm。
• layer.confirm：有取舍的操作（删除、退出）。不要用它：纯信息通知，两个按钮反而增加点击成本。
• layer.load：请求期间的等待指示。不要用它：内容等待超过 10 秒还不确定的长流程，应改用带进度反馈的方案。
• layer.open：以上都不满足时的兜底，传完整配置。不要用它：一句话提示，msg一行代码的事。
• layer.photos：图片查看，支持上一张/下一张。不要用它：视频、PDF 等非图片内容。

layer.open 核心参数

layer.open是配置入口，日常 8 个参数覆盖绝大多数需求，其余参数保持默认即可：

最常用的组合——打开一个 500×300 的自定义弹窗：

var index = layer.open({ type: 1, title: '编辑用户', area: ['500px', '300px'], content: '<div>表单内容</div>', btn: ['确定', '取消'], success: function (layero) { /* 拿到弹层节点 */ } });

位置与动画

offset和anim控制弹层"出现在哪、怎么出现"，常用值各一列，记不住就回默认值。

offset：'auto'（居中，默认）、'lt'左上、'rt'右上、'lb'左下、'rb'右下，也可传[top, left]数组精确控制，例如['100px', '20px']。

anim：0 默认淡入、1 从顶部向下滑入、2 从底部向上滑入、3 从右侧滑入、4 顶部缩放、5 左半圆翻转、6 右半圆翻转。

layer.open({ title: '通知', content: '内容', offset: 'rt', // 右上角 anim: 3 // 从右侧滑入 });

多弹层生命周期管理

layer 给每个弹层发一个自增index，这是后续一切操作的句柄；layer.index始终指向最新打开的弹层，新弹层会自动叠在旧弹层之上，层级无需手动维护。

var idx = layer.open({ title: '外层' }); layer.open({ title: '内层' }); // layer.index 指向它 layer.closeLast(); // 只关最近打开的内层 layer.close(idx); // 按句柄关外层 layer.closeAll(); // 清空页面上所有弹层

setTop(layero)用于把某个弹层重新提到最前，一般只在success回调里配合特殊层级需求时使用。

避坑指南

高频问题只有 3 个，按"现象 + 做法"对照处理即可。

1. 弹层被其他元素遮挡：layer 的zIndex默认 19891014 且随 index 自动递增，多数遮挡是页面里某个元素自己写了更高的 z-index。做法：先检查遮挡元素的层级，确属必要才在success里补一句layer.setTop(layero)，不要随手把zIndex改成 99999 这种和默认量级不匹配的值。

2. 移动端弹层超出屏幕：area写死像素值在小屏上会溢出。做法：宽度改用百分比，高度保持auto：

layer.open({ area: ['90%', 'auto'], content: '内容自适应' });

3. 关闭后资源没清干净：弹层只是容器，你在success里创建的定时器、绑定到弹层内节点的事件不会随关闭自动消失，反复开关就会堆积。做法：把清理动作放进end回调（关闭后触发），它和success一开一关正好配对：

layer.msg('处理中', { time: 0, end: function () { console.log('弹层已移除') } });

样式层面的定制（圆角、配色等）改 layer 样式文件 或给skin加自己的类，不要直接覆写默认皮肤。

延伸资源

• 组件实现：src/components/layer.js，约 2200 行，open、close、setTop的完整逻辑都在这里
• 样式定义：src/css/modules/layer.css，弹层皮肤与动画类（layer-anim-00到layer-anim-06）
• 本地示例页：tests/visual/layer.html，可对照本文各节效果自查

【免费下载链接】layui一套遵循浏览器原生态开发模式的 Web UI 组件库。项目地址: https://gitcode.com/GitHub_Trending/la/layui