HTML Academy · 课时

FormData API

Q: 「FormData API」这节课中我会学到什么？

使用 FormData 接口以编程方式收集表单数据 你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用 FormData 接口以编程方式收集表单数据

FormData API 是 CoddyKit 上的免费 HTML Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 HTML Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 HTML Academy 课程共包含 4 节课。

FormData 是什么

FormData 是一个表示表单字段及其值的内置对象，适合通过 fetch 或 XMLHttpRequest 直接提交。它可以处理文件上传、多部分编码以及任意键值对，无需手动序列化。

从表单构造

将一个 <form> 元素传递给构造函数：const data = new FormData(formElement)。结果包含每个有效的表单控件（带名称的输入框、选择框、文本区域、已选中的复选框和文件）。禁用及未选中的控件会自动排除。

document.forms.checkout.addEventListener("submit", async (e) => {
  e.preventDefault();
  const data = new FormData(e.target);
  await fetch("/api/checkout", { method: "POST", body: data });
});

使用 fetch 提交

将 FormData 作为 fetch 的请求体传递，会自动将请求的 Content-Type 设置为 multipart/form-data（并设置正确的边界）。请不要手动设置 Content-Type——fetch 需要自行生成边界。

append、设置、删除

data.append(key, value) 会添加一个键（允许重复）。data.set(key, value) 会替换该键已有的值。data.delete(key) 会删除某个键的所有值。data.has(key) 会检查该键是否存在。

const data = new FormData();
data.append("tag", "html");
data.append("tag", "css");
console.log(data.getAll("tag")); // ["html", "css"]

文件上传

FormData 会透明地处理文件：data.append("avatar", fileInput.files[0])。服务器会收到包含文件名和 MIME 类型的多部分上传。这是在现代代码中使用 fetch 上传文件的标准方式。

遍历

FormData 可迭代：for (const [key, value] of data) { ... }。如需特定的迭代方式，请使用 data.entries()、data.keys() 或 data.values()。这对于日志记录、验证或构建表单的 JSON 副本很有用。

转换为 JSON

如需发送 JSON 而不是多部分数据：Object.fromEntries(data) 会生成一个普通对象，但会丢失重复的键。要正确处理重复键，请遍历条目并手动分组。对于纯 JSON 接口，直接构建对象通常更简单，无需经过 FormData。

以编程方式填充

构造一个空的 FormData，然后手动追加值：const data = new FormData(); data.append("title", title); data.append("file", file);。当要发送的数据并非源自表单时，这种方式很有用（例如拖放的文件、接口响应或生成的有效负载）。

检测提交按钮

如果存在多个提交按钮，请将提交按钮作为第二个参数传递给 FormData：new FormData(form, e.submitter)。提交按钮的名称和值会包含在数据中——这对多操作表单很重要。

URLSearchParams 的近亲

对于 application/x-www-form-urlencoded 编码（不含文件时的默认表单编码），请从 FormData 构造 URLSearchParams：new URLSearchParams(data)。对于仅包含纯文本的表单，它比多部分编码开销更低。

常见陷阱

将 fetch 的 Content-Type 标头明确设置为“multipart/form-data”会破坏上传——浏览器将无法再添加所需的边界。发送 FormData 时请省略 Content-Type，让 fetch 负责处理。

知识检查

使用 fetch 发送 FormData 时，为什么不应手动设置 Content-Type？

总结

FormData 表示表单内容，并可通过 fetch 顺利提交，包括通过 multipart/form-data 上传文件。您可以从表单元素构造它，并按需追加、设置或删除条目，也可以进行遍历。发送时不要设置 Content-Type——fetch 会自动生成边界。对于仅包含文本的表单，请使用 URLSearchParams。

常见问题解答

「FormData API」课时是免费的吗？

是的 — 「FormData API」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 HTML Academy 课程的其余内容，请升级到 CoddyKit PRO。 HTML Academy 课程共包含 4 节课。

「FormData API」这节课中我会学到什么？

使用 FormData 接口以编程方式收集表单数据你通过在浏览器中直接运行的动手代码来练习 HTML Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 HTML Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 HTML Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「FormData API」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 HTML Academy 课中编写并运行代码吗？

能。每节 HTML Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 HTML Academy