@tap.stop 是 uni-app 中最简单可靠的防误关方案，它在事件回调前调用 stoppropagation 阻断冒泡，比 document 监听更轻量稳定；需配合遮罩层样式（position/fixed、z-index）和 pointer-events: none 才能彻底生效。
直接在弹窗根元素上加 @tap.stop 是最简单、最可靠的防误关方案，比监听 document + 判断点击位置更轻量、更稳定。
为什么 document 点击监听经常失效
很多人写 document.addEventListener('click', closePopup) 后发现：点弹窗里的按钮、输入框甚至遮罩层本身，弹窗也关了。这不是事件没冒泡，而是你没过滤目标——event.target 可能是弹窗任意子节点，而这些节点本该“免疫”关闭逻辑。
关键不是阻止冒泡，而是精准识别“点的到底是不是空白处”。空白处 = 弹窗容器及其所有后代元素之外的区域。
- 用
e.composedPath().includes(popupEl)是目前最健壮的判断方式，能穿透 Shadow DOM 和 Portal 渲染场景 - 降级可用
e.target.closest('.popup-wrapper')，但不适用于自定义元素或 Web Component 内部 - 绝对不要用
e.target === document.body或递归查parentElement，容易漏判或误判
@tap.stop 是 uni-app 里最推荐的拦截方式
在遮罩层或弹窗外层容器上写 @tap.stop="closePopup"，等于在事件触发回调前立刻调用 event.stopPropagation()，从源头掐断冒泡路径。
它比 @click.stop 更稳妥：uni-app 中 @tap 是跨平台手势事件统一入口，iOS、小程序、H5 行为一致；而 @click 在部分 iOS Safari 或微信小程序里可能延迟或不触发。
- 错误写法：
<view><view></view></view>→ 点子元素仍会冒泡触发关闭 - 正确写法：
<view><view></view></view>→ 子元素点击不会影响父层 - 注意：如果弹窗内容区需要滚动，别给整个弹窗容器加
@touchmove.stop.prevent，否则内部滑动失效
遮罩层失效的三个常见原因
很多“点击空白没反应”或“点了却关不掉”的问题，根本不是事件没拦住，而是遮罩层压根没生效。
- 遮罩层没设
position: fixed或absolute，导致无法覆盖全屏 -
z-index不够高，被地图、cover-view、video等原生组件穿透（它们默认层级更高） - 底层内容没禁用交互，仅靠遮罩层拦截不够——必须同时加
pointer-events: none到页面主体容器上
推荐组合：class="mask-active" 动态控制，配合 CSS：.mask-active .page-content { pointer-events: none; }，显示弹窗时加类，隐藏后立刻移除。
遇到 TypeError: $event.stopPropagation is not a function 怎么办
这个报错只出现在某些平台（如旧版微信小程序基础库或 nvue 页面），本质是事件对象不是标准 Event 实例，没有 stopPropagation 方法。
此时不能依赖修饰符，得手动处理：
- 改用
@tap="handleTap($event)"，在方法里加if (e && typeof e.stopPropagation === 'function') e.stopPropagation() - 或者直接换用
catchtap（仅限小程序端，H5/App 不支持） - 更彻底的解法：统一用
@tap.stop，并确保项目编译目标基础库 ≥ 2.27.0（微信小程序）或使用最新版 HBuilderX
真正复杂的点不在“怎么写”，而在于三件事是否同时成立：事件被 stop、样式层级够高、底层交互被禁用。少一个，就可能在某个机型或快速连点时失效。
