JS原生表单序列化：FormData与URLSearchParams用法详解

图 0：原生表单序列化与双轨管道模型概览

一、表单序列化的核心机制与 DOM 提取流程

在标准的 HTML 规范中，表单序列化遵循严格的控件筛选与值抽取规则。当用户提交或前端脚本序列化一个 <form> 元素时，浏览器会遍历表单内部的所有可提交元素（Submittable Elements）。只有完全满足以下条件的输入控件才会被包含进最终的数据集合：

• 必须声明 name 属性：缺少 name 属性的控件会被直接忽略，不生成任何键名。
• 未处于禁用状态（disabled）：任何设置了 disabled 的控件均不参与序列化。
• 状态有效性筛选：对于 type="radio" 与 type="checkbox"，只有处于 checked 勾选状态的项才会被捕获；未勾选的单选和复选框不占用键值。
• 文件控件处理：type="file" 控件若未选取文件，在标准序列化中会产生一个文件名为空的空白 File 对象，而非直接忽略键名。

图 1：表单 DOM 提取到原生序列化的四个阶段流程图

原生表单处理的起点通常是获取表单 DOM 节点，并由专用的序列化容器完成结构化装载。下面我们依次深入探讨 FormData 与 URLSearchParams 的具体运用。

二、FormData：多媒体与复合表单的标准容器

FormData 接口是在 XMLHttpRequest Level 2 和现代 Fetch 规范中引入的核心标准。它的设计初衷是提供一种以键值对形式表示表单数据的数据结构，特别原生支持二进制数据（File 与 Blob）。

1. 实例化与自动抽取

FormData 最强大的能力在于可直接传入一个 HTMLFormElement，其构造函数会立即自动执行上述标准扫描，将表单内的全部可用控件转化为内部键值列表：

// 获取目标表单 DOM 元素
const formElement = document.querySelector('#profileForm');

// 构造函数自动完成全表单字段收集
const formData = new FormData(formElement);

// 此时 formData 内部已包含了所有带 name 属性的有效控件值

2. 核心操作 API

FormData 实例提供了一组类 Map 的增删改查方法，用于在提交前进行数据修剪或手动追加额外参数：

• formData.get(name)：返回指定键名对应的第一个值。若不存在则返回 null。
• formData.getAll(name)：返回一个数组，包含指定键名的所有值。这对于多选复选框（Checkbox）或 <select multiple> 尤为关键。
• formData.append(name, value, [filename])：向集合追加新值。即使同名键已存在，也会作为独立项并存，不覆盖旧值。当 value 是 Blob 或 File 时，第三个参数可指定传输文件名。
• formData.set(name, value, [filename])：设置指定键名的值。若该键已存在，会覆盖原有所有同名值；若不存在则新增。
• formData.delete(name)：彻底移除指定键名及其对应的所有值。
• formData.has(name)：检查集合中是否存在指定的键名，返回布尔值。

3. 数据遍历与查看

注意：FormData 实例直接调用 console.log(formData) 在绝大多数浏览器中仅打印出空对象或原型链信息，无法直接查看数据内容。必须通过其提供的迭代器方法进行遍历：

// 使用 for...of 遍历所有键值对
for (const [key, value] of formData.entries()) {
  if (value instanceof File) {
    console.log(`[文件字段] ${key}: 文件名=${value.name}, 大小=${value.size} 字节`);
  } else {
    console.log(`[文本字段] ${key}: ${value}`);
  }
}

三、URLSearchParams：Query String 编码与标准实现

与 FormData 专注于复合载荷不同，URLSearchParams 是针对 application/x-www-form-urlencoded 编码格式的专用原生实现。它专门用于构建和操作 URL 查询字符串以及表单 URL 编码载荷。

图 2：URLSearchParams 编码规范与内部处理机制原理图

1. 实例化模式与类型桥接

URLSearchParams 支持极具灵活性的入参类型，能够无缝桥接文本、对象以及 FormData：

// 方式 A：直接解析已有的 Query String
const params1 = new URLSearchParams('keyword=javascript&page=1');

// 方式 B：从普通对象或二维数组构造
const params2 = new URLSearchParams({ sort: 'desc', filter: 'active' });

// 方式 C（核心）：直接从 FormData 桥接构造
const form = document.querySelector('#searchForm');
const paramsFromForm = new URLSearchParams(new FormData(form));
console.log(paramsFromForm.toString());
// 示例输出: "keyword=%E5%8E%9F%E7%94%9F+JS&page=1"

2. 核心编码规范解析

URLSearchParams.prototype.toString() 的执行遵循严格的 W3C URL 规范，具有以下明确特征：

• 空格转为加号 +：区别于通用 encodeURIComponent 将空格转为 %20，表单 urlencoded 规范中空格必须被编码为 +。
• 中文及保留字符：采用标准的 UTF-8 字节流进行百分比编码（如中文字符转化为 %E4%B8%AD...）。
• 同名键保留：同名键不会合并或丢失，输出时按添加顺序通过 & 依次串联（例如 tag=html&tag=css）。

四、深度对比：FormData 与 URLSearchParams 的差异与协作

理解两者的边界，是选择合适表单提交方式的前提。两者的核心差异在于对二进制文件的支持程度以及协议编码层的处理方式。

