React 事件处理与 TypeScript 类型系统：从合成事件到泛型 Hook 的类型安全实践 - 简希博客

React 的事件系统因为合成事件（SyntheticEvent）的存在，类型标注比 DOM 原生事件多了一层抽象。很多开发者在这上面反复踩坑——要么用了错误的 Event 类型，要么在泛型组件里搞丢了事件回调的类型。这篇把常见的坑和最佳实践一次性讲清楚。

一、合成事件的基础类型

React 合成事件不是 MouseEvent，是 React.MouseEvent。这一点写错了 TypeScript 不会直接报错，但后续访问 currentTarget 等属性时类型推断会错。

// ❌ 错误：用了 DOM 原生类型
function handleClick(e: MouseEvent) {
  console.log(e.currentTarget.value);
  //              ^? EventTarget | null —— 不是你期望的 HTMLButtonElement
}

// ✅ 正确：使用 React 合成事件类型
function handleClick(e: React.MouseEvent<HTMLButtonElement>) {
  console.log(e.currentTarget.value);
  //              ^? HTMLButtonElement —— 类型精确
}

React 提供了完整的合成事件类型表：

// 常用事件类型速查
React.MouseEvent<T>         // onClick, onMouseDown, onMouseUp...
React.KeyboardEvent<T>      // onKeyDown, onKeyUp, onKeyPress
React.ChangeEvent<T>        // onChange (表单元素)
React.FormEvent<T>          // onSubmit, onReset
React.FocusEvent<T>         // onFocus, onBlur
React.ClipboardEvent<T>     // onCopy, onPaste, onCut
React.DragEvent<T>          // 拖拽事件

泛型参数 T 指定 currentTarget 的元素类型，这个信息会贯穿整个事件处理链。

二、表单事件的类型陷阱

onChange 是高频事件，同时也是类型标注最容易偷懒的地方：

// ❌ 坏：用 any 逃避类型
<input onChange={(e: any) => setName(e.target.value)} />

// ❌ 另一种坏：用 Event（太宽泛）
<input onChange={(e: Event) => {
  const target = e.target as HTMLInputElement; // 需要手动断言
}} />

// ✅ 好：正确的合成事件类型
<input onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
  setName(e.target.value); // 类型自动推断为 string
}} />

不同类型的表单元素对应不同的 onChange 细节：

// input[type="text"]：value 是 string
const handleTextChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  console.log(e.target.value); // string
};

// input[type="checkbox"]：checked 才是关注点
const handleCheckChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  console.log(e.target.checked); // boolean
};

// select：value 类型取决于 option 的 value
const handleSelectChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
  console.log(e.target.value); // string
};

三、泛型组件中传递事件回调

当组件是泛型的时候，事件回调的类型传递容易断裂：

// ❌ 坏：泛型丢失，回调类型退化为 any
type ListProps<T> = {
  items: T[];
  onSelect: (item: T) => void; // 泛型 T 还在
  renderItem: (item: T) => React.ReactNode;
};

// ❌ 用户在 onClick 里需要手动标注
<button onClick={(e) => {
  onSelect(item);
  // e 的类型是 React.MouseEvent<HTMLButtonElement>，但 T 丢了
}}>

通用泛型事件回调的场景，推荐用类型工具提取：

type EventHandler<E extends React.SyntheticEvent<any>> = (e: E) => void;

type ListItemProps<T> = {
  item: T;
  onClick: EventHandler<React.MouseEvent<HTMLLIElement>>;
};

四、自定义 Hook 里的事件类型

自定义 Hook 封装事件逻辑时，类型标注决定了 Hook 的复用质量：

// ❌ 差：硬编码元素类型，Hook 不可复用
function useClickOutside(callback: () => void) {
  const ref = useRef<HTMLDivElement>(null);
  // 只能用在 div 上
}

// ✅ 好：泛型让 Hook 通用于任何 HTML 元素
function useClickOutside<T extends HTMLElement>(
  callback: (e: MouseEvent) => void
) {
  const ref = useRef<T>(null);

  useEffect(() => {
    const handler = (e: MouseEvent) => {
      if (ref.current && !ref.current.contains(e.target as Node)) {
        callback(e);
      }
    };
    document.addEventListener('mousedown', handler);
    return () => document.removeEventListener('mousedown', handler);
  }, [callback]);

  return ref; // 返回类型：React.RefObject<T>
}

// 使用时自动推断元素类型
const divRef = useClickOutside<HTMLDivElement>(() => setIsOpen(false));
const ulRef = useClickOutside<HTMLUListElement>(() => setSelected(null));

五、事件冒泡与 preventDefault 的类型问题

// submit 事件的 preventDefault 不需要额外标注
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault();
  // FormEvent 上 preventDefault 已声明
};

// 嵌套事件中阻止冒泡
const handleInnerClick = (e: React.MouseEvent<HTMLButtonElement>) => {
  e.stopPropagation();
  // 不会触发父级的 onClick
  doSomething();
};

// 异步操作后访问事件对象 —— 这是经典 Bug
const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
  // ❌ 事件已经被回收
  setTimeout(() => {
    console.log(e.target); // null 或报错
  }, 100);

  // ✅ 提前提取需要的值
  const target = e.currentTarget;
  setTimeout(() => {
    console.log(target); // 安全
  }, 100);
};

React 合成事件池（v17 前）会回收事件对象，虽然 v17+ 已经移除事件池，但异步访问事件对象仍然是不推荐的模式，TypeScript 不会帮你发现这个问题。

六、总结

场景	推荐做法
onClick/onMouseDown 等	`React.MouseEvent<元素类型>`
onChange（表单）	`React.ChangeEvent<元素类型>`
onSubmit	`React.FormEvent<HTMLFormElement>`
键盘事件	`React.KeyboardEvent<元素类型>`
泛型组件事件	保持泛型 T 贯穿回调链，不要降级为 any
自定义 Hook 事件	泛型 `T extends HTMLElement` 绑定 ref