Layui layer 弹层速查:5 种类型 + 1 张配置表,快速搞定前端弹窗
【免费下载链接】layui 一套遵循浏览器原生态开发模式的 Web UI 组件库。 项目地址: https://gitcode.com/GitHub_Trending/la/layui
后台系统里有个绕不开的矛盾:操作结果必须让用户看见,又不能打断他正在做的填写。原生 alert 会阻塞脚本,自己写固定定位的 div 又要操心遮罩、层级、关闭按钮和焦点管理。Layui 的 layer 弹层组件把这层交互封装成了一个模块,原生 JavaScript 实现,弹层 DOM 在打开时才创建、关闭时移除,拿到 index 就能管理任意一个弹层。
一张表看懂 layer 的五种弹层类型
layer 的 type 配置定义了五种基础模式(源码里就这一行:type: ['dialog', 'page', 'iframe', 'loading', 'tips']),覆盖绝大多数弹窗诉求:
| 类型 | type | 适用场景 | 一句话说明 |
|---|---|---|---|
| dialog 对话框 | 0 | 信息提示、二次确认 | 默认类型,可带图标和底部按钮 |
| page 页面层 | 1 | 展示一段 HTML 或页面内已有元素 | content 可以是字符串,也可以是指向 DOM 的选择器 |
| iframe 层 | 2 | 在弹窗里嵌入一个独立页面 | content 直接传页面地址 |
| loading 加载层 | 3 | 异步请求期间的等待反馈 | 默认极淡遮罩 + 旋转图标,不打断视线 |
| tips 提示层 | 4 | 指向某个元素的小气泡 | 自动计算方位,带箭头跟随目标 |
在五种基础类型之上还有几个开箱即用的扩展方法:layer.prompt(输入框)、layer.tab(选项卡层)、layer.photos(图片浏览层)。
30 秒跑通第一个弹层
先引入模块,再调三件套。layer 内置的 alert / confirm / msg 三个快捷方法,本质都是 layer.open 的预设配置:
var layer = layui.layer;
// 单按钮对话框,点“确定”自动关闭
layer.alert('操作成功!');
// 双按钮确认框,yes 回调里必须手动关闭
layer.confirm('确定删除这条记录吗?', function (index) {
layer.close(index); // 关闭当前弹层
});
// 无遮罩的轻提示,默认 3 秒后自动消失
layer.msg('保存成功', { icon: 1 });
三种都返回值是弹层 index,后续任何管理操作都靠它。完整可运行的按钮演示仓库里就有,直接打开 tests/visual/layer.html 就能点到每种类型。
三个业务场景实战
场景一:删除前的操作确认
问题:危险操作需要二次确认,还要防止用户连点导致重复提交。
layer.confirm('删除后不可恢复,确定执行吗?', {
btn: ['删除', '取消'], // 自定义按钮文案
}, function (index, layero) {
layer.close(index); // 先关弹层,再发请求
fetch('/api/del', { method: 'POST' }).then(function () {
layer.msg('已删除', { icon: 1 });
});
});
注意点:yes 回调不会自动关闭弹层,必须显式 layer.close(index),否则弹层残留在页面上。
场景二:异步请求的加载遮罩
问题:等待期间既要挡住重复操作,又不能黑得太实。
// 返回 index;shade 0.1 表示 10% 不透明度的遮罩
var loadIndex = layer.load(0, { shade: 0.1 });
fetch('/api/list')
.then(function (res) { return res.json(); })
.finally(function () {
layer.close(loadIndex); // 无论成败都关闭
});
注意点:关闭动作放在 finally 里,请求失败时遮罩才不会卡死在页面上。type 3 的层打开时会先关掉已有的 loading 层,连续发请求不会叠出一堆。
场景三:用 iframe 层嵌入内容
问题:弹层里要嵌一个独立的页面,又不想自己处理 iframe 尺寸。
var index = layer.open({
type: 2, // iframe 层
title: '订单详情',
area: ['80%', '90%'], // 相对视口的宽高
content: '/order/detail.html',
});
// 不重建弹层,只换里面的页面地址
layer.iframeSrc(index, '/order/detail.html?id=1024');
注意点:type 2 时 content 是字符串的话,它会被当作 iframe 的 src。后续换页用 layer.iframeSrc,比重开一个弹层便宜。
layer.open 常用配置项速查
| 配置项 | 默认值 | 说明 |
|---|---|---|
| type | 0 | 弹层类型:0 对话框 / 1 页面 / 2 iframe / 3 loading / 4 tips |
| content | - | 内容字符串、选择器或 iframe 地址(type 2) |
| title | 提示 | 标题栏文字,传 false 可隐藏 |
| area | auto | 宽高,如 ['80%', '500px'],支持百分比与 auto |
| shade | 0.3 | 遮罩透明度;[0.1, '#fff'] 可改颜色;false 关闭 |
| offset | auto | 定位:auto 居中,t / b / l / r / lt / rb 等方位,也支持 ['50px', '80px'] |
| anim | 0 | 弹窗动画,数字 0~6 或 slideDown / slideLeft 等滑入方向 |
| time | 0 | 毫秒数,到期自动关闭;0 表示不自动关 |
| zIndex | 19891014 | 层级基准,每开一个弹层自动叠加 index |
| btn | 确定 | 底部按钮文案数组,如 ['提交', '取消'] |
| btnAsync | false | true 时按钮回调支持 Promise,返回 false 则不关闭 |
| success / end | - | 打开后 / 关闭后的回调,拿 layero 和 index |
| id + hideOnClose | - | 配 id 防止重复弹出;hideOnClose 关闭时只隐藏不销毁,复用好 |
| maxmin | false | 打开最小化 / 最大化按钮(type 1、2 生效) |
踩坑指南:三个高频问题
Q:弹层被遮挡怎么办?
先看页面里有没有人给其他元素写了超大的 z-index 和 position,这是最常见的根源。layer 自身已按 zIndex + index 自动递增,正常打开的弹层不会互相压。确需把某个弹层提到最前,在 success 回调里调用 layer.setTop(layero),它会监听 mousedown 持续置顶。
Q:弹层没关闭,页面上残留了一堆?
layer 没有兜底的自动关闭机制:每个需要用户手动关闭的弹层,都要在回调里显式 layer.close(index),否则 DOM 和事件监听都会留在页面上。补救手段:layer.closeLast('dialog') 关最近打开的对话框,layer.closeAll('loading') 清空某类型全部弹层,time 配置则让弹层到期自毁。
Q:layer 移动端适配要点?
layer 的 run 里对 iOS / Android 的宽高 API 做了兼容,fixed: true 的弹层会监听 resize 自动重算坐标,一般不用手写适配。要做的只有一件事:宽度别写死像素,用 '80%'、'auto' 这类值,让 src/css/modules/layer.css 里的 maxWidth 限制在不同视口上生效。
什么时候该用 layer
需要拦截用户操作、必须展示操作结果的场景——确认、轻提示、加载、气泡、嵌入页面——交给 layer;独立业务流程或长表单更适合做成页面路由,别塞进弹层。实现细节见源码 src/components/layer.js,官方文档见 docs/README.md。
【免费下载链接】layui 一套遵循浏览器原生态开发模式的 Web UI 组件库。 项目地址: https://gitcode.com/GitHub_Trending/la/layui
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