图 3：FormData 与 URLSearchParams 核心特性对比矩阵

五、常见实战场景：原生 Fetch 提交与格式转换

场景 1：GET 请求自动拼接 Query String

在搜索筛选、数据分页等只读场景下，表单应当序列化为 URL 查询字符串并追加在请求地址后：

async function handleSearchSubmit(formElement) {
  // 1. 从表单直接构建 URLSearchParams
  const searchParams = new URLSearchParams(new FormData(formElement));

  // 2. 借助 URL 对象安全拼装，无需手动处理 '?' 与 '&'
  const url = new URL('/api/v1/articles', window.location.origin);
  url.search = searchParams.toString();

  // 示例请求地址: https://example.com/api/v1/articles?category=tech&keyword=js
  const response = await fetch(url, {
    method: 'GET',
    headers: { 'Accept': 'application/json' }
  });

  return await response.json();
}

场景 2：POST 提交带文件的 multipart/form-data（防坑重点）

当表单包含头像、文档等文件控件时，应直接将 FormData 实例作为 Fetch 的 body。

async function handleUploadSubmit(formElement) {
  const formData = new FormData(formElement);

  // 业务中追加额外参数
  formData.append('uploadedAt', Date.now().toString());

  const response = await fetch('/api/v1/upload', {
    method: 'POST',
    // 【切记】：不要在此处手动设置 'Content-Type': 'multipart/form-data'
    // 浏览器会自动计算包含 boundary 分隔符的正确头部：
    // multipart/form-data; boundary=----WebKitFormBoundary...
    body: formData
  });

  if (!response.ok) throw new Error('上传失败');
  return await response.json();
}

场景 3：POST 提交 application/x-www-form-urlencoded

传统后端接口常要求 application/x-www-form-urlencoded 格式。此时将 URLSearchParams 传入 Fetch 的 body 即可：

async function handleLoginSubmit(formElement) {
  const urlParams = new URLSearchParams(new FormData(formElement));

  const response = await fetch('/api/v1/login', {
    method: 'POST',
    // 传入 URLSearchParams 时，浏览器会自动设置正确的 Content-Type:
    // application/x-www-form-urlencoded;charset=UTF-8
    body: urlParams
  });

  return await response.json();
}

场景 4：表单转 JSON 提交与同名键（多选）处理

现代 RESTful 接口普遍采用 application/json。许多开发者习惯使用 Object.fromEntries(new FormData(form))，但该方法存在严重缺陷：遇到多选复选框或同名键时，后面的值会直接覆盖前面的值，导致多选数组丢失。

以下是正确兼顾单值与多值字段的健壮转换函数：

/**
 * 将 FormData 转换为完整的 JSON 数据对象，自动将多同名键聚合成数组
 * @param {FormData} formData 
 * @returns {Record<string, any>}
 */
function serializeFormDataToJson(formData) {
  const result = {};

  for (const key of formData.keys()) {
    // 若已处理过该键，则跳过避免重复计算
    if (Object.prototype.hasOwnProperty.call(result, key)) continue;

    const values = formData.getAll(key);
    // 若只有一个值，直接保留该值；若有多个值，保存为数组
    result[key] = values.length > 1 ? values : values[0];
  }

  return result;
}

// 使用示例：
async function handleJsonSubmit(formElement) {
  const formData = new FormData(formElement);
  const payload = serializeFormDataToJson(formData);

  const response = await fetch('/api/v1/user/settings', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
}

六、常见易错问题排查与技术选型决策

1. 关键排查清单

• 输入控件缺少 name 属性：这是初学者最常见失误。没有 name 属性的输入项在序列化时会被彻底忽略。
• 手动设置 multipart/form-data 导致 400/500 报错：若在 Fetch Headers 中写死 'Content-Type': 'multipart/form-data'，会导致浏览器无法自动拼接 boundary=xxx 随机分界标识符，服务端无法解析分块，必然导致解析失败。正确的做法是彻底不显式声明该 Header。
• 未执行表单原生校验：直接读取表单序列化数据会绕过浏览器内置验证。应在序列化前调用 formElement.reportValidity() 检查并拦截非法输入。
• Checkbox 未勾选时无默认值：未选中的复选框不会生成任何字段。若后端必须接收 false，需在提取后手动补齐或在 HTML 中使用 hidden 输入框预置。

图 4：表单序列化与网络提交技术选型决策树

七、总结

现代 Web 标准已经为表单序列化提供了坚实的原生支撑：

• 处理文件上传、二进制流、混合大表单，直接选择 FormData，配合 Fetch 自动处理 boundary。
• 处理URL 查询字符串拼接、标准 urlencoded 文本提交，直接使用 URLSearchParams。
• 两者的协同调用 new URLSearchParams(new FormData(form)) 是纯文本表单快速转 Query String 的高效桥梁。
• 向后端传输 JSON 结构时，需利用 formData.getAll() 妥善处理多值并存问题，避免简单使用 Object.fromEntries 导致的数据静默覆盖。

掌握这两者的特性与边界条件，便能在不引入任何外部依赖的前提下，优雅、安全地应对前端开发中的所有表单序列化需求。