如何在document上创建React SyntheticEvent键盘事件监听器？

你无法直接在document对象上绑定React合成事件（SyntheticEvent）。React的合成事件系统是框架层基于根节点事件委托实现的封装，本身没有提供把合成事件直接绑定到document、window这类全局对象的API。

你遇到的两类方案表现差异，和事件是原生还是合成没有直接关系：

• 外层容器绑定onKeyDown能读到最新state、refs，是因为每次组件重渲染时，React都会把持有最新闭包的回调函数绑定到事件监听上，执行时自然能拿到最新值
• document.addEventListener绑定的原生事件读到旧值，是典型的闭包陈旧问题：你大概率只在组件首次挂载时绑定了一次回调，这个回调持有的是首次渲染时的state、refs引用，后续组件重渲染不会更新这个已经绑定的函数，自然会读到过期值

另外你提到的外层容器捕获不到浮层按键事件，和元素的absolute/fixed定位无关：这类浮层（汉堡菜单、全屏预览图、弹窗等）通常会通过Portal挂载到外层容器的DOM子树之外（比如直接挂到document.body下），或者内部调用了e.stopPropagation()阻止事件冒泡，自然无法把事件传递到你绑定监听的外层容器上。

方案1：修复原生全局事件的闭包问题（稳定性最高，100%全局捕获） #

不需要强行使用合成事件，只要解决原生事件绑定的闭包陈旧问题，就能实现全局无遗漏的按键监听，同时回调里能正常访问最新的state、refs值，优先推荐这种写法。

写法A：通过ref持有最新回调（性能最优） #

用ref存储每次渲染生成的最新处理函数，原生事件只在挂载时绑定一次，触发时调用ref中存储的最新回调即可，不会频繁解绑/绑定事件：

import { useEffect, useRef, useState } from 'react';

function GlobalKeyListener() {
  // 业务中用到的state、ref
  const [activeKey, setActiveKey] = useState('');
  const menuRef = useRef(null);

  // 用ref存储最新的按键处理逻辑
  const keyDownHandlerRef = useRef();
  // 每次组件重渲染都更新ref中存储的处理函数，保证函数持有最新的闭包引用
  keyDownHandlerRef.current = (e) => {
    // 这里可以正常访问所有最新的state、ref值，不存在过期问题
    console.log('当前按下的键：', e.key);
    console.log('最新state值：', activeKey);
    console.log('最新ref值：', menuRef.current);

    // 自定义业务逻辑，比如按ESC关闭菜单
    if (e.key === 'Escape' && menuRef.current) {
      menuRef.current.close();
    }
  };

  useEffect(() => {
    // 挂载时只绑定一次原生事件
    const listener = (e) => {
      keyDownHandlerRef.current(e);
    };
    document.addEventListener('keydown', listener);
    // 卸载时移除监听，避免内存泄漏
    return () => document.removeEventListener('keydown', listener);
  }, []);

  return null; // 这个组件不需要渲染任何内容，只做全局事件绑定
}

只需要把这个组件挂在应用最外层，就能实现全局按键监听。

写法B：正确配置依赖，更新时重新绑定事件 #

如果回调依赖的响应式变量不多，也可以把所有依赖项加入useEffect的依赖数组，依赖变化时自动解绑旧回调、绑定新回调：

useEffect(() => {
  const handleKeyDown = (e) => {
    // 这里访问的所有值都是最新的
    console.log(activeKey, menuRef.current);
  };
  document.addEventListener('keydown', handleKeyDown);
  return () => document.removeEventListener('keydown', handleKeyDown);
}, [activeKey, menuRef.current]); // 把回调中用到的所有响应式值加入依赖数组

注意：如果依赖项更新非常频繁，这种写法会反复执行事件绑定/解绑逻辑，性能弱于ref持有回调的写法。

方案2：根节点绑定捕获阶段合成事件 #

React 17及以上版本中，合成事件默认委托到应用挂载的根节点而非document。你可以给覆盖全视口的根节点绑定捕获阶段的键盘事件监听，捕获阶段的事件会先于所有子元素的冒泡事件触发，不会被子元素的stopPropagation拦截：

function App() {
  const handleKeyDown = (e) => {
    // 这里是合成事件，逻辑和普通合成事件完全一致
    console.log('触发合成事件keydown', e);
  };

  return (
    <div
      onKeyDownCapture={handleKeyDown}
      tabIndex={-1} // 普通div需要加这个属性才能接收键盘事件
      style={{ width: '100vw', height: '100vh' }}
    >
      {/* 所有应用内容，包括通过Portal挂载的浮层 */}
    </div>
  );
}

注意：这个方案要求所有浮层必须通过React Portal挂载在当前根节点的DOM上下文下，如果有第三方组件直接把DOM插到body上且不经过Portal，还是会出现事件漏捕获的问题，稳定性不如原生全局绑定方案。

• 不要尝试手动实例化React的SyntheticEvent对象绑定到全局监听上。React内部对合成事件做了池化回收处理，手动构造的事件对象不仅无法匹配React的事件生命周期，还会引发内存泄漏、事件状态错乱等问题，完全没有必要。
• 如果用React 18的严格模式开发，全局绑定原生事件时，一定要在useEffect的清理函数里移除对应监听，否则会出现重复绑定、回调多次触发的问题。
• 给非交互类DOM节点（比如普通div）绑定键盘合成事件时，必须给节点加tabIndex={-1}属性，否则节点无法获得焦点，也就接收不到键盘事件。

内容的提问来源于stack exchange，提问作者martolini