一、什么是 React 合成事件

React 合成事件是 React 对浏览器原生 DOM 事件的一层封装，它提供了跨浏览器兼容的统一事件接口，同时结合 React 虚拟 DOM 特性实现了更高效的事件处理。

简单来说，合成事件不是原生 DOM 事件，但可以看作原生事件的“代理”——它保留了原生事件的核心能力，同时解决了原生事件的兼容性和性能问题。

核心特点

1. 跨浏览器一致性：不同浏览器的原生事件存在差异（如 IE 的 srcElement vs 标准浏览器的 target），React 合成事件抹平了这些差异，让事件逻辑在所有浏览器中表现一致。
2. 事件委托机制：合成事件不会直接绑定到具体的 DOM 元素，而是统一委托到 React 应用的根节点（React 17+）或 document（React 16 及更早），大幅减少事件绑定的内存开销。
3. 与虚拟 DOM 解耦：合成事件系统独立于真实 DOM，符合 React “数据驱动视图”的设计理念，避免开发者直接操作 DOM。
4. 原生事件访问入口：合成事件对象通过 nativeEvent 属性暴露底层原生 DOM 事件，满足特殊场景下的原生操作需求。

二、为什么 React 要设计合成事件

合成事件不是为了“多包一层”而存在。它要同时解决三个层面的问题：浏览器之间的差异、大型组件树的事件成本，以及 React 自己的声明式更新模型。再往后看，它还为批处理和事件优先级提供了统一入口。

1. 抹平浏览器差异，给组件一个稳定的事件 API

React 诞生早期，浏览器事件差异是实打实的开发成本。绑定方式有 addEventListener 和 IE 的 attachEvent，事件对象上有 target 和 srcElement，表单的 change 触发时机也不一致，mouseenter 这类事件在部分浏览器里甚至不会冒泡。

如果 React 直接把原生事件交给组件，每个业务组件都可能要写兼容分支。合成事件把这些差异收口到框架内部，对外提供统一的 target、currentTarget、preventDefault()、stopPropagation() 等接口，并模拟缺失的事件语义。组件面对的不再是“某个浏览器的事件”，而是 React 定义的一套稳定契约。

2. 用事件委托承接大规模组件树

如果每个带 onClick 的元素都直接绑定原生监听器，页面上的监听器数量会随组件数量线性增长。组件频繁挂载、卸载时，还要反复绑定和解绑。

合成事件采用事件委托：每种事件类型只在根节点绑定一次原生监听器，事件触发后，React 从真实 DOM 找到对应 Fiber，再沿 Fiber 树分发。这样即使页面上有几千个按钮，原生监听器数量也基本不变。新增或删除节点时，也不需要单独维护监听器，因为分发逻辑是运行时根据 Fiber 树计算的。

3. 和虚拟 DOM 的更新方式匹配

React 重新渲染时，组件的 props 和事件处理函数可能每次都是新的，但真实 DOM 节点会被复用。如果事件直接绑在真实 DOM 上，React 每次渲染都要比较处理函数是否变化，再决定解绑和重新绑定。

合成事件把“原生监听器”和“业务处理函数”拆开了：根节点上的原生监听器保持稳定，真正要执行的函数从当前 Fiber 的 memoizedProps 里读取。这样事件处理函数的更新跟着 React 的渲染结果走，不需要和真实 DOM 的绑定生命周期绑在一起。

4. 统一事件语义，而不只是统一属性名

合成事件做的不仅是把 srcElement 改名成 target。它还统一了捕获和冒泡的执行顺序，动态维护 currentTarget，并对 onChange、onMouseEnter 等事件做行为适配。

这也解释了一个常见疑问：为什么 e.stopPropagation() 有时挡不住原生事件？因为合成事件和原生事件是两套传播体系。e.stopPropagation() 停的是 React 在 Fiber 树上的模拟传播，要阻止原生事件继续冒泡，还得调用 e.nativeEvent.stopPropagation()。这不是 bug，而是两层事件系统之间的边界。

5. 为批处理和事件优先级留出入口

在 React 18 之前，只有在 React 事件处理函数中触发的状态更新才会被批量处理。合成事件的分发过程，正好是 React 收集更新、统一刷新的时机。React 18 引入自动批处理后，Promise、定时器、原生事件里的更新也能批量处理，但事件系统仍然是 React 判断事件类型和调度优先级的重要入口。

例如点击、键盘输入这类离散事件需要尽快响应，滚动、鼠标移动这类连续事件则可以按帧合并处理。如果事件完全交给浏览器和业务代码，React 就很难在统一层面做这种调度。

6. 为不同渲染器保留统一的事件抽象

React 的目标不只是操作 DOM。组件里写的是 onClick、onChange 这样的声明式事件属性，具体如何把它们映射到宿主环境，由渲染器负责。合成事件把“组件如何描述事件”与“宿主如何产生事件”隔开，React DOM 负责 DOM 事件的适配，其他渲染器也可以提供自己的宿主事件实现。

代价与边界

合成事件不是没有成本。它多了一层对象创建和分发，调试时看到的不一定是原生事件；某些依赖原生行为的功能需要 nativeEvent；事件委托的位置也从 React 16 的 document 变成了 React 17+ 的根容器，以避免多个 React 版本或嵌套应用之间互相干扰。

但把这些成本放在框架层，换来的是一致的事件 API、可控的监听器数量和更顺畅的更新模型。对绝大多数业务代码来说，这笔交换是划算的。

三、合成事件的核心原理

React 合成事件核心执行阶段

阶段 1：事件委托——统一挂载原生事件监听

React 会在应用初始化时，在根节点（React 17+）或 document（React 16 及更早）上，为所有需要支持的事件类型（如 click、input）绑定一次原生事件监听函数（绑定在原生冒泡阶段）。

同时，React 内部维护了一张 事件类型映射表，将 React 事件名（如 onClick）映射到对应的原生事件名（如 click），例如：

• onChange → 原生 input/change 事件（兼容不同浏览器的 change 触发逻辑）
• onMouseEnter → 原生 mouseover/mouseout 事件（模拟无冒泡的鼠标进入事件）

阶段 2：原生事件触发——根节点监听函数执行

当用户触发事件（如点击按钮），浏览器先执行原生捕获阶段（从 document 遍历到目标 DOM，执行所有原生捕获事件），随后进入原生冒泡阶段：

1. 浏览器从目标 DOM 开始向上遍历真实 DOM 树；
2. 遍历到 React 根节点时，触发之前绑定的原生事件监听函数；
3. React 从原生事件对象中提取核心信息：触发事件的真实 DOM 元素、事件类型（如 click）、原生事件对象（如 MouseEvent）；
4. 通过真实 DOM 上的隐藏属性（如 __reactInternalInstance$xxx），找到对应的目标 Fiber 节点（虚拟 DOM 节点）。

阶段 3：合成事件对象创建——封装原生事件

基于上述信息，React 完成合成事件实例的创建：

1. 从原生事件对象中提取关键信息（如触发元素、事件类型、鼠标坐标、按键编码等）；
2. 根据事件类型创建对应的合成事件实例（如 SyntheticMouseEvent 对应鼠标事件、SyntheticKeyboardEvent 对应键盘事件）；
3. 为合成事件对象添加标准化方法（preventDefault、stopPropagation）和属性（target、currentTarget），确保跨浏览器行为一致；
   • target 直接赋值为触发事件的真实 DOM（固定不变）；
   • currentTarget 暂为空，后续分发时动态赋值。

阶段 4：事件分发——模拟冒泡与捕获流程

这是合成事件最核心的“模拟”逻辑。由于事件实际绑定在根节点，React 需要手动模拟事件的冒泡和捕获阶段，具体步骤如下：

1. 构建事件路径：从目标 Fiber 节点出发，向上遍历到 React 根节点对应的 Fiber 节点，生成一条“Fiber 树事件传播路径”；
2. 模拟捕获阶段：如果组件绑定了捕获阶段的事件（如 onClickCapture），React 会从事件路径的根节点向目标节点遍历，依次执行捕获阶段的事件处理函数（执行时动态赋值 currentTarget 为当前 Fiber 节点对应的真实 DOM）；
3. 模拟冒泡阶段：默认情况下，React 会从目标 Fiber 节点向根节点遍历，依次执行冒泡阶段的事件处理函数（如 onClick）：
   • 遍历到每个 Fiber 节点时，读取节点 memoizedProps 中绑定的事件处理函数；
   • 为合成事件对象赋值 currentTarget（当前 Fiber 节点对应的真实 DOM）；
   • 执行事件处理函数（传入合成事件实例）；
   • 若调用 e.stopPropagation()，则终止遍历，不再执行后续父节点的事件回调。

阶段 5：原生冒泡收尾——浏览器继续遍历

React 合成事件处理完毕后，浏览器会继续执行原生冒泡阶段的剩余逻辑：从 React 根节点向上遍历到 document，执行这些节点上绑定的原生冒泡事件（若未通过 e.nativeEvent.stopPropagation() 阻止）。

阶段 6：事件池（React 17 已废弃）

在 React 16 及更早版本中，为了进一步优化内存，React 引入了事件池机制：

• 事件处理函数执行前，从事件池中取出一个合成事件对象，填充原生事件数据；
• 事件处理函数执行完毕后，清空合成事件对象的属性，放回池中复用。

这导致在异步操作中访问合成事件会出现属性丢失的问题，需要调用 e.persist() 将事件对象从池中取出。React 17 移除了事件池，因为现代浏览器的内存管理能力已足够高效，事件池带来的收益远小于开发成本。

核心流程时序总结

