一、什么是 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 团队设计合成事件系统，核心是为了解决原生 DOM 事件的三大痛点：

1. 浏览器兼容性问题：不同浏览器对同一事件的支持程度、属性名称、触发时机存在差异，开发者需要编写大量兼容代码。合成事件提供了标准化的 API（如 e.target、e.preventDefault()），无需关注浏览器差异。
2. 大量元素事件绑定的性能瓶颈：如果为页面中每个元素都绑定原生事件，会占用大量内存。合成事件通过事件委托，只在根节点绑定一次原生事件，利用事件冒泡机制触发对应组件的事件处理函数，极大优化了内存占用。
3. 与虚拟 DOM 的适配问题：React 的虚拟 DOM 会频繁更新，若直接绑定原生事件到真实 DOM，虚拟 DOM 重新渲染时需要反复解绑/绑定事件，增加性能损耗。合成事件基于虚拟 DOM 路径分发，无需关心真实 DOM 的更新。

三、合成事件的核心原理

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()。