React 怎么阻止子组件手势穿透父组件，用错场景反而更麻烦

先分清两件事：如果"手势穿透"指的是点击子组件时父组件的 onClick 也被触发，那是事件冒泡，用 e.stopPropagation() 解决；如果指的是弹层里滑动时底下的页面跟着滚，那是滚动链（scroll chaining），用 CSS 的 overscroll-behavior 解决，跟事件冒泡毫无关系。把这两件事混为一谈，是这个问题越改越乱的根源。

子组件手势穿透到底该怎么拦？

还有一个更隐蔽的坑：React 的 stopPropagation 只对 React 合成事件生效，对挂在 document 或 window 上的原生监听器无效。很多人调完发现"明明阻止了还是触发"，就卡在这里。

本文按"先分清问题类型 → 给出正确写法 → 说明用错场景的代价"的顺序讲清，并给出一份能定位到底是哪种穿透的判断流程。

先看结论

点击穿透用 e.stopPropagation()，滚动穿透用 overscroll-behavior: contain 或给 body 加 overflow: hidden。两者不是同一个机制，别互相替代。

优先级的正确顺序是：能用语义化手段（disabled、条件渲染、CSS pointer-events）解决的，就别用事件拦截。事件拦截会让键盘操作和无障碍支持一起失效，属于"为了堵一个洞拆了整面墙"。

合成事件这块若不牢，可以先看 React 官方教程把事件对象的传递过程过一遍。

一、先分清是哪种"穿透"

两种现象看起来像，机制完全不同。区分清楚事件冒泡与滚动链，后面的修复才不会用错工具。

1.1 点击穿透：事件冒泡

子组件被点击时，事件会沿着组件树向上传递，父组件的 onClick 随之触发。这是 DOM 事件模型的标准行为，不是 bug。

function Card({ onClose }) {
  return (
    <div className="card" onClick={onClose}>
      <button onClick={(e) => {
        e.stopPropagation();
        console.log('只执行按钮自己的逻辑');
      }}>
        卡片内的按钮
      </button>
    </div>
  );
}

这段做的是：外层 div 点击时关闭卡片，内层按钮用 e.stopPropagation() 掐断冒泡，于是点按钮不会触发关闭。关键点是要拿到事件对象 e，且必须在自己的处理逻辑之前调用。

1.2 滚动穿透：滚动链

弹层滚到尽头后，继续滑动会让底层页面跟着滚。这是浏览器的滚动链行为，跟事件冒泡无关，所以 stopPropagation() 完全不起作用。

.modal {
  max-height: 60vh;
  overflow-y: auto;
  overscroll-behavior: contain;
}

这段做的是：给弹层自身可滚动区域加上 overscroll-behavior: contain，滚动到边界后不再把滚动传递给祖先容器。另外还需要给 body 加 overflow: hidden，阻止背景页面整体滚动。

点击穿透与滚动穿透的判定流程

二、三个真实的失败分支

2.1 失败分支一：阻止了冒泡，document 上的监听还是触发了

React 的合成事件是把事件代理到容器节点上统一派发的。如果你在 document 上用原生 addEventListener 挂了监听，它处在 React 容器之外，合成事件的 stopPropagation 管不到它。

useEffect(() => {
  const handler = () => console.log('document 上的监听照样触发');
  document.addEventListener('click', handler);
  return () => document.removeEventListener('click', handler);
}, []);

这段做的是在 document 上挂一个原生监听。预期结果（未在本机执行，依据事件模型的传播顺序）是即便子组件调用了 stopPropagation，这条监听仍会执行。

修复办法有三条，按推荐排序：把监听挂到 React 容器内部的节点上；在处理函数里用 e.target.closest() 判断点击来源；或者改用 ref 直接在 DOM 节点上绑定原生事件并在捕获阶段处理。

2.2 失败分支二：用 stopPropagation 屏蔽表单提交

想在按钮里阻止外层表单提交，正确做法是 e.preventDefault() 而不是 stopPropagation()。前者阻止默认行为（提交表单），后者只阻止冒泡，表单该提交还是会提交。

2.3 失败分支三：靠判断 target 来屏蔽点击

