FormData и отправка на сервер

Конструктор new FormData(form) обходит поля сам, и берёт не всё подряд, а только то, что браузер считает отправляемым: у поля должен быть name, оно не должно быть disabled, а чекбокс или радиокнопка — должны быть отмечены.

const fd = new FormData(document.getElementById("signup"));

console.log(fd.get("login"));
console.log(fd.get("news"));
console.log(fd.get("ads"));
console.log(fd.get("promo"));
console.log([...fd.keys()].length);

Это не каприз API: FormData повторяет ровно тот набор данных, который форма отправила бы и вообще без JavaScript. Значения в нём — строки или файлы: типов, которые были в разметке, там нет.

FormData похож на объект только на первый взгляд. Внутри — упорядоченный список пар, и одно имя может встречаться в нём несколько раз: два отмеченных чекбокса с одинаковым name дадут две записи. Поэтому и методов два: get возвращает первое значение, getAll — все.

const fd = new FormData(document.getElementById("prefs"));

console.log(fd.get("tag"));
console.log(fd.getAll("tag"));
console.log([...fd.keys()].join(","));
console.log(Object.fromEntries(fd).tag);

Для правки данных есть три метода: append добавляет ещё одну пару, set заменяет все значения этого имени одним, delete выносит их все.

const fd = new FormData(document.getElementById("cart"));

fd.append("item", "хлеб");
console.log(fd.getAll("item").length);

fd.set("item", "вода");
console.log(fd.getAll("item"));
console.log(fd.has("promo"));

Отправка — самая короткая часть темы: await fetch("/api/signup", { method: "POST", body: fd }). Никакой сериализации писать не нужно, fetch умеет принимать FormData телом напрямую. Обычно перехватывают событие submit, отменяют штатную отправку и собирают данные из event.target.

const form = document.getElementById("login");

form.addEventListener("submit", (event) => {
  event.preventDefault();
  const fd = new FormData(event.target);
  console.log(fd.get("email"));
  console.log([...fd.keys()].length);
});

form.requestSubmit(); // вместо клика человека

Заголовок Content-Type браузер выставляет сам — вместе со случайной строкой-разделителем. Убедиться в этом можно, не отправляя ничего: объект Request собирается по тем же правилам, что и запрос внутри fetch, но в сеть не ходит.

const fd = new FormData();
fd.append("email", "rico@mail.dev");

const req = new Request("https://example.com/api/signup", { method: "POST", body: fd });
console.log(req.method);

const type = req.headers.get("content-type");
console.log(type.startsWith("multipart/form-data"));
console.log(type.includes("boundary="));

Самая частая ошибка: дописать к fetch заголовок Content-Type: multipart/form-data вручную. Тогда в заголовке не будет boundary, и сервер прочитает тело как кашу. С FormData заголовки не трогают вообще.

Файл — единственное значение в FormData, которое не строка. Его берут из input.files или собирают вручную конструктором File; в теле запроса он уедет байтами, без base64 и без роста объёма на треть.

const fd = new FormData();
const file = new File(["hello"], "note.txt", { type: "text/plain" });
fd.append("doc", file);

const got = fd.get("doc");
console.log(got instanceof File);
console.log(got.name);
console.log(got.type);
console.log(got.size);

Из формы файл попадает сам — достаточно, чтобы у input type="file" был name. Тонкость: если человек ничего не выбрал, поле всё равно окажется в FormData — пустым файлом с именем "" и нулевым размером. Поэтому «файл приложен» проверяют по size, а не по наличию ключа. При multiple перебирают input.files и делают append под одним именем.

const input = document.getElementById("doc");

// имитируем выбор файла человеком
const box = new DataTransfer();
box.items.add(new File(["hello"], "a.txt", { type: "text/plain" }));
input.files = box.files;

const fd = new FormData(input.form);
console.log(fd.get("doc").name);
console.log(fd.get("doc").size);

Разница не в моде, а в форме тела. FormData уезжает как multipart/form-data: плоский список пар, где файл лежит байтами, а всё остальное — строками. JSON — это текст: в нём есть вложенность и типы, но нет места для двоичных данных.

const fd = new FormData();
fd.append("login", "rico");
fd.append("age", "30");

console.log(new URLSearchParams(fd).toString());
console.log(JSON.stringify(Object.fromEntries(fd)));
console.log(typeof Object.fromEntries(fd).age);

Приведение типов — всегда чья-то отдельная работа, ваша перед JSON.stringify или серверная после разбора. Практическое правило простое: есть файлы — FormData; нужна вложенная структура — JSON; нужно и то и другое — кладите файлы в FormData, а сложную часть добавьте туда же строкой: fd.append("meta", JSON.stringify(meta)).

FormData переживёт и смену инструментов. В React форму читают тем же new FormData(form), а в React 19 форма и вовсе отдаёт его сама — это разбирает статья «Неуправляемые поля, ref и FormData».