遮罩层必须是 modal__overlay 而不是独立 block，因其与弹窗内容共享同一交互状态，bem 规范要求其为 modal 的直属 element；css 需避免层叠上下文陷阱、正确设置 pointer-events 和 transition，并确保 html 结构中 modal 与 modal__overlay 平级且位于 body 下。
遮罩层为什么必须是 modal__overlay 而不是独立 Block
因为遮罩和弹窗内容共享同一交互状态：点击遮罩关闭弹窗、ESC 键关闭整个组件、JS 控制显隐时也只应操作一个状态开关。若把遮罩写成 overlay 独立 Block，就会被迫在 JS 里同时切换 modal--visible 和 overlay--visible，稍有疏漏就导致遮罩显示但内容没出来，或反之。BEM 规范要求 __overlay 是 modal 的直属 Element，语义上它属于 modal 这个 Block 的一部分，不是平行组件。
常见错误包括：modal__content__overlay（违反 BEM 元素不可嵌套）、overlay 单独声明（破坏状态统一）、或把 modal__overlay 塞进 modal__content 内部（导致定位被父级 transform 截断）。
modal__overlay 的 CSS 必须绕开层叠上下文陷阱
Fixed 定位本该锚定视口，但一旦父元素有 transform、opacity、filter 或 will-change，就会创建新层叠上下文，让 z-index 失效——遮罩看似写了 z-index: 9999，却压不住隔壁一个 z-index: 1 的按钮。
实操要点：
- 确保
modal__overlay直接挂载在下，或至少是html/body的直系子节点，避开所有可能带transform的容器 -
modal__overlay自身不能加transform（哪怕只是translateZ(0)），否则它自己就创建了新上下文 - 用
inset: 0替代top: 0; right: 0; bottom: 0; left: 0，更简洁且不易漏边；旧版 Safari 回退写四边 - 背景色必须显式声明，如
background-color: rgba(0, 0, 0, 0.5)，完全透明的rgba(0,0,0,0)在部分浏览器下不触发 pointer-events
pointer-events 分层控制不能只靠 z-index
遮罩盖住了内容，不代表它能拦截点击——用户点一下，背后按钮照样触发，说明 pointer-events 没配对。
正确做法是分两层控制：
-
modal__overlay设pointer-events: none（视觉存在但不响应事件） - 遮罩内部的可点击元素（如关闭按钮、引导箭头）单独设
pointer-events: auto - 别用
opacity: 0或visibility: hidden隐藏遮罩——它们仍占位、仍响应事件；该用display: none或移除 DOM - 如果遮罩下有
overflow: hidden的祖先，fixed 元素可能被裁剪；此时需检查并临时移除该限制，或改用position: absolute+body { position: relative }（仅限无滚动场景）
transition 动画必须定义在基础类，而非修饰符
动画闪一下就消失、隐藏时直接跳变，大概率是因为把 transition 写在了 modal__overlay--visible 里。
原因：CSS transition 只在属性值变化时生效，而 --visible 类只在显示时添加，隐藏时类被移除，transition 就没了作用对象。
正确写法：
.modal__overlay {
opacity: 0;
visibility: hidden;
transition: opacity 0.2s ease, visibility 0.2s step-end;
}
.modal--visible .modal__overlay {
opacity: 1;
visibility: visible;
}
关键点：step-end 防止 visibility 在过渡中途突然显示导致闪现；display: none 不可过渡，必须弃用。
真正容易被忽略的，是 HTML 结构和 CSS 定位必须严格对齐：DOM 中 modal 和 modal__overlay 必须平级、紧邻，且都在 body 下；否则再正确的 class 名和样式，也会因父级上下文或定位偏移失效。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
