FormData.set() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

Mit FormData.set() legen Sie den Wert eines Feldes in einem FormData-Objekt fest. Gibt es den Schlüssel schon, werden alle vorhandenen Einträge mit diesem Namen entfernt und durch genau einen neuen ersetzt. Die Position bleibt dabei erhalten: Der neue Wert steht dort, wo der erste alte Eintrag stand. Gibt es den Schlüssel noch nicht, wird er am Ende angehängt.

Genau hier liegt der Unterschied zu FormData.append(): append() fügt immer einen weiteren Eintrag hinzu, sodass ein Schlüssel mehrere Werte haben kann (z. B. tags[] oder eine Auswahl mehrerer Dateien). set() nehmen Sie, wenn ein Feld genau einen Wert haben soll, etwa um ein Formularfeld vor dem Absenden zu überschreiben, ein CSRF-Token einzufügen oder ein Bild durch eine verkleinerte Fassung zu ersetzen.

Als Wert sind Zeichenketten sowie Blob- bzw. File-Objekte erlaubt. Alle anderen Werte (Zahlen, Booleans, Objekte) werden in eine Zeichenkette umgewandelt. Bei einem Blob können Sie mit dem dritten Parameter einen Dateinamen angeben, den der Server im multipart/form-data-Body zu sehen bekommt.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Feldes, also der Schlüssel. Groß- und Kleinschreibung wird unterschieden.
$value Pflicht	string \| Blob \| File		Neuer Wert. Alles, was kein `Blob` ist, wird mit `String()` in eine Zeichenkette umgewandelt.
$filename	string	"blob" bei Blob, bei File dessen name	Dateiname, der an den Server übermittelt wird. Nur erlaubt, wenn `value` ein `Blob` ist. Aus einem `Blob` wird dann intern ein `File` mit diesem Namen.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das FormData-Objekt wird direkt verändert, Aufrufe lassen sich also nicht verketten.

Beispiele

set() im Vergleich zu append()

const fd = new FormData();
fd.append('tag', 'js');
fd.append('tag', 'web');
console.log(fd.getAll('tag'));

// set() ersetzt alle vorhandenen Werte durch einen einzigen
fd.set('tag', 'formdata');
console.log(fd.getAll('tag'));

// Zahlen werden in Zeichenketten umgewandelt
fd.set('seite', 2);
console.log(typeof fd.get('seite'), fd.get('seite'));

['js', 'web'] ['formdata'] string 2

Formularfelder vor dem Absenden überschreiben und ergänzen

const form = document.querySelector('#profil-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const fd = new FormData(form);

  // Eingabe normalisieren und CSRF-Token setzen
  fd.set('email', fd.get('email').trim().toLowerCase());
  fd.set('csrf_token', document.querySelector('meta[name="csrf"]').content);

  const res = await fetch('/api/profil', { method: 'POST', body: fd });
  console.log('Status:', res.status);
});

Status: 200

Blob mit Dateinamen hochladen (z. B. aus einem Canvas)

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

const blob = await new Promise((resolve) => canvas.toBlob(resolve, 'image/png'));

const fd = new FormData();
// Ohne dritten Parameter hieße die Datei "blob"
fd.set('avatar', blob, 'avatar.png');

console.log(fd.get('avatar') instanceof File, fd.get('avatar').name);

await fetch('/upload', { method: 'POST', body: fd });

true avatar.png

// Wichtig · Fallstricke

set() oder append(): Wenn Sie set() für Felder mit mehreren Werten verwenden (Mehrfachauswahl bei Checkboxen, <input type=\"file\" multiple>), gehen alle Werte bis auf den letzten verloren.
Kein Rückgabewert: fd.set('a', 1).set('b', 2) löst einen TypeError aus.
Typumwandlung: Objekte werden zu \"[object Object]\". Strukturierte Daten müssen Sie vorher mit JSON.stringify() umwandeln.
Dateiname nur bei Blob: Übergeben Sie filename zusammen mit einem Zeichenkettenwert, wirft der Aufruf einen TypeError.
Kein Content-Type-Header setzen: Wenn Sie FormData an fetch() übergeben, setzt der Browser den multipart/form-data-Header samt Boundary selbst. Legen Sie ihn von Hand fest, fehlt die Boundary und der Server kann den Body nicht auslesen.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workern. Der Internet Explorer kennt die Methode nicht. In Node.js ist FormData ab Version 18 global verfügbar.

Siehe auch

FormData FormData.append() FormData.get() FormData.getAll() FormData.delete() FormData.has() URLSearchParams.set()