用户触发事件
  ↓
浏览器执行：原生捕获阶段（document → 目标 DOM）
  ↓
浏览器执行：原生冒泡阶段（目标 DOM → React 根节点）
  ↓
触发 React 根节点的原生监听函数
  ↓
React 提取：真实 DOM + 事件类型 → 找到对应 Fiber 节点
  ↓
React 创建：合成事件实例（封装原生事件 + 标准化属性）
  ↓
React 执行：模拟合成捕获阶段（根 Fiber → 目标 Fiber）
  ↓
React 执行：模拟合成冒泡阶段（目标 Fiber → 根 Fiber）
  ↓
浏览器执行：原生冒泡收尾（React 根节点 → document）
  ↓
（React 16-）事件池回收合成事件实例

关键点补充说明

1. Fiber 节点是核心桥梁：React 不会直接关联“真实 DOM ↔ 事件回调”，而是将回调存在 Fiber 节点的 memoizedProps 中，真实 DOM 仅通过隐藏属性关联 Fiber 节点；
2. currentTarget 动态赋值：target 始终指向触发事件的真实 DOM，而 currentTarget 会在合成事件遍历 Fiber 树时，动态指向当前执行回调的 Fiber 节点对应的真实 DOM；
3. stopPropagation 作用域：合成事件的 e.stopPropagation() 仅终止 Fiber 树的遍历，若要阻止原生冒泡，需调用 e.nativeEvent.stopPropagation()。

四、合成事件的使用细节

1. 基础使用方法

合成事件通过 React 元素的属性绑定，事件名采用小驼峰命名（如 onClick 而非 onclick），事件处理函数接收合成事件对象作为参数。

import React from 'react';

const Button = () => {
  const handleClick = (e) => {
    // 阻止默认行为（跨浏览器兼容）
    e.preventDefault();
    // 阻止合成事件冒泡
    e.stopPropagation();
    // 访问原生事件对象
    console.log('原生事件：', e.nativeEvent);
    console.log('触发元素：', e.target);
  };

  return <button onClick={handleClick}>点击测试</button>;
};

export default Button;

2. 合成事件 vs 原生 DOM 事件

3. 关键注意点

（1）stopPropagation 的作用范围

合成事件的 e.stopPropagation() 仅能阻止合成事件的传播，无法阻止原生事件的冒泡。如果同时绑定了合成事件和原生事件，需要通过原生事件对象阻止冒泡：

const handleClick = (e) => {
  e.stopPropagation(); // 阻止合成事件冒泡
  e.nativeEvent.stopPropagation(); // 阻止原生事件冒泡
};

（2）类组件中的 this 指向问题

在类组件中，直接传递事件处理函数会导致 this 丢失指向，需要通过以下三种方式绑定：

import React, { Component } from 'react';

class MyButton extends Component {
  // 方法 1：类字段（推荐）
  handleClick = () => {
    console.log('this 指向组件实例', this);
  };

  render() {
    // 方法 2：bind 绑定
    // return <button onClick={this.handleClick.bind(this)}>点击</button>;
    // 方法 3：箭头函数包裹
    // return <button onClick={() => this.handleClick()}>点击</button>;
    return <button onClick={this.handleClick}>点击</button>;
  }
}

（3）合成事件与原生事件的执行顺序

由于合成事件是在原生事件的冒泡阶段触发的，因此执行顺序为：

原生捕获阶段 → 合成捕获阶段 → 合成冒泡阶段 → 原生冒泡阶段

五、合成事件的常见坑与解决方案

1. 阻止冒泡不生效

问题：同时绑定合成事件和原生事件时，e.stopPropagation() 无法阻止原生事件冒泡。 解决方案：通过 e.nativeEvent.stopPropagation() 阻止原生事件流。

2. 异步操作中访问合成事件属性丢失

问题：React 16 及更早版本中，异步操作（如 setTimeout）中访问合成事件属性会返回 null。 解决方案：调用 e.persist() 或升级到 React 17+（移除了事件池）。

3. 自定义事件无法被合成事件系统识别

问题：通过 dispatchEvent 触发的自定义原生事件，无法触发 React 合成事件。 解决方案：直接使用原生事件监听，或通过 React 状态管理实现组件间通信。

六、总结

React 合成事件是 React 事件处理的核心，其本质是基于事件委托和虚拟 DOM 路径遍历的跨浏览器事件系统。理解合成事件的原理，不仅能帮助我们写出更高效的事件处理代码，还能规避开发中的常见陷阱。

核心要点回顾：

1. 合成事件是原生事件的封装，目的是跨浏览器兼容和性能优化；
2. 核心原理是事件委托 + 模拟事件流，事件统一绑定到根节点，通过遍历虚拟 DOM 路径分发；
3. stopPropagation 仅作用于合成事件流，原生事件需要单独处理；
4. React 17 移除了事件池，无需再调用 e.persist()。