FormData.append() — Methode · JavaScript-Referenz

Signatur

FormData.prototype.append(name, value, filename)

Beschreibung

append() fügt einem FormData-Objekt einen neuen Eintrag hinzu. Anders als set() werden bestehende Werte mit demselben Schlüssel nicht überschrieben. Der neue Wert kommt als weiterer Eintrag dazu. So lassen sich mehrere Werte unter einem Namen übertragen, zum Beispiel mehrere ausgewählte Dateien oder Checkbox-Werte.

Als Wert ist entweder ein String oder ein Blob bzw. eine File erlaubt. Alle anderen Typen (Zahlen, Booleans, Objekte) werden automatisch in einen String umgewandelt. Bei einem Blob bestimmt der optionale dritte Parameter filename den Dateinamen, den der Server im Content-Disposition-Header sieht.

Typischerweise wird FormData mit append() programmatisch aufgebaut und dann per fetch() oder XMLHttpRequest verschickt. Der Browser kodiert den Inhalt dabei automatisch als multipart/form-data und setzt den passenden boundary-Parameter im Header.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Feldes, unter dem der Wert eingetragen wird.
$value Pflicht	string \| Blob \| File		Wert des Feldes. Alles, was kein `Blob` ist, wird in einen String umgewandelt.
$filename	string	"blob" bei Blob, bei File dessen name	Dateiname, der dem Server mitgeteilt wird. Gilt nur, wenn `value` ein `Blob` oder eine `File` ist.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das FormData-Objekt wird direkt verändert, daher ist keine Verkettung möglich.

Beispiele

Einfache Felder hinzufügen und mehrfache Werte

const fd = new FormData();
fd.append('benutzer', 'anna');
fd.append('tags', 'js');
fd.append('tags', 'web'); // zweiter Wert, kein Überschreiben
fd.append('alter', 42);   // wird zu "42"

console.log(fd.get('tags'));
console.log(fd.getAll('tags'));
console.log(typeof fd.get('alter'));

js ["js", "web"] string

Mehrere Dateien aus einem Input hochladen

const input = document.querySelector('#dateien'); // <input type="file" multiple>

const hochladen = async () => {
  const fd = new FormData();
  for (const datei of input.files) {
    fd.append('dokumente[]', datei);
  }
  fd.append('ordner', 'rechnungen');

  // KEINEN Content-Type setzen – der Browser erzeugt die boundary selbst
  const res = await fetch('/api/upload', { method: 'POST', body: fd });
  console.log(res.status);
};

input.addEventListener('change', hochladen);

200

Blob mit Dateinamen anhängen (z. B. Canvas-Export)

const canvas = document.querySelector('canvas');

canvas.toBlob(async (blob) => {
  const fd = new FormData();
  fd.append('avatar', blob, 'avatar.png');
  fd.append('meta', new Blob([JSON.stringify({ breite: canvas.width })], { type: 'application/json' }), 'meta.json');

  await fetch('/api/avatar', { method: 'POST', body: fd });
  console.log(fd.get('avatar').name);
}, 'image/png');

avatar.png

// Wichtig · Fallstricke

append() oder set()? append() hängt Werte an, set() ersetzt alle vorhandenen Werte des Schlüssels. Wird append() versehentlich mehrfach aufgerufen, zum Beispiel in einem erneut ausgelösten Event-Handler, entstehen doppelte Einträge.
Kein Content-Type von Hand setzen: Setzt man bei fetch den Header multipart/form-data selbst, fehlt die boundary und der Server kann den Body nicht lesen.
Automatische String-Umwandlung: Objekte werden zu "[object Object]". Strukturierte Daten also vorher mit JSON.stringify() umwandeln.
null wird zu "null", undefined zu "undefined". Leere Werte daher vor dem Anhängen herausfiltern.
Der Parameter filename gilt nur für Blobs. Bei einem String-Wert mit drei Argumenten wirft der Aufruf einen TypeError.
Der Inhalt lässt sich nicht einfach per console.log(fd) ansehen. Zum Debuggen for (const [k, v] of fd) oder [...fd.entries()] verwenden.
Kompatibilität: in allen modernen Browsern und in Web Workern verfügbar. In Node.js ist FormData ab Version 18 global vorhanden (über undici).

Siehe auch

FormData FormData.set() FormData.get() FormData.getAll() FormData.delete() Blob File