new FormDataEvent() — Methode · JavaScript-Referenz

Signatur

new FormDataEvent(type, options)

Beschreibung

Der Konstruktor FormDataEvent() erzeugt ein Ereignisobjekt vom Typ FormDataEvent. Der Browser löst ein solches Ereignis mit dem Typ "formdata" selbst aus, wenn er die Eintragsliste eines Formulars aufbaut: beim Absenden des Formulars oder beim Aufruf von new FormData(form). In der Eigenschaft formData steckt dann das FormData-Objekt, das Sie noch vor dem Versand ändern können.

Den Konstruktor brauchen Sie nur selten direkt. Nützlich ist er vor allem in Unit-Tests, wenn Sie einen formdata-Handler ohne echtes Absenden prüfen wollen, sowie bei eigenen Komponenten (z. B. Web Components), die das Verhalten nativer Formulare nachbilden und ihren Zuhörern ein FormData-Objekt übergeben möchten.

Wichtig: Die Eigenschaft formData im Optionsobjekt ist Pflicht. Fehlt sie, wirft der Konstruktor einen TypeError. Ein selbst erzeugtes Ereignis hat außerdem isTrusted === false und löst weder ein Absenden noch sonst ein Standardverhalten des Formulars aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Beim Standardverhalten ist das `"formdata"`. Groß- und Kleinschreibung zählt.
$options Pflicht	object		Optionsobjekt. Es erbt alle Felder von `EventInit` und ergänzt ein Pflichtfeld: `formData` (`FormData`, Pflicht): das Datenobjekt, das Zuhörer über `event.formData` erreichen. `bubbles` (`boolean`, Standard `false`): Ob das Ereignis im DOM nach oben weitergereicht wird. `cancelable` (`boolean`, Standard `false`): Ob `preventDefault()` Wirkung hat. `composed` (`boolean`, Standard `false`): Ob das Ereignis die Shadow-DOM-Grenze überschreitet.

Rückgabewert

Typ

FormDataEvent

Beschreibung

Ein neues FormDataEvent-Objekt. Über seine Eigenschaft formData ist das übergebene FormData-Objekt erreichbar.

Beispiele

Ereignis erzeugen und Daten auslesen

const data = new FormData();
data.append('benutzer', 'anna');

const event = new FormDataEvent('formdata', { formData: data });

console.log(event.type);                       // Ereignistyp
console.log(event.formData.get('benutzer'));   // Wert aus FormData
console.log(event.isTrusted);                  // synthetisch erzeugt

formdata anna false

Handler für das native formdata-Ereignis (Praxis)

const form = document.createElement('form');
form.innerHTML = '<input name="email" value="a@example.com">';
document.body.append(form);

// Zusätzliches Feld vor dem Versand ergänzen
form.addEventListener('formdata', (event) => {
  event.formData.append('zeitstempel', '2024-01-01');
});

// new FormData(form) löst das formdata-Ereignis synchron aus
const result = new FormData(form);
console.log([...result.entries()]);

[["email", "a@example.com"], ["zeitstempel", "2024-01-01"]]

formdata-Handler im Unit-Test ohne echtes Formular-Absenden prüfen

const addCsrfToken = (event) => {
  event.formData.set('csrf', 'token-123');
};

const target = new EventTarget();
target.addEventListener('formdata', addCsrfToken);

const testData = new FormData();
target.dispatchEvent(new FormDataEvent('formdata', { formData: testData }));

console.assert(testData.get('csrf') === 'token-123', 'Token fehlt!');
console.log('Test bestanden:', testData.get('csrf'));

Test bestanden: token-123

Fehlende formData-Option führt zu TypeError

try {
  new FormDataEvent('formdata');
} catch (err) {
  console.log(err instanceof TypeError);
}

true

// Wichtig · Fallstricke

Pflichtoption: Ohne options.formData (oder wenn der Wert kein FormData-Objekt ist) wirft der Konstruktor einen TypeError.
Kein Standardverhalten: Wenn Sie ein selbst erzeugtes FormDataEvent mit dispatchEvent() auf einem <form> auslösen, wird das Formular dadurch nicht abgesendet. Zuhörer bekommen nur das übergebene Objekt, nicht die echten Formularfelder.
Nicht abbrechbar: Das native formdata-Ereignis ist nicht cancelable. Mit preventDefault() lässt sich ein Absenden nicht verhindern, dafür ist das submit-Ereignis zuständig.
Synchron: Handler laufen synchron, während die Eintragsliste aufgebaut wird. Asynchrone Änderungen (etwa nach await) kommen zu spät.
Kompatibilität: Die API ist in allen modernen Browsern verfügbar (Chrome/Edge 77+, Firefox 72+, Safari 15+). Im Internet Explorer gibt es sie nicht. In Node.js existiert FormDataEvent nicht global; in Testumgebungen wie jsdom kann die Unterstützung fehlen.

Siehe auch

FormDataEvent FormDataEvent.formData FormData Event EventTarget.prototype.dispatchEvent()