FormData.get() — Methode · JavaScript-Referenz

Signatur

FormData.prototype.get(name)

Beschreibung

Die Methode get() liest einen einzelnen Wert aus einem FormData-Objekt. Das ist praktisch, wenn Formulardaten vor dem Absenden per fetch() geprüft, umgewandelt oder protokolliert werden sollen, etwa im submit-Handler eines Formulars.

Gibt es mehrere Einträge mit demselben Namen (zum Beispiel bei Checkbox-Gruppen, <select multiple> oder mehrfachem append()), liefert get() immer nur den ersten Wert. Alle Werte bekommt man mit getAll().

Der Rückgabewert ist entweder ein string oder, bei Datei-Feldern (<input type="file">) bzw. angehängten Blobs, ein File-Objekt. Zahlen oder Wahrheitswerte gibt es nicht: Alle Nicht-Blob-Werte werden beim Einfügen in Zeichenketten umgewandelt. Ist der Schlüssel nicht vorhanden, liefert die Methode null.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des gesuchten Eintrags, also normalerweise das `name`-Attribut des Formularfelds. Groß- und Kleinschreibung werden unterschieden.

Rückgabewert

Typ

string | File | null

Beschreibung

Den ersten Wert zum Schlüssel name: einen string oder ein File. Existiert kein Eintrag mit diesem Namen, wird null zurückgegeben.

Beispiele

Werte im submit-Handler auslesen

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

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

  const email = data.get('email');
  const remember = data.get('remember'); // Checkbox: 'on' oder null

  if (!email) {
    alert('Bitte E-Mail angeben');
    return;
  }

  console.log(email, remember !== null);
  await fetch('/api/login', { method: 'POST', body: data });
});

max@example.com true

Erster Wert bei mehrfachen Schlüsseln und fehlender Schlüssel

const fd = new FormData();
fd.append('tag', 'js');
fd.append('tag', 'css');
fd.append('alter', 42);

console.log(fd.get('tag'));         // nur der erste Wert
console.log(fd.getAll('tag'));      // alle Werte
console.log(typeof fd.get('alter')); // Zahl wurde zu String
console.log(fd.get('fehlt'));

js ["js", "css"] string null

Hochgeladene Datei prüfen

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

form.addEventListener('submit', (event) => {
  const file = new FormData(form).get('avatar');

  // Bei leerem Datei-Feld: File mit size 0 und leerem Namen
  if (!(file instanceof File) || file.size === 0) {
    event.preventDefault();
    console.log('Keine Datei gewählt');
    return;
  }

  if (file.size > 2 * 1024 * 1024) {
    event.preventDefault();
    console.log(`${file.name} ist zu groß`);
  }
});

Keine Datei gewählt

Zahlenwert sicher umwandeln

const fd = new FormData();
fd.set('menge', '3');

const menge = Number(fd.get('menge') ?? 0);
console.log(menge * 2);

6

// Wichtig · Fallstricke

Nur der erste Wert: Bei Checkbox-Gruppen oder <select multiple> fehlen mit get() die weiteren Werte. Verwende dafür getAll().
null vs. leerer String: Ein leeres Textfeld liefert "", ein fehlender Schlüssel dagegen null. Nicht angehakte Checkboxen und deaktivierte Felder (disabled) werden gar nicht übertragen und liefern daher null.
Immer Strings: Zahlen und Wahrheitswerte werden beim Einfügen zu Zeichenketten. "false" ist truthy, deshalb vor Vergleichen ausdrücklich umwandeln.
Leeres Datei-Feld: Ein <input type="file"> ohne Auswahl liefert ein File mit size === 0, nicht null.
Momentaufnahme: new FormData(form) übernimmt die Werte zum Zeitpunkt der Erstellung. Spätere Eingaben im Formular sind darin nicht enthalten.
Sicherheit: Werte kommen direkt vom Nutzer. Gib sie nicht ungeprüft per innerHTML aus (XSS-Gefahr) und prüfe sie auch serverseitig.
Kompatibilität: In allen modernen Browsern verfügbar, außerdem in Web Workern und in Node.js ab Version 18 (global). Der Internet Explorer unterstützt nur append(), nicht get().

Siehe auch

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