React 事件系统addTrappedEventListener的使用

──────────────────────────────────────────────────────────────────────
 createRoot(container)
──────────────────────────────────────────────────────────────────────
  │
  ▼
 listenToAllSupportedEvents(container)
  │
  ├── (container._reactListening = true)
  │
  ├── allNativeEvents.forEach('click'):
  │   ├── 'click' ∉ nonDelegatedEvents
  │   │   └── listenToNativeEvent('click', false, container)
  │   │       └── addTrappedEventListener(container, 'click', 0, false)
  │   │            ├── createEventListenerWrapperWithPriority(container, 'click', 0)
  │   │            │   └── getEventPriority('click') → DiscreteEventPriority
  │   │            │   └── dispatchDiscreteEvent.bind(null, 'click', 0, container)
  │   │            ├── passiveBrowserEventsSupported? Yes, but click ∈ [touchstart,touchmove,wheel]? No
  │   │            │   └── isPassiveListener = undefined
  │   │            ├── isCapturePhaseListener? false → addEventBubbleListener
  │   │            │   └── container.addEventListener('click', wrapper, false)
  │   │            └── return listener (unsubscribe)
  │   │
  │   └── listenToNativeEvent('click', true, container)
  │       └── addTrappedEventListener(container, 'click', IS_CAPTURE_PHASE, true)
  │           ├── dispatchDiscreteEvent.bind(null, 'click', IS_CAPTURE_PHASE, container)
  │           ├── isCapturePhaseListener? true → addEventCaptureListener
  │           │   └── container.addEventListener('click', wrapper, true)
  │           └── return listener
  │
  ├── allNativeEvents.forEach('touchstart'):
  │   ├── listenToNativeEvent('touchstart', false, container)
  │   │   └── addTrappedEventListener(container, 'touchstart', 0, false)
  │   │       ├── isPassiveListener = true  (domEventName === 'touchstart')
  │   │       ├── isCapturePhaseListener? false, isPassiveListener? true
  │   │       │   └── addEventBubbleListenerWithPassiveFlag(container, 'touchstart', wrapper, true)
  │   │       │       └── container.addEventListener('touchstart', wrapper, { passive: true })
  │   │       └── return listener
  │   │
  │   └── listenToNativeEvent('touchstart', true, container)
  │       └── addTrappedEventListener(container, 'touchstart', IS_CAPTURE_PHASE, true)
  │           ├── isCapturePhaseListener? true, isPassiveListener? true
  │           │   └── addEventCaptureListenerWithPassiveFlag(container, 'touchstart', wrapper, true)
  │           │       └── container.addEventListener('touchstart', wrapper, { capture: true, passive: true })
  │           └── return listener
  │
  └── ownerDocument = document
      └── listenToNativeEvent('selectionchange', false, document)
          └── addTrappedEventListener(document, 'selectionchange', 0, false)
              ├── getEventPriority('selectionchange') → DiscreteEventPriority
              ├── isPassiveListener? false (non-passive)
              └── document.addEventListener('selectionchange', wrapper, false)
──────────────────────────────────────────────────────────────────────
 mount(<img onLoad={fn} />)
──────────────────────────────────────────────────────────────────────
  │
  └── ReactDOMComponent.finalizeInitialChildren
      └── listenToNonDelegatedEvent('load', imgElement)
          ├── listenerSet = imgElement.__reactEvents || new Set()
          ├── listenerSetKey = "load__bubble"
          ├── Set has "load__bubble"? No
          │
          └── addTrappedEventListener(imgElement, 'load', IS_NON_DELEGATED, false)
              ├── createEventListenerWrapperWithPriority(imgElement, 'load', IS_NON_DELEGATED)
              │   └── getEventPriority('load') → DefaultEventPriority
              │   └── dispatchEvent.bind(null, 'load', IS_NON_DELEGATED, imgElement)
              ├── isPassiveListener = undefined (load ∉ [touchstart,touchmove,wheel])
              └── imgElement.addEventListener('load', wrapper, false)
              └── listenerSet.add("load__bubble")

let listener = createEventListenerWrapperWithPriority(
  targetContainer,
  domEventName,
  eventSystemFlags,
);

let isPassiveListener = undefined;
if (passiveBrowserEventsSupported) {
  if (
    domEventName === 'touchstart' ||
    domEventName === 'touchmove' ||
    domEventName === 'wheel'
  ) {
    isPassiveListener = true;
  }
}

// 特性检测：浏览器是否支持 { passive: true } 选项
if (canUseDOM) {
  try {
    const options = {};
    Object.defineProperty(options, 'passive', {
      get: function () {
        passiveBrowserEventsSupported = true;  // getter 触发 → 浏览器支持
      },
    });
    window.addEventListener('test', options, options);
    window.removeEventListener('test', options, options);
  } catch (e) {
    passiveBrowserEventsSupported = false;
  }
}

if (isCapturePhaseListener) {
  // 捕获阶段
  if (isPassiveListener !== undefined) {
    unsubscribeListener = addEventCaptureListenerWithPassiveFlag(
      targetContainer, domEventName, listener, isPassiveListener,
    );

  } else {
    unsubscribeListener = addEventCaptureListener(
      targetContainer, domEventName, listener,
    );
  }
} else {
  // 冒泡阶段
  if (isPassiveListener !== undefined) {
    unsubscribeListener = addEventBubbleListenerWithPassiveFlag(
      targetContainer, domEventName, listener, isPassiveListener,
    );
  } else {
    unsubscribeListener = addEventBubbleListener(
      targetContainer, domEventName, listener,
    );
  }
}

export function addEventBubbleListener(
  target,
  eventType,
  listener,
) {
  target.addEventListener(eventType, listener, false);
  return listener;
}

export function addEventCaptureListener(
  target,
  eventType,
  listener,
) {
  target.addEventListener(eventType, listener, true);
  return listener;
}

export function addEventCaptureListenerWithPassiveFlag(
  target,
  eventType,
  listener,
  passive,
) {
  target.addEventListener(eventType, listener, {
    capture: true,
    passive,
  });
  return listener;
}

export function addEventBubbleListenerWithPassiveFlag(
  target,
  eventType,
  listener,
  passive,
) {
  target.addEventListener(eventType, listener, {
    passive,
  });
  return listener;
}

export function createEventListenerWrapperWithPriority(
  targetContainer,
  domEventName,
  eventSystemFlags,
) {
  const eventPriority = getEventPriority(domEventName);
  let listenerWrapper;
  switch (eventPriority) {
    case DiscreteEventPriority:
      listenerWrapper = dispatchDiscreteEvent;
      break;
    case ContinuousEventPriority:
      listenerWrapper = dispatchContinuousEvent;
      break;
    case DefaultEventPriority:
    default:
      listenerWrapper = dispatchEvent;
      break;
  }
  return listenerWrapper.bind(
    null,
    domEventName,
    eventSystemFlags,
    targetContainer,
  );
}

function dispatchDiscreteEvent(
  domEventName,
  eventSystemFlags,
  container,
  nativeEvent,
) {
  const prevTransition = ReactSharedInternals.T;
  ReactSharedInternals.T = null;
  const previousPriority = getCurrentUpdatePriority();
  try {
    setCurrentUpdatePriority(DiscreteEventPriority);
    dispatchEvent(domEventName, eventSystemFlags, container, nativeEvent);
  } finally {
    setCurrentUpdatePriority(previousPriority);
    ReactSharedInternals.T = prevTransition;
  }
}

function dispatchContinuousEvent(
  domEventName,
  eventSystemFlags,
  container,
  nativeEvent,
) {
  const prevTransition = ReactSharedInternals.T;
  ReactSharedInternals.T = null;
  const previousPriority = getCurrentUpdatePriority();
  try {
    setCurrentUpdatePriority(ContinuousEventPriority);
    dispatchEvent(domEventName, eventSystemFlags, container, nativeEvent);
  } finally {
    setCurrentUpdatePriority(previousPriority);
    ReactSharedInternals.T = prevTransition;
  }
}

