原生 可用但易踩坑，推荐手动实现遮罩+弹层；遮罩须用 position: fixed、避免 100vh、用 transform 居中弹层；点击遮罩关闭需 pointerdown + e.target === this 校验；检测 showModal 方法存在性决定是否降级。
原生 <dialog></dialog> 在现代项目里能用，但直接上它大概率踩坑；手动布局遮罩+弹层才是可控、可调、可降级的正解。
遮罩层必须用 position: fixed，别碰 absolute
遮罩本质是“盖住整个视口”，和页面滚动无关。用 position: absolute 依赖最近的 position: relative 祖先，一旦祖先有 transform、overflow: hidden 或 filter，遮罩就偏移、裁剪甚至消失。
正确写法：
.modal-overlay {
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
background-color: rgba(0, 0, 0, 0.5);
z-index: 1000;
}
- 不用
100vh—— iOS Safari 滚动时地址栏收放会导致高度突变；可用100dvh（Chrome 105+/Safari 16.4+），否则 fallback 到min-height: 100vh -
z-index: 1000是起点，不是终点；确保它比背景高、比弹层低 - 移动端加
touch-action: none，避免橡皮筋拖拽或缩放干扰
弹层居中不能靠 margin: auto + width/height
固定宽高的弹层用 margin: auto 居中，只在 position: absolute 且父容器为 position: relative 时有效，但遮罩和弹层应同级、都用 fixed，所以这个组合失效。
立即学习“前端免费学习笔记（深入）”；
推荐方案：用 transform: translate(-50%, -50%) 配合绝对定位坐标：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
.modal {
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
z-index: 1001;
width: 90vw;
max-width: 500px;
}
- 不设
height，让内容撑开；设max-height+overflow-y: auto防止内容溢出屏幕 -
width: 90vw保证移动端留边，max-width控制桌面端宽度上限 - 如果弹层内含表单或输入框，记得加
outline: none和tabindex="-1"避免焦点跳到不可见区域
点击遮罩关闭弹层，e.target === this 判断不能省
监听遮罩的 click 事件时，若不做目标校验，点弹层内部任意按钮、链接、输入框都会触发关闭——因为事件冒泡到遮罩层。
正确写法（注意是 pointerdown，非 click）：
overlayEl.addEventListener('pointerdown', function(e) {
if (e.target !== this) return;
closeModal();
});
- 移动端必须用
pointerdown替代click，规避 iOS Safari 的 300ms 延迟导致的误判 - 别用
overlay.contains(e.target)—— 遮罩和弹层是兄弟节点，contains永远返回false - 也别用
e.target.classList.contains('overlay')—— 弹层可能动态插入，类名不唯一
要不要用原生 <dialog></dialog>？先检测再决定
别只检查 document.createElement('dialog') 是否成功，旧版 Safari（如 15.3）能创建元素，但调用 showModal() 会直接抛 TypeError: modal.showModal is not a function。
唯一可靠检测方式：
if ('showModal' in HTMLDialogElement.prototype) {
// 可安全使用 dialog
} else {
// 必须降级为 <div role="dialog"> + 手动实现焦点锁、遮罩、Esc 关闭
}
-
dialog::backdrop是伪元素，无法直接绑定事件；想点击关闭，得监听它本身（现代浏览器支持），或退回到外层加真实 DOM 遮罩 -
dialog.open = true无效，必须用dialog.showModal()；关闭必须用dialog.close()，设open = false不会移除 backdrop - 动画支持弱，
transition对dialog本身基本无效；真要入场动效，还是得手动控制 class + CSS 动画
真正难的不是写出来，而是让弹层在 iOS Safari 滚动时不抖、在嵌套场景下焦点不丢、在缩放或横屏时仍居中——这些细节没被显式处理，上线后就会在用户手指划过时突然暴露。
