Die FormData API

FormData ist ein integriertes Objekt, das Formularfelder und ihre Werte repräsentiert und sich zum direkten Senden über fetch oder XMLHttpRequest eignet. Es verarbeitet Datei-Uploads, Multipart-Kodierung und beliebige Schlüssel-Wert-Paare ohne manuelle Serialisierung.

Übergeben Sie dem Konstruktor ein <form>-Element: const data = new FormData(formElement). Das Ergebnis enthält jedes erfolgreiche Formularelement (benannte Inputs, Selects, Textareas, aktivierte Checkboxen und Dateien). Deaktivierte und nicht angehakte Elemente werden automatisch ausgeschlossen.

Wenn Sie FormData als Body von fetch übergeben, wird der Content-Type der Anfrage automatisch auf multipart/form-data gesetzt (mit der richtigen Boundary). Setzen Sie Content-Type nicht manuell — fetch muss die Boundary selbst erzeugen.

data.append(key, value) fügt einen Schlüssel hinzu (Dubletten sind erlaubt). data.set(key, value) ersetzt alle vorhandenen Werte für diesen Schlüssel. data.delete(key) entfernt alle Werte für einen Schlüssel. data.has(key) prüft, ob der Schlüssel vorhanden ist.

FormData verarbeitet Dateien transparent: data.append("avatar", fileInput.files[0]). Der Server empfängt einen Multipart-Upload mit dem Dateinamen und dem MIME-Typ der Datei. Dies ist die Standardmethode für Datei-Uploads mit fetch in modernem Code.

FormData ist iterierbar: for (const [key, value] of data) { ... }. Verwenden Sie data.entries(), data.keys() oder data.values() für bestimmte Iterationen. Das ist nützlich für Protokollierung, Validierung oder zum Erstellen einer JSON-Kopie des Formulars.

Um statt Multipart JSON zu senden, erzeugt Object.fromEntries(data) ein einfaches Objekt — dabei gehen doppelte Schlüssel verloren. Für die korrekte Verarbeitung doppelter Schlüssel iterieren Sie über die Einträge und gruppieren Sie sie manuell. Bei reinen JSON-APIs ist es einfacher, das Objekt direkt zu erstellen, ohne FormData zu verwenden.

Erstellen Sie ein leeres FormData-Objekt und hängen Sie Werte manuell an: const data = new FormData(); data.append("title", title); data.append("file", file);. Das ist nützlich, wenn die zu sendenden Daten nicht aus einem Formular stammen (per Drag-and-drop abgelegte Dateien, API-Antworten oder generierte Payloads).

Wenn mehrere Submit-Buttons vorhanden sind, übergeben Sie den Submitter als zweites Argument an FormData: new FormData(form, e.submitter). Name und Wert des Submitters werden in die Daten aufgenommen — wichtig für Formulare mit mehreren Aktionen.

Für die application/x-www-form-urlencoded-Kodierung (die standardmäßige Formular-Kodierung ohne Dateien) erstellen Sie URLSearchParams aus FormData: new URLSearchParams(data). Das ist für reine Textformulare effizienter als Multipart.

Das explizite Setzen des Content-Type-Headers von fetch auf "multipart/form-data" macht den Upload kaputt — der Browser kann die erforderliche Boundary nicht mehr hinzufügen. Lassen Sie Content-Type beim Senden von FormData weg und überlassen Sie die Verarbeitung fetch.

Warum sollten Sie Content-Type beim Senden von FormData mit fetch NICHT manuell setzen?

FormData repräsentiert Formularinhalte und lässt sich mit fetch problemlos senden — einschließlich Datei-Uploads über multipart/form-data. Erstellen Sie es aus einem Formularelement, fügen Sie Einträge hinzu, ersetzen oder löschen Sie sie und iterieren Sie bei Bedarf darüber. Setzen Sie Content-Type beim Senden nicht — fetch erzeugt die Boundary automatisch. Verwenden Sie URLSearchParams für urlencoded-Formulare, die nur Text enthalten.