export function dispatchEvent(
  domEventName,
  eventSystemFlags,
  targetContainer,
  nativeEvent,
) {
  // 标记 React 合成事件系统是否启用；关闭则直接跳过所有事件处理
  if (!_enabled) {
    return;
  }
  // 查找当前触发事件的 DOM 节点链上，还未完成水合（hydrate）的 DOM 元素；返回对应 DOM，无阻塞节点返回 null
  let blockedOn = findInstanceBlockingEvent(nativeEvent);
  if (blockedOn === null) {
    dispatchEventForPluginEventSystem(
      domEventName,
      eventSystemFlags,
      nativeEvent,
      return_targetInst,  // 事件目标 DOM 对应的 Fiber 实例
      targetContainer,
    );
    // 清空当前连续事件缓存队列，丢弃过期事件
    clearIfContinuousEvent(domEventName, nativeEvent);
    return;
  }

  if (
    // 连续事件（scroll/mousemove/touchmove）入队
    queueIfContinuousEvent(
      blockedOn,
      domEventName,
      eventSystemFlags,
      targetContainer,
      nativeEvent,
    )
  ) {
    nativeEvent.stopPropagation();
    return;
  }
  clearIfContinuousEvent(domEventName, nativeEvent);

  if (
    eventSystemFlags & IS_CAPTURE_PHASE &&
    // 判断该离散事件是否必须等待水合完成才能执行（click、input、keydown 等用户强交互）
    isDiscreteEventThatRequiresHydration(domEventName)
  ) {
    while (blockedOn !== null) {
      const fiber = getInstanceFromNode(blockedOn);
      if (fiber !== null) {
        attemptSynchronousHydration(fiber);
      }
      const nextBlockedOn = findInstanceBlockingEvent(nativeEvent);
      if (nextBlockedOn === null) {
        dispatchEventForPluginEventSystem(
          domEventName,
          eventSystemFlags,
          nativeEvent,
          return_targetInst,
          targetContainer,
        );
      }
      if (nextBlockedOn === blockedOn) {
        break;
      }
      blockedOn = nextBlockedOn;
    }
    if (blockedOn !== null) {
      nativeEvent.stopPropagation();
    }
    return;
  }

  dispatchEventForPluginEventSystem(
    domEventName,
    eventSystemFlags,
    nativeEvent,
    null,
    targetContainer,
  );
}

export function findInstanceBlockingEvent(
  nativeEvent,
) {
  const nativeEventTarget = getEventTarget(nativeEvent);
  return findInstanceBlockingTarget(nativeEventTarget);
}

function getEventTarget(nativeEvent) {
  let target = nativeEvent.target || nativeEvent.srcElement || window;

  if (target.correspondingUseElement) {
    target = target.correspondingUseElement;
  }
  return target.nodeType === TEXT_NODE ? target.parentNode : target;
}

export let return_targetInst = null;

export function findInstanceBlockingTarget(
  targetNode,
) {

  return_targetInst = null;
  // 从 DOM 向上找最近绑定 Fiber 的实例
  let targetInst = getClosestInstanceFromNode(targetNode);

  if (targetInst !== null) {
    // 从当前 Fiber 向上找最近已挂载的 Fiber
    const nearestMounted = getNearestMountedFiber(targetInst);
    if (nearestMounted === null) {
      targetInst = null;
    } else {
      const tag = nearestMounted.tag;
      // Suspense 组件，子树延迟加载，内部 DOM 已渲染但未激活
      if (tag === SuspenseComponent) {
        const instance = getSuspenseInstanceFromFiber(nearestMounted);
        if (instance !== null) {
          return instance;
        }
        targetInst = null;
      // 离屏缓存组件（React 内部），DOM 存在但组件未激活
      } else if (tag === ActivityComponent) {
        const instance = getActivityInstanceFromFiber(nearestMounted);
        if (instance !== null) {
          return instance;
        }
        targetInst = null;
      // 应用根 Fiber，对应 #root 容器
      } else if (tag === HostRoot) {
        const root = nearestMounted.stateNode;
        if (isRootDehydrated(root)) {
          return getContainerFromFiber(nearestMounted);
        }
        targetInst = null;
      } else if (nearestMounted !== targetInst) {
        targetInst = null;
      }
    }
  }
  return_targetInst = targetInst;
  return null;
}

