# FormData 参考

URL: https://caijiao.org/reference/web-api/formdata
Source: docs/reference/web-api/formdata.md
Description: FormData Reference，整理表单字段读取、文件上传、append、set、entries、fetch 提交和常见错误。

FormData 用于构造表单数据，常见于文件上传、表单提交和 `multipart/form-data` 请求。它可以直接从 `<form>` 元素创建，也可以手动追加字段。

## 语法

```js
const formData = new FormData(form);
formData.append("name", "caijiao");
```

## 常用方法

| 方法 | 说明 |
| --- | --- |
| `append(name, value)` | 追加字段，允许同名多值 |
| `set(name, value)` | 设置字段，会覆盖同名旧值 |
| `get(name)` | 读取第一个字段值 |
| `getAll(name)` | 读取全部同名字段值 |
| `delete(name)` | 删除字段 |
| `entries()` | 遍历字段键值对 |

## 返回值

FormData 本身是可迭代对象。字段值可能是字符串，也可能是 `File`。

## 示例

```js
const form = document.querySelector("form");
const formData = new FormData(form);

formData.append("source", "web");

await fetch("/api/upload", {
  method: "POST",
  body: formData,
});
```

## 使用要点

- 上传文件时不要手动设置 `Content-Type`，浏览器会自动带上 multipart boundary。
- 用 `Object.fromEntries(formData)` 转对象只适合普通文本字段，文件字段要单独判断。
- 同名字段可能有多个值，例如多选框和多文件上传。

## 常见错误

- 手动设置 `Content-Type: multipart/form-data` 导致 boundary 缺失，服务端无法解析。
- 把 `File` 当字符串处理，导致文件上传逻辑丢失。
- 使用 `get()` 读取多选字段，只拿到第一个值。

## 相关内容

- [Web API Reference](/reference/web-api/)
- [Blob](/reference/web-api/blob)
- [JavaScript 如何把 FormData 转对象](/how-to/javascript/formdata-to-object)
- [Fetch 如何上传文件](/how-to/javascript/upload-file-fetch)
- [JavaScript 教程](/javascript/)
- [MDN FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData)