FormData.append: примеры (JAVASCRIPT)

Базовые примеры использования

Создание простого объекта FormData и добавление текстовых данных.

const formData = new FormData();
formData.append('username', 'Иван Петров');
formData.append('email', 'ivan@example.com');

// Для проверки выведем значения
for (let [key, value] of formData.entries()) {
  console.log(key, value);
}

username Иван Петров
email ivan@example.com

Добавление файла с указанием имени и без.

const fileInput = document.querySelector('input[type="file"]');
const formData = new FormData();

// Предположим, что пользователь выбрал один файл
const file = fileInput.files[0];
formData.append('userfile', file); // Имя файла будет взято из объекта File
formData.append('avatar', file, 'my-avatar.png'); // Имя файла задано явно

Добавление нескольких значений под одним ключом.

const formData = new FormData();
formData.append('tags', 'JavaScript');
formData.append('tags', 'FormData');
formData.append('tags', 'API');

for (let value of formData.getAll('tags')) {
  console.log(value);
}

JavaScript
FormData
API

Похожие методы в JavaScript

Объект FormData предоставляет другие методы для управления данными.

• FormData.set(name, value[, filename]): Устанавливает новое значение для ключа. Если ключ уже существует, его предыдущие значения заменяются новым. В остальном синтаксис аналогичен append(). Предпочтительнее, когда нужно гарантировать единственное значение для поля.
• FormData.delete(name): Удаляет все значения, связанные с заданным ключом.
• FormData.get(name): Возвращает первое значение, связанное с ключом.
• FormData.getAll(name): Возвращает массив всех значений, связанных с ключом. Это ключевое отличие от append(), который позволяет хранить такие массивы.
• FormData.has(name): Возвращает логическое значение, указывающее, существует ли ключ.

Для отправки простых данных в формате x-www-form-urlencoded может использоваться интерфейс URLSearchParams, но он не поддерживает передачу файлов.

Аналоги в других языках программирования

В разных языках и средах существуют свои способы работы с данными форм, особенно для загрузки файлов.

PHP

В PHP данные формы, отправленные с кодировкой multipart/form-data, автоматически становятся доступны в суперглобальных массивах $_POST, $_FILES. Аналога для динамического построения нет, но можно эмулировать.

// Отправка с помощью cURL в PHP
$postData = [
    'field1' => 'value1',
    'file1' => new CURLFile('/path/to/file.jpg')
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
// ... дальнейшая настройка и выполнение запроса

Python (requests)

Библиотека requests позволяет легко отправлять данные формы и файлы.

import requests

url = 'https://httpbin.org/post'
data = {'key': 'value'}
files = {'file': open('report.xls', 'rb')}

r = requests.post(url, data=data, files=files)

C (libcurl)

Используется структура curl_mime для создания сложных составных сообщений.

CURL *curl = curl_easy_init();
curl_mime *mime;
curl_mimepart *part;
if(curl) {
  mime = curl_mime_init(curl);
  part = curl_mime_addpart(mime);
  curl_mime_name(part, "field");
  curl_mime_data(part, "value", CURL_ZERO_TERMINATED);
  part = curl_mime_addpart(mime);
  curl_mime_name(part, "file");
  curl_mime_filedata(part, "filename.jpg");
  curl_easy_setopt(curl, CURLOPT_MIMEPOST, mime);
  // ... выполнение запроса и очистка
}

Типичные ошибки

1. Попытка передать нестроковое значение в качестве имени поля (ключ).

const formData = new FormData();
formData.append(123, 'value'); // Ключ будет преобразован в строку "123"
// Ошибки не будет, но это может привести к неочевидному поведению.

2. Отправка объекта FormData без правильных заголовков. При использовании Fetch API или XMLHttpRequest заголовок Content-Type устанавливать не нужно – браузер сделает это сам, установив правильную границу (boundary) для multipart/form-data.

// НЕПРАВИЛЬНО
fetch('/api/upload', {
  method: 'POST',
  headers: {
    'Content-Type': 'multipart/form-data' // Браузер сам установит правильный заголовок с boundary
  },
  body: formData
});

// ПРАВИЛЬНО
fetch('/api/upload', {
  method: 'POST',
  body: formData // Заголовок Content-Type НЕ задается явно
});

3. Непонимание разницы между append и set.

const fd = new FormData();
fd.append('key', 'first');
fd.append('key', 'second');
console.log(fd.getAll('key')); // ['first', 'second']

fd.set('key', 'third');
console.log(fd.getAll('key')); // ['third'] (все предыдущие значения удалены)

История изменений

Спецификация FormData API была стандартизирована как часть XMLHttpRequest Level 2 и теперь включена в стандарт WHATWG. Сам метод append() с тремя аргументами (включая необязательный filename) поддерживается во всех современных браузерах.

Существенных изменений в синтаксисе метода за последние годы не было. Основное развитие связано с интеграцией FormData с Fetch API и поддержкой в Node.js (например, через модуль form-data или встроенную глобальную реализацию в некоторых версиях).

Стандарт разрешает передавать в качестве значения не только строки и Blob/File, но и объекты USVString, что на практике для разработчика несущественно.

Расширенные примеры применения

Пример динамического построения формы из данных объекта, включая вложенные структуры.

const data = {
  user: { name: 'Мария', id: 42 },
  files: [document.getElementById('file1').files[0]],
  preferences: ['dark', 'compact']
};

const formData = new FormData();
// Для объектов используется JSON-сериализация
formData.append('user', JSON.stringify(data.user));

// Для массивов – несколько вызовов append с одним ключом или JSON
if (data.files && data.files.length > 0) {
  data.files.forEach(file => formData.append('files', file));
}

// Отправка
fetch('/api/update', { method: 'POST', body: formData });

Комбинирование данных из HTML-формы и программно добавленных полей.

const htmlForm = document.getElementById('myForm');
const formData = new FormData(htmlForm); // Инициализация данными формы

// Добавление служебной информации
formData.append('csrf_token', 'abc123');
formData.append('timestamp', Date.now());

// Добавление canvas как файла
const canvas = document.getElementById('myCanvas');
canvas.toBlob(function(blob) {
  formData.append('canvas_image', blob, 'canvas.png');
  // Теперь можно отправить formData
});

Использование с третьим параметром filename для Blob.

const textBlob = new Blob(['Hello, world!'], { type: 'text/plain' });
const formData = new FormData();
formData.append('text_file', textBlob, 'custom-filename.txt');

// При отправке сервер получит файл с именем "custom-filename.txt"
// и заголовком: Content-Disposition: form-data; name="text_file"; filename="custom-filename.txt"

Создание и отправка данных FormData в Node.js с помощью библиотеки form-data.

const FormData = require('form-data');
const fs = require('fs');
const http = require('http');

const form = new FormData();
form.append('my_field', 'my value');
form.append('my_buffer', Buffer.from('some data'));
form.append('my_file', fs.createReadStream('/path/to/file.jpg'));

const request = http.request({
  method: 'post',
  host: 'example.com',
  path: '/upload',
  headers: form.getHeaders() // Важно: получить правильные заголовки
});

form.pipe(request);