React子组件捕获keydown事件并阻止向父组件传播的方法

现有父组件App通过监听document的keydown事件，实现按左右箭头增减计数器的功能，代码运行正常：

export default function App() {
  const [position, setPosition] = React.useState(0);
  const LEFT_ARROW = 37;
  const RIGHT_ARROW = 39;

  React.useEffect(() => {
    const keyboardHandler = (event) => {
      const key = parseInt(event.keyCode || event.which || 0, 10);
      switch (key) {
        case LEFT_ARROW:
          setPosition((p) => p - 1);
          break;
        case RIGHT_ARROW:
          setPosition((p) => p + 1);
          break;
        default:
          break;
      }
    };

    window.document.addEventListener("keydown", keyboardHandler);
    return () => {
      window.document.removeEventListener("keydown", keyboardHandler);
    };
  }, []);

  return (
    <div className="App">
      {position}
      <br />
      <Inner />
    </div>
  );
}

现在有一个带输入框的子组件Inner，希望输入框聚焦时，左右箭头事件不会触发父组件的计数器变化，但当前给子组件绑定document级keydown事件并调用stopPropagation()的方案无效，父组件仍会接收到事件：

export default function Inner() {
  const LEFT_ARROW = 37;
  const RIGHT_ARROW = 39;

  React.useEffect(() => {
    const keyboardHandler = (event) => {
      const key = parseInt(event.keyCode || event.which || 0, 10);
      switch (key) {
        case LEFT_ARROW:
          event.stopPropagation();
          break;
        case RIGHT_ARROW:
          event.stopPropagation();
          break;
        default:
          break;
      }
    };

    window.document.addEventListener("keydown", keyboardHandler);
    return () => {
      window.document.removeEventListener("keydown", keyboardHandler);
    };
  }, []);

  return <input name="test" />;
}

问题根源：事件绑定在document上时，stopPropagation()无法阻止事件传播——因为事件已经冒泡到document层级，此时调用它对已到达这里的事件监听没有作用。

方法1：直接给输入框绑定事件拦截 #

直接给子组件的input元素绑定keydown事件，让事件在冒泡到document之前被拦截：

export default function Inner() {
  const LEFT_ARROW = 37;
  const RIGHT_ARROW = 39;

  const handleKeyDown = (event) => {
    const key = parseInt(event.keyCode || event.which || 0, 10);
    if (key === LEFT_ARROW || key === RIGHT_ARROW) {
      event.stopPropagation();
    }
  };

  return <input name="test" onKeyDown={handleKeyDown} />;
}

这种方式下，输入框的keydown事件会在冒泡路径中提前被处理，调用stopPropagation()可以阻止父组件绑定在document上的监听器触发。

方法2：父组件判断焦点状态跳过逻辑 #

如果必须保留document级别的监听，可以在父组件的事件处理中检查当前焦点是否在目标输入框内，是的话就不执行计数器逻辑：

export default function App() {
  const [position, setPosition] = React.useState(0);
  const LEFT_ARROW = 37;
  const RIGHT_ARROW = 39;

  React.useEffect(() => {
    const keyboardHandler = (event) => {
      // 检查当前焦点是否是目标输入框
      const activeElement = document.activeElement;
      if (activeElement?.tagName === 'INPUT' && activeElement.name === 'test') {
        return; // 输入框聚焦时跳过计数器逻辑
      }

      const key = parseInt(event.keyCode || event.which || 0, 10);
      switch (key) {
        case LEFT_ARROW:
          setPosition((p) => p - 1);
          break;
        case RIGHT_ARROW:
          setPosition((p) => p + 1);
          break;
        default:
          break;
      }
    };

    window.document.addEventListener("keydown", keyboardHandler);
    return () => {
      window.document.removeEventListener("keydown", keyboardHandler);
    };
  }, []);

  return (
    <div className="App">
      {position}
      <br />
      <Inner />
    </div>
  );
}

这种方式不需要修改子组件，通过父组件主动判断焦点状态来控制逻辑执行。

方法3：利用事件捕获阶段拦截（不推荐） #

如果一定要在子组件的document监听中处理，可以利用事件捕获的优先级，但该方式依赖监听注册顺序，容易引发问题：

export default function Inner() {
  const LEFT_ARROW = 37;
  const RIGHT_ARROW = 39;

  React.useEffect(() => {
    const keyboardHandler = (event) => {
      const key = parseInt(event.keyCode || event.which || 0, 10);
      if (key === LEFT_ARROW || key === RIGHT_ARROW) {
        event.stopImmediatePropagation(); // 阻止同层级其他监听器执行
      }
    };

    // 第三个参数设为true，在捕获阶段监听
    window.document.addEventListener("keydown", keyboardHandler, true);
    return () => {
      window.document.removeEventListener("keydown", keyboardHandler, true);
    };
  }, []);

  return <input name="test" />;
}

这里用stopImmediatePropagation()代替stopPropagation()，可以阻止同一元素（document）上后续的事件监听器执行，但仅建议在特殊场景下使用。

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