JavaScript FormData

Der effiziente Umgang mit Formulardaten ist entscheidend für die Entwicklung dynamischer, interaktiver Webseiten. JavaScript stellt dafür die FormData API bereit: Sie ermöglicht es, die Felder eines Formulars einzulesen, Schlüssel/Wert-Paare programmatisch aufzubauen und zusammen mit Dateien an einen Server zu senden. Dieser Leitfaden erläutert, was FormData ist, wie man es erstellt und ausliest, welche Methoden es bereitstellt, wie man es mit fetch versendet und welche typischen Fehlerquellen es gibt.

FormData verstehen

FormData ist ein eingebautes JavaScript-Objekt, das einen Satz von Schlüssel/Wert-Paaren repräsentiert — modelliert nach der Art, wie ein Browser ein HTML-Formular überträgt. Es vereinfacht das Erfassen von Daten aus HTML-Formularen und das asynchrone Senden dieser Daten an einen Server mithilfe der Fetch API.

Warum sollte man es statt eines einfachen object verwenden?

• Es liest vorhandene Formularfelder automatisch ein — kein manuelles Auslesen des value je Eingabefeld.
• Es unterstützt Dateien und Blobs, was mit einfachen objects und JSON nicht möglich ist.
• Wird es an fetch übergeben, setzt der Browser automatisch den korrekten Content-Type (multipart/form-data) mit dem richtigen Boundary.

FormData-Objekte erstellen

Ein FormData-Objekt wird mit dem FormData()-Konstruktor erstellt. Übergibt man ein <form>-Element, werden alle benannten, aktivierten Felder dieses Formulars sofort erfasst. Den Inhalt kann man durchlaufen, indem man die Methode entries() verwendet, die einen Iterator von [key, value]-Paaren zurückgibt:

<script>
  function onSubmit(event) {
    event.preventDefault();
    const form = document.getElementById('myForm');
    const formData = new FormData(form);
    let results = '';
    for (const [key, value] of formData.entries()) {
      results += `${key}: ${value}\n`;
    }
    alert(results)
  }
</script>
<form id="myForm" onsubmit="onSubmit(event)">
  <input type="text" name="username" value="John Doe" />
  <input type="email" name="email" value="[email protected]" />
  <input type="submit" />
</form>

Auf Formulardaten zugreifen

Ein einzelnes Feld liest man mit get() aus, oder man iteriert mit entries() über alle Felder (wie oben gezeigt). get() gibt den ersten Wert für einen Schlüssel zurück (oder null, falls der Schlüssel nicht existiert):

<form id="myForm" onsubmit="onSubmit(event)">
  <input type="text" name="username" value="John Doe" />
  <input type="email" name="email" value="[email protected]" />
  <input type="submit" />
</form>
<script>
  function onSubmit(event) {
    const form = document.getElementById('myForm');
    const formData = new FormData(form);
    const username = formData.get('username');
    const email = formData.get('email');
    alert(`username: ${username}; email: ${email}`);
  }
</script>

FormData-Methoden

Über das bloße Einlesen eines bestehenden Formulars hinaus ermöglicht FormData, den Datensatz manuell aufzubauen und zu bearbeiten. Jede Instanz stellt folgende Methoden bereit:

Der Unterschied zwischen append und set ist die häufigste Fehlerquelle:

const fd = new FormData();
fd.append('tag', 'js');
fd.append('tag', 'web');   // append keeps both
console.log(fd.getAll('tag'));   // [ 'js', 'web' ]

fd.set('tag', 'html');     // set replaces all
console.log(fd.getAll('tag'));   // [ 'html' ]

console.log(fd.has('tag'));      // true
fd.delete('tag');
console.log(fd.has('tag'));      // false

Man kann ein FormData-Objekt auch vollständig im Code erstellen — ohne jedes Formular — indem man Felder direkt hinzufügt. Ein drittes Argument bei append/set legt den Dateinamen fest, wenn der Wert ein Blob oder File ist.

FormData mit der Fetch API senden

Ein häufiger Anwendungsfall für FormData ist das asynchrone Senden von Formulardaten an den Server. Man übergibt die FormData-Instanz als body einer fetch-Anfrage — der Browser setzt den Content-Type automatisch auf multipart/form-data mit dem korrekten Boundary, daher sollte man diesen Header nicht selbst setzen:

<form id="myForm" onsubmit="onSubmit(event)">
  <input type="text" name="title" value="A title" />
  <input type="text" name="body" value="A body" />
  <input type="submit" value="Submit Post" />
</form>
<div>post id: <span id="response"></span></div>
<script>
  function onSubmit(event) {
    event.preventDefault();
    const form = document.getElementById('myForm');
    const formData = new FormData(form);
    const responseSpan = document.getElementById('response');
    fetch('https://jsonplaceholder.typicode.com/posts', {
        method: 'POST',
        body: formData
    })
      .then(response => response.json())
      .then(data => { responseSpan.innerHTML = data.id; })
      .catch(error => console.error('Error:', error));
  }
</script>

Datei-Uploads verarbeiten

FormData ist der standardmäßige Weg zum Hochladen von Dateien, da es eine multipart/form-data-Anfrage erzeugt, die binäre Inhalte neben Textfeldern transportieren kann. Wenn man das FormData-Objekt aus einem Formular erstellt, das ein <input type="file">-Element enthält, ist die ausgewählte Datei bereits enthalten — es ist nicht nötig, input.files auszulesen und die Datei erneut hinzuzufügen:

<form id="fileUploadForm">
    <input type="file" name="file" />
    <input type="submit" value="Upload" />
</form>
<script>
    const form = document.getElementById('fileUploadForm');
    form.addEventListener('submit', (event) => {
        event.preventDefault();
        // The file input is captured automatically from the form.
        const formData = new FormData(form);
        fetch('https://httpbin.org/post', {
            method: 'POST',
            body: formData
        })
        .then(response => response.json())
        .then(data => console.log('Upload successful:', data))
        .catch(error => console.error('Error:', error));
    });
</script>

Um eine Datei anzuhängen, die nicht Teil eines Formulars ist — zum Beispiel eine programmatisch ausgewählte —, fügt man sie explizit hinzu und kann dabei optional einen Dateinamen angeben:

const formData = new FormData();
formData.append('avatar', fileObject, 'profile.png');

FormData vs. URLSearchParams

Beide verwalten Schlüssel/Wert-Paare, serialisieren diese jedoch unterschiedlich. FormData verwendet man, wenn Dateien oder multipart/form-data benötigt werden. URLSearchParams eignet sich, wenn man nur Text hat und einen kompakten application/x-www-form-urlencoded-Body (oder einen Query-String) benötigt. Man kann sogar eines aus dem anderen konstruieren, solange alle Werte strings sind:

const fd = new FormData();
fd.append('q', 'cats');
fd.append('page', '2');

const params = new URLSearchParams(fd);
console.log(params.toString());   // q=cats&page=2

Fazit

FormData ist ein vielseitiges und leistungsstarkes Werkzeug für die Verwaltung von Formulardaten in JavaScript-Anwendungen. Ob es sich um einfache Texteingaben oder komplexe Datei-Uploads handelt — FormData vereinfacht den Prozess und bietet eine komfortable Schnittstelle für die Arbeit mit Formulardaten. Wer FormData beherrscht, kann die Interaktivität und Reaktionsfähigkeit seiner Webanwendungen steigern und Nutzern ein nahtloses Erlebnis bieten.

Übungen