前端组件事件为什么别直接传 DOM Event：语义事件、数据边界与测试成本

一个很常见的重构事故是：最初的 TitleInput 只是普通输入框，于是组件把 ChangeEvent 原样传给父组件。半年后产品要支持自动清理空格、粘贴校验和可编辑标题，输入实现一换，十几个调用方、测试桩和类型声明一起报错。父组件真正需要的只是“标题改成了什么”，却被迫知道事件来自哪一种 DOM 节点。

问题不在事件对象，而在边界泄漏

DOM Event 本身没有错。问题出在组件把“浏览器如何报告一次输入”当成“业务层如何表达标题变化”。这两件事的生命周期不同：输入节点可以从 input 换成 textarea，甚至换成组合控件；业务动作仍然只是编辑标题、确认提交或取消编辑。

下面这种接口在小页面里看起来省事，但调用方已经和具体节点绑定：

import type { ChangeEvent } from "react";

type TitleInputProps = {
  value: string;
  onChange: (event: ChangeEvent) => void;
};

export function TitleInput({ value, onChange }: TitleInputProps) {
  return ;
}

// 父组件必须知道值藏在 currentTarget.value 里
 setDraftTitle(event.currentTarget.value)}
/>

把 DOM 事件翻译成语义值

更稳妥的做法是在组件内部读取事件，只把调用方需要的值发出去。这里的模式可以叫“语义事件边界”：边界内处理 DOM 细节，边界外只使用领域可理解的值与动作。

type TitleInputProps = {
  value: string;
  onValueChange: (nextValue: string) => void;
  onCommit: (value: string) => void;
};

export function TitleInput({
  value,
  onValueChange,
  onCommit,
}: TitleInputProps) {
  return (
     onValueChange(event.currentTarget.value)}
      onKeyDown={(event) => {
        if (event.key === "Enter") onCommit(event.currentTarget.value.trim());
      }}
    />
  );
}

 saveTitle({ title })}
/>

调用方现在不需要导入 React 事件类型，也不用知道组件内部是哪种输入节点。以后把内部实现改成 textarea，或者在提交前做 trim()，只要外部语义不变，父组件就不需要跟着修改。

什么时候语义回调最有价值

判断标准不是“事件对象高级不高级”，而是调用方是否真的需要浏览器层信息。如果父组件拿到事件后第一行永远只是读取 currentTarget.value，这个转换就应该下沉到子组件。

不要为了整洁把所有底层能力都藏掉

语义接口不是万能答案。比如拖拽组件要读取指针坐标，菜单触发器可能允许调用方阻止默认打开行为，输入法组合阶段也可能影响提交时机。如果组件把这些信息过早压成一个字符串，调用方反而只能绕过组件。

对这类底层组件，可以明确提供两个层次：

type SelectPayload = {
  id: string;
  source: "pointer" | "keyboard";
};

type ItemProps = {
  onSelect: (payload: SelectPayload) => void;
  onPointerDown?: (event: PointerEvent) => void;
};

常用业务路径走 onSelect，确实需要底层控制的使用者再接 onPointerDown。不要把两者塞进同一个含糊的 onChange，否则类型虽然少了，协议反而更难理解。

测试成本会暴露接口是否选错

如果测试一个保存标题的业务函数，必须先伪造 target、currentTarget 和事件方法，通常说明测试穿过了不该穿过的边界。语义接口只需要传入字符串或小对象，断言也更接近用户动作：

it("提交清理后的标题", () => {
  const onCommit = vi.fn();

  onCommit("Quarterly report");

  expect(onCommit).toHaveBeenCalledWith("Quarterly report");
});

事件适配层仍然要测，但只需在组件测试里覆盖一次：输入、按下 Enter、确认外部收到正确载荷。业务规则测试不再重复构造浏览器事件。

改造旧组件时的顺序

1. 统计父组件实际读取了事件的哪些字段。
2. 把常用字段收敛成值或结构化载荷，并起一个动作明确的名字。
3. 在组件内部保留 DOM Event 到语义载荷的转换。
4. 为确实需要底层行为的少数场景单独提供原生事件入口。
5. 先迁移调用方和测试，再删除旧接口，避免一次性断掉整条调用链。

常见问题

所有 onChange 都应该改成 onValueChange 吗？

不需要。原生元素包装器、无样式底层组件或需要完整事件能力的接口，继续使用 onChange(event) 更直观。业务组件才更适合语义回调。

同时传 value 和 event 可以吗？

可以，但要明确这是刻意保留底层能力，而不是怕做决定。若大多数调用方只用 value，可以把 event 放到单独的高级入口。

语义载荷会不会创建太多对象？

高频指针移动需要关注分配成本；普通表单编辑、保存和筛选操作通常更应优先保证边界清晰。简单值还可以直接传字符串或数字，不必总建对象。

Vue 或原生 Web Components 也适用吗？

适用。原则与框架无关：组件内部接住平台事件，对外发出稳定的值或动作；只有调用方确实依赖平台细节时才暴露原生事件。

最后怎么判断

先问一句：调用方关心的是“用户完成了什么”，还是“浏览器产生了什么事件”？前者使用语义值或动作，后者才传 DOM Event。把这个判断固定在组件边界，通常能减少类型耦合、重构扩散和无意义的事件测试桩，同时保留真正需要的底层控制能力。