FormData — Schnittstelle · JavaScript-Referenz

Signatur

interface FormData

Beschreibung

FormData stellt eine geordnete Liste von Schlüssel/Wert-Paaren dar, genau so, wie ein HTML-Formular sie beim Absenden erzeugt. Die Werte sind entweder Zeichenketten oder File/Blob-Objekte. Das Objekt lässt sich direkt als body an fetch(), XMLHttpRequest.send() oder navigator.sendBeacon() übergeben. Der Browser kodiert es dann als multipart/form-data und setzt den Content-Type-Header samt boundary selbst.

Übergeben Sie dem Konstruktor ein <form>-Element, liest FormData alle erfolgreichen Steuerelemente aus: Felder mit name-Attribut, die nicht deaktiviert sind, angehakte Checkboxen und Radiobuttons sowie ausgewählte Dateien. Mit dem optionalen submitter kommt auch der Name und Wert des auslösenden Absende-Buttons in die Daten. Ohne Argument entsteht ein leeres Objekt, das Sie selbst befüllen.

Die wichtigsten Methoden sind:

append(name, value, filename?): fügt einen Wert hinzu. Doppelte Schlüssel sind erlaubt.
set(name, value, filename?): ersetzt alle vorhandenen Werte unter diesem Schlüssel.
get(name) / getAll(name): liest den ersten Wert bzw. alle Werte.
has(name) und delete(name): prüft bzw. entfernt einen Schlüssel.
entries(), keys(), values(): liefern Iteratoren. Das Objekt selbst ist iterierbar, for (const [k, v] of fd) entspricht also fd.entries().

FormData eignet sich vor allem für Datei-Uploads und dafür, bestehende Formulare ohne Seitenneuladen per AJAX abzusenden. Brauchen Sie URL-kodierte Daten oder Query-Strings, übergeben Sie das Objekt an new URLSearchParams(formData). Für JSON-APIs nutzen Sie Object.fromEntries(formData).

Parameter

Name	Typ	Default	Beschreibung
$form	HTMLFormElement		Optional. Ein `<form>`-Element, dessen aktuelle Feldwerte übernommen werden. Nur Felder mit `name`-Attribut werden berücksichtigt.
$submitter	HTMLButtonElement \| HTMLInputElement		Optional. Der Absende-Button (z. B. `event.submitter`). Sein `name`/`value` wird mit aufgenommen. Er muss zum Formular gehören und ein Absende-Button sein, sonst wird ein `TypeError` bzw. `NotFoundError` geworfen.

Rückgabewert

Typ

FormData

Beschreibung

Eine neue FormData-Instanz. Sie ist leer oder enthält die Daten des übergebenen Formulars.

Beispiele

Formular per fetch absenden (inkl. Submit-Button)

const form = document.querySelector('#kontakt');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  // event.submitter übernimmt Name und Wert des geklickten Buttons
  const data = new FormData(form, event.submitter);

  const response = await fetch('/api/kontakt', {
    method: 'POST',
    body: data // Content-Type NICHT manuell setzen!
  });
  console.log(response.ok ? 'Gesendet' : `Fehler: ${response.status}`);
});

Gesendet

FormData manuell aufbauen und Datei hochladen

const input = document.querySelector('input[type=file]');

const upload = async () => {
  const fd = new FormData();
  fd.append('titel', 'Urlaubsfoto');
  fd.append('tags', 'strand');
  fd.append('tags', 'sommer'); // doppelter Schlüssel erlaubt
  fd.append('bild', input.files[0], 'foto.jpg');

  console.log(fd.getAll('tags'));
  await fetch('/upload', { method: 'POST', body: fd });
};

input.addEventListener('change', upload);

["strand", "sommer"]

Iterieren und in JSON bzw. Query-String umwandeln

const fd = new FormData();
fd.set('name', 'Anna');
fd.set('stadt', 'Köln');

for (const [key, value] of fd) {
  console.log(`${key} = ${value}`);
}

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

name = Anna stadt = Köln {"name":"Anna","stadt":"Köln"} name=Anna&stadt=K%C3%B6ln

Blob aus erzeugten Daten anhängen

const fd = new FormData();
const csv = new Blob(['id;name\n1;Anna'], { type: 'text/csv' });
fd.append('export', csv, 'daten.csv');

const file = fd.get('export');
console.log(file instanceof File, file.name, file.type);

true daten.csv text/csv

// Wichtig · Fallstricke

Content-Type nicht selbst setzen: Wenn Sie FormData an fetch() übergeben, dürfen Sie 'Content-Type': 'multipart/form-data' nicht manuell angeben. Sonst fehlt die boundary, und der Server kann die Anfrage nicht auswerten.
Nur Felder mit name: Felder ohne name-Attribut, deaktivierte Felder (disabled) und nicht angehakte Checkboxen landen nicht in den Daten. readonly-Felder werden dagegen übernommen.
Werte werden zu Zeichenketten: Alles außer Blob/File wird in einen String umgewandelt. fd.append('n', 5) ergibt also "5", und null wird zu "null". Ein angehängter Blob wird beim Auslesen zu einem File, standardmäßig mit dem Namen "blob".
Object.fromEntries() verliert Mehrfachwerte: Bei doppelten Schlüsseln bleibt nur der letzte Wert erhalten. Nutzen Sie in dem Fall getAll().
Momentaufnahme: new FormData(form) liest die Werte zum Zeitpunkt des Aufrufs aus. Spätere Änderungen am Formular wirken sich nicht aus.
Kompatibilität: Das Interface wird in allen modernen Browsern unterstützt, auch in Web Workern (dort ohne form-Argument). Den Parameter submitter gibt es erst seit etwa 2022 (Chrome 112, Firefox 111, Safari 16.4). In Node.js ist FormData ab Version 18 global verfügbar.
Sicherheit: Werte aus dem Client sind nicht vertrauenswürdig. Prüfen Sie sie auf dem Server, insbesondere Dateinamen und MIME-Typen bei Uploads.

Siehe auch

URLSearchParams XMLHttpRequest Navigator.sendBeacon() HTMLFormElement SubmitEvent Blob File Object.fromEntries()