FormDataEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface FormDataEvent extends Event

Beschreibung

FormDataEvent ist das Ereignisobjekt für das formdata-Ereignis. Der Browser löst es auf einem <form>-Element aus, sobald er die Eintragsliste des Formulars aufgebaut hat. Das passiert beim normalen Absenden des Formulars (nach dem submit-Ereignis) und bei jedem Aufruf von new FormData(form).

Die wichtigste Eigenschaft ist formData. Sie enthält das FormData-Objekt mit den Daten, die gleich gesendet bzw. zurückgegeben werden. Wenn du es im Handler änderst, landen die Änderungen direkt in der Übermittlung. Du kannst zum Beispiel mit append() berechnete Felder ergänzen, mit set() Werte normalisieren oder mit delete() Felder entfernen.

Typische Einsatzfälle:

Web Components / Custom Elements: Eigene Eingabefelder können ihre Werte ins umgebende Formular einschleusen. Das ist die Alternative, falls du ElementInternals nicht nutzt.
Versteckte Metadaten: Zeitstempel, Client-Informationen oder Tokens anhängen, ohne dafür <input type="hidden"> anzulegen.
Datenaufbereitung: Werte kurz vor dem Versand bereinigen, etwa Leerzeichen am Rand entfernen.

Das Ereignis steigt im DOM auf (bubbles: true) und lässt sich nicht abbrechen (cancelable: false). Das Absenden kannst du darüber also nicht verhindern. Dafür ist das submit-Ereignis zuständig.

Rückgabewert

Typ

FormDataEvent

Beschreibung

Der Konstruktor liefert eine neue FormDataEvent-Instanz. Über event.formData greifst du auf das zugehörige FormData-Objekt zu.

Beispiele

Zusätzliche Felder beim Absenden anhängen

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

form.addEventListener('formdata', (event) => {
  // Metadaten ergänzen, ohne versteckte Inputs
  event.formData.append('gesendetAm', new Date().toISOString());
  event.formData.append('sprache', navigator.language);
});

// Das Ereignis wird auch durch new FormData(form) ausgelöst
const daten = new FormData(form);
console.log(daten.has('gesendetAm'));

true

Werte vor dem Versand normalisieren (on-Property)

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

form.onformdata = ({ formData }) => {
  for (const [key, value] of [...formData.entries()]) {
    if (typeof value === 'string') {
      formData.set(key, value.trim());
    }
  }
  formData.delete('passwortWiederholung'); // nicht an den Server senden
};

Custom Element trägt seinen Wert ins Formular ein

class StarRating extends HTMLElement {
  value = 0;

  connectedCallback() {
    this.form = this.closest('form');
    this.handler = (e) => {
      e.formData.append(this.getAttribute('name') ?? 'rating', String(this.value));
    };
    this.form?.addEventListener('formdata', this.handler);
  }

  disconnectedCallback() {
    // Listener sauber entfernen
    this.form?.removeEventListener('formdata', this.handler);
  }
}
customElements.define('star-rating', StarRating);

FormDataEvent manuell erzeugen

const fd = new FormData();
fd.append('test', '42');

const event = new FormDataEvent('formdata', { formData: fd, bubbles: true });
console.log(event instanceof Event, event.formData.get('test'));

true "42"

// Wichtig · Fallstricke

Nicht abbrechbar: event.preventDefault() hat keine Wirkung. Um das Absenden zu verhindern, nutze das submit-Ereignis.
Auslösung durch new FormData(form): Der Handler läuft auch, wenn du die Formulardaten nur per Skript ausliest. Nebenwirkungen im Handler, zum Beispiel doppeltes append() oder Netzwerkaufrufe, sollten darauf ausgelegt sein.
Nur synchron: Änderungen an formData müssen synchron im Handler geschehen. Nach einem await ist die Übermittlung schon vorbereitet, spätere Änderungen gehen verloren.
Keine Rekursion: Wenn du im formdata-Handler new FormData(form) für dasselbe Formular aufrufst, wirft der Browser einen InvalidStateError.
Dateien: Blob- und File-Werte kommen nur korrekt an, wenn das Formular mit enctype="multipart/form-data" gesendet wird.
Kompatibilität: Unterstützt ab Chrome/Edge 77, Firefox 72 und Safari 15. Ältere Safari-Versionen kennen das Ereignis nicht. Für Custom Elements ist ElementInternals.setFormValue() heute oft die robustere Lösung.

Siehe auch

FormData HTMLFormElement SubmitEvent ElementInternals Event