export function clearIfContinuousEvent(
  domEventName,
  nativeEvent,
) {
  switch (domEventName) {
    case 'focusin':
    case 'focusout':
      // 缓存 focusin /focusout 焦点过渡事件
      queuedFocus = null;
      break;
    case 'dragenter':
    case 'dragleave':
      // 缓存 dragenter /dragleave 拖拽进出事件
      queuedDrag = null;
      break;
    case 'mouseover':
    case 'mouseout':
      // 缓存 mouseover /mouseout 鼠标悬浮进出事件
      queuedMouse = null;
      break;
    case 'pointerover':
    case 'pointerout': {
      // 缓存 pointerover/pointerout 指针悬浮事件
      const pointerId = nativeEvent.pointerId;
      queuedPointers.delete(pointerId);
      break;
    }
    case 'gotpointercapture':
    case 'lostpointercapture': {
      // 缓存 gotpointercapture/lostpointercapture 指针捕获事件
      const pointerId = nativeEvent.pointerId;
      queuedPointerCaptures.delete(pointerId);
      break;
    }
  }
}

export function queueIfContinuousEvent(
  blockedOn,
  domEventName,
  eventSystemFlags,
  targetContainer,
  nativeEvent,
) {
  switch (domEventName) {
    case 'focusin': {
      const focusEvent = nativeEvent;
      queuedFocus = accumulateOrCreateContinuousQueuedReplayableEvent(
        queuedFocus,
        blockedOn,
        domEventName,
        eventSystemFlags,
        targetContainer,
        focusEvent,
      );
      return true;
    }
    case 'dragenter': {
      const dragEvent = nativeEvent;
      queuedDrag = accumulateOrCreateContinuousQueuedReplayableEvent(
        queuedDrag,
        blockedOn,
        domEventName,
        eventSystemFlags,
        targetContainer,
        dragEvent,
      );
      return true;
    }
    case 'mouseover': {
      const mouseEvent = nativeEvent;
      queuedMouse = accumulateOrCreateContinuousQueuedReplayableEvent(
        queuedMouse,
        blockedOn,
        domEventName,
        eventSystemFlags,
        targetContainer,
        mouseEvent,
      );
      return true;
    }
    case 'pointerover': {
      const pointerEvent = nativeEvent;
      const pointerId = pointerEvent.pointerId;
      queuedPointers.set(
        pointerId,
        accumulateOrCreateContinuousQueuedReplayableEvent(
          queuedPointers.get(pointerId) || null,
          blockedOn,
          domEventName,
          eventSystemFlags,
          targetContainer,
          pointerEvent,
        ),
      );
      return true;
    }
    case 'gotpointercapture': {
      const pointerEvent = nativeEvent;
      const pointerId = pointerEvent.pointerId;
      queuedPointerCaptures.set(
        pointerId,
        accumulateOrCreateContinuousQueuedReplayableEvent(
          queuedPointerCaptures.get(pointerId) || null,
          blockedOn,
          domEventName,
          eventSystemFlags,
          targetContainer,
          pointerEvent,
        ),
      );
      return true;
    }
  }
  return false;
}

function accumulateOrCreateContinuousQueuedReplayableEvent(
  existingQueuedEvent,
  blockedOn,
  domEventName,
  eventSystemFlags,
  targetContainer,
  nativeEvent,
) {
  if (
    existingQueuedEvent === null ||
    existingQueuedEvent.nativeEvent !== nativeEvent
  ) {
    const queuedEvent = createQueuedReplayableEvent(
      blockedOn,
      domEventName,
      eventSystemFlags,
      targetContainer,
      nativeEvent,
    );
    if (blockedOn !== null) {
      const fiber = getInstanceFromNode(blockedOn);
      if (fiber !== null) {
        // 给被阻塞的 Fiber 打上连续事件水合优先级，调度器优先处理该组件水合，尽快解除阻塞
        attemptContinuousHydration(fiber);
      }
    }
    return queuedEvent;
  }
  existingQueuedEvent.eventSystemFlags |= eventSystemFlags;
  const targetContainers = existingQueuedEvent.targetContainers;
  if (
    targetContainer !== null &&
    targetContainers.indexOf(targetContainer) === -1
  ) {
    targetContainers.push(targetContainer);
  }
  return existingQueuedEvent;
}

function createQueuedReplayableEvent(
  blockedOn,
  domEventName,
  eventSystemFlags,
  targetContainer,
  nativeEvent,
) {
  return {
    blockedOn,
    domEventName,
    eventSystemFlags,
    nativeEvent,
    targetContainers: [targetContainer],
  };
}

export function dispatchEventForPluginEventSystem(
  domEventName,
  eventSystemFlags,
  nativeEvent,
  targetInst,
  targetContainer,
) {
  let ancestorInst = targetInst;
  if (
    // 当前 DOM 是 React 托管组件，不是第三方外部 DOM
    (eventSystemFlags & IS_EVENT_HANDLE_NON_MANAGED_NODE) === 0 &&
    // 当前事件支持冒泡委托（click/input 等常规事件，不是 scroll/focus 这类不冒泡事件）
    (eventSystemFlags & IS_NON_DELEGATED) === 0
  ) {
    const targetContainerNode = targetContainer;

    if (targetInst !== null) {
      let node = targetInst;

      mainLoop: while (true) {
        if (node === null) {
          return;
        }
        const nodeTag = node.tag;
        if (nodeTag === HostRoot || nodeTag === HostPortal) {
          let container = node.stateNode.containerInfo;
          // 判断 DOM 容器是否为当前事件绑定的根容器
          if (isMatchingRootContainer(container, targetContainerNode)) {
            break;
          }
          if (nodeTag === HostPortal) {
            let grandNode = node.return;
            while (grandNode !== null) {
              const grandTag = grandNode.tag;
              if (grandTag === HostRoot || grandTag === HostPortal) {
                const grandContainer = grandNode.stateNode.containerInfo;
                if (
                  isMatchingRootContainer(grandContainer, targetContainerNode)
                ) {
                  return;
                }
              }
              grandNode = grandNode.return;
            }
          }
 
          while (container !== null) {
            const parentNode = getClosestInstanceFromNode(container);
            if (parentNode === null) {
              return;
            }
            const parentTag = parentNode.tag;
            if (
              parentTag === HostComponent ||
              parentTag === HostText ||
              parentTag === HostHoistable ||
              parentTag === HostSingleton
            ) {
              node = ancestorInst = parentNode;
              continue mainLoop;
            }
            container = container.parentNode;
          }
        }
        node = node.return;
      }
    }
  }
  // 批量更新，内部回调所有 setState 会合并批量渲染，减少重渲染
  batchedUpdates(() =>
    // 事件插件体系真正执行逻辑，生成合成事件、遍历 Fiber 执行 onXxx 回调
    dispatchEventsForPlugins(
      domEventName,
      eventSystemFlags,
      nativeEvent,
      ancestorInst,
      targetContainer,
    ),
  );
}

function dispatchEventsForPlugins(
  domEventName,
  eventSystemFlags,
  nativeEvent,
  targetInst,
  targetContainer,
) {
  const nativeEventTarget = getEventTarget(nativeEvent);
  // 事件调度队列，数组结构，存储每条事件处理记录（包含阶段、回调、Fiber 实例、合成事件配置等）
  const dispatchQueue = [];
  extractEvents(
    dispatchQueue,
    domEventName,
    targetInst,
    nativeEvent,
    nativeEventTarget,
    eventSystemFlags,
    targetContainer,
  );
  // 按捕获先、冒泡后的顺序遍历队列，创建 SyntheticEvent 合成事件、执行用户回调、处理事件池、阻止冒泡 / 默认行为
  processDispatchQueue(dispatchQueue, eventSystemFlags);
}