FormDataEvent 统一拦截原生表单数据的实现

FormDataEvent 适合解决“多个原生表单都要补同一批字段、清理同一批 UI 字段”的重复代码问题。浏览器构造完表单条目后会触发 formdata 事件，事件的 formData 属性指向即将被提交或刚由构造器创建的 FormData。在这里统一调用 set()、append() 和 delete()，修改会直接反映到这份数据上。

官方文档：https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/formdata_event

目标是让多个原生表单共用一套数据加工

下面的小项目有资料表单、文件上传表单和订单表单。它们都需要写入时区与请求标识，同时删除仅供前端确认使用的字段。与其在每个 submit 回调里复制逻辑，不如给需要处理的表单增加 data-enrich-form 标记，再由一个共享监听器完成加工。

  
    昵称
    

  
    确认昵称
    

  保存
  保存并关闭

原生表单只会把“成功控件”加入 FormData：控件需要有 name，禁用控件不会进入数据，未选中的复选框通常也不会出现。按钮字段是否进入数据还取决于哪个提交按钮触发了提交，因此后面需要保留 submitter。

用 formdata 事件集中加工数据

最小实现可以直接监听表单自身。如果项目里的表单较多或会动态插入，可以在 document 的捕获阶段监听，再通过事件目标和数据属性筛选。这样不依赖事件冒泡差异，也不需要为每个新表单重复绑定。

function installFormDataInterceptor(root = document) {
  root.addEventListener(
    "formdata",
    (event) => {
      const form = event.target;

      // 只处理显式加入公共加工合同的原生表单。
      if (!(form instanceof HTMLFormElement)) return;
      if (!form.matches("[data-enrich-form]")) return;

      const data = event.formData;

      // set 保证公共单值字段只有一个最终值。
      data.set(
        "client_timezone",
        Intl.DateTimeFormat().resolvedOptions().timeZone,
      );
      data.set("request_id", crypto.randomUUID());

      // delete 移除只参与界面校验、不应发送给服务端的字段。
      data.delete("confirm_display_name");

      // append 适合允许重复出现的审计标签。
      data.append("client_capability", "native-formdata-event");
    },
    true, // 捕获阶段可统一覆盖多个表单，也能兼容不冒泡的实现。
  );
}

// 页面初始化时只安装一次共享处理器。
installFormDataInterceptor();

FormDataEvent.formData 属性本身是只读的，意思是不能给它重新赋一个对象；但这个属性返回的 FormData 可以修改。用 set 会替换同名字段，用 append 会保留旧值并增加一项，用 delete 会移除这个名称对应的全部条目。

把提交控制和数据加工分成两个监听器

formdata 事件发生在条目列表已经构造之后，它不是用来阻止提交的取消点。需要把提交改成 fetch 时，仍然监听 submit、调用 preventDefault()，然后构造 FormData。构造动作会再次触发前面的共享 formdata 处理器。

document.addEventListener(
  "submit",
  async (event) => {
    const form = event.target;

    // 没有 data-async-form 的表单继续走浏览器原生提交。
    if (!(form instanceof HTMLFormElement)) return;
    if (!form.matches("[data-async-form]")) return;

    event.preventDefault();

    // submit 事件由有效表单提交触发；这里保留防御式校验。
    if (!form.reportValidity()) return;

    const submitter = event.submitter;

    // 第二个参数保留实际点击按钮的 name/value。
    const data = submitter
      ? new FormData(form, submitter)
      : new FormData(form);

    try {
      const response = await fetch(form.action, {
        method: form.method || "POST",
        body: data,
        // 不要手工设置 Content-Type，浏览器需要生成 multipart boundary。
      });

      if (!response.ok) {
        throw new Error(`提交失败：HTTP ${response.status}`);
      }

      // 成功后由业务决定清空、跳转或显示状态。
      form.dataset.state = "success";
    } catch (error) {
      form.dataset.state = "error";
      console.error(error);
    }
  },
  true, // 捕获阶段统一接住页面内符合条件的表单。
);

这段代码把职责拆得很清楚：submit 处理器控制是否阻止默认提交、何时发请求和怎样处理响应；formdata 处理器只负责数据字段。以后换成原生导航提交、XHR 或其他传输方式，字段加工规则仍可复用。

FormData 构造器也会触发统一处理

统一处理并不只服务用户点击提交按钮。只要用带表单参数的构造器创建数据，浏览器也会在该表单上触发 formdata 事件。因此导出预览、离线保存或测试代码都能复用同一规则：

const form = document.querySelector("[data-enrich-form]");

// 从表单构造数据时，会触发已安装的 formdata 监听器。
const previewData = new FormData(form);

// entries() 用于检查最终键值；文件值仍会保持为 File 对象。
for (const [name, value] of previewData.entries()) {
  console.log(name, value);
}

不要用 new FormData() 创建空对象后期待表单事件自动出现。只有构造器接收具体表单，或浏览器为该表单构造提交数据时，才与这个表单的 formdata 事件关联。

四个容易漏掉的实现边界

还要注意安全边界：客户端补充的 request_id、角色、租户或价格字段都不可信。服务端必须重新校验和授权，不能因为这些字段由统一拦截器生成就直接采信。FormDataEvent 解决的是前端代码复用，不是安全证明。

验收时检查最终数据而不是输入框数量

完成实现后，建议用三组场景验收：普通文本表单、带文件的表单、包含两个提交按钮的表单。检查点如下：

• 每次构造 FormData 后都存在一个 client_timezone 和一个 request_id。
• confirm_display_name 已删除，原始输入框仍保留在页面中。
• 文件字段仍是 File，没有被字符串化。
• 点击不同按钮时，intent 值与实际 submitter 一致。
• 未标记 data-enrich-form 的表单不会被公共规则修改。
• 动态插入的表单仍能被 document 捕获监听器处理。
• 网络失败时进入错误状态，不会静默显示成功。

相关问题

formdata 事件能阻止表单提交吗？

不能把它当作取消点。需要阻止默认提交时监听 submit 并调用 preventDefault()，formdata 只负责读取和修改已构造的数据。

为什么 disabled 输入框没有出现在 FormData 中？

FormData 按原生表单的成功控件规则收集字段；禁用控件、没有 name 的控件和未选中的复选框通常不会加入条目列表。

统一拦截时用 set 还是 append？

公共单值字段用 set，确保不会重复；允许同名多值的标签、附件或筛选条件使用 append。