有些写法是在父组件里判断 e.target 的类名，命中子元素就直接 return。这种写法会让键盘 Enter、空格键触发的点击也一并失效，可访问性直接退化。修复办法是换成语义化控制：真的不可点就用 disabled 属性，或者干脆不渲染那个元素。

场景	正确手段	错误手段
阻止父级点击	stopPropagation	判断 e.target 类名
阻止表单提交	preventDefault	stopPropagation
阻止滚动传递	overscroll-behavior	stopPropagation
元素不可交互	disabled / pointer-events	事件里 return

三、用错场景的代价

stopPropagation 用来处理事件冒泡本身没错，但用多了会留下三个后遗症：

调试变困难。事件在某个层级被悄无声息地掐断，出问题时要逐层往上找是谁拦的。
全局功能失效。写在 document 上的"点击空白处关闭"这类全局交互会被一起掐断，而且现象很随机。
无障碍退化。靠事件拦截实现的"不可点击"，对读屏软件来说是仍然可点的，语义与视觉不一致。

更稳的替代方案是 CSS 层面的 pointer-events: none：

.overlay-children {
  pointer-events: none;
}
.overlay-children .interactive {
  pointer-events: auto;
}

这段做的是：让遮罩的子元素整体不接收指针事件，再给需要交互的那部分单独恢复。它比事件拦截更彻底，也不影响键盘操作的可访问性语义。

合成事件与 document 原生监听在传播链上的相对位置

四、定位流程与验证清单

4.1 三步定位到底是哪类穿透

在子元素的处理函数里打印事件类型：是 click 走冒泡路线，是 touchmove/wheel 走滚动路线；
临时给弹层加 overscroll-behavior: contain，看背景还滚不滚；
临时在 document 上加一个 console.log，确认是否有原生监听在 React 之外生效。

事件冒泡相关的排查还有一个前提：确认冒泡路径上有几个监听器，以及它们分别挂在哪个节点上。

4.2 验证清单

检查：事件处理函数是否接收了事件对象 e
检查：stopPropagation 是否在处理逻辑之前调用
运行：分别点击子元素与父元素空白区，观察控制台输出
预期：点子元素只有子元素日志，点空白区才有父元素日志
失败：两边都触发 → 事件对象没传对，或者监听挂在 React 之外
修复：改用 preventDefault、overscroll-behavior 或 pointer-events
验证：用键盘 Tab 到该元素再按 Enter，确认交互语义仍然完整

最后这一项最关键：事件拦截最容易牺牲的正是键盘用户，不验证等于埋雷。

总结

阻止子组件手势穿透父组件，先判断是事件冒泡还是滚动链：前者用 stopPropagation，后者用 overscroll-behavior。stopPropagation 只对合成事件生效，管不到 document 上的原生监听；表单提交要的是 preventDefault 而不是事件拦截。

三条要点带走：

三种穿透三种手段，别用 stopPropagation 通吃；
能用 disabled、pointer-events、条件渲染解决的，就别拦事件；
改完一定要用键盘走一遍，确认语义没被破坏。

下一步建议把"点击外部关闭"这类全局交互统一收进一个 hook，避免在组件里散落事件拦截。语法细节记不住时，翻 JavaScript 速查手册最快。

常见问题

Q：为什么调用了 stopPropagation 但父组件还是响应了？

A：先确认事件对象传对了、且在处理逻辑之前调用。还有一种情况是父组件用的是捕获阶段，需要在捕获阶段拦截。

Q：弹层里滑动时背景跟着滚动，怎么解决？

A：那不是事件冒泡而是滚动链。给弹层加 overscroll-behavior: contain，并给 body 加 overflow: hidden。

Q：stopPropagation 和 preventDefault 有什么区别？

A：前者阻止事件继续传播给父级，后者阻止元素的默认行为。想阻止表单提交要用后者，两者不能互相替代。

Q：怎么阻止同一元素上的其他监听器执行？

A：原生事件用 stopImmediatePropagation。React 合成事件没有这个 API，需要改成在同一个处理函数里控制执行顺序。

延伸学习

想把事件这块补齐，可以按这个顺序来：

读一篇相关笔记 React 常见坑排查笔记，把渲染与事件相关的典型问题过一遍；
想系统学，JavaScript 配套课程是从基础到模块化的完整路线；
想随手验证，用 JavaScript 在线运行贴进去跑。