HTMLFormElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLFormElement extends HTMLElement

Beschreibung

HTMLFormElement ist die DOM-Schnittstelle für jedes <form>-Element. Sie erbt von HTMLElement und ergänzt Eigenschaften, die die HTML-Attribute des Formulars widerspiegeln, zum Beispiel action, method, enctype, target, noValidate, name und autocomplete.

Besonders nützlich ist die Eigenschaft elements. Sie liefert eine HTMLFormControlsCollection mit allen zugehörigen Steuerelementen (input, select, textarea, button, fieldset, output, object). Dazu gehören auch Elemente außerhalb des Formulars, die über das Attribut form="id" verknüpft sind. Auf einzelne Felder greift man über ihren Namen oder ihre ID zu, etwa mit form.elements.email. length gibt die Anzahl der Steuerelemente an.

Die wichtigsten Methoden:

submit() sendet das Formular ab, ohne Validierung und ohne submit-Event.
requestSubmit(submitter?) sendet das Formular so ab, als hätte der Nutzer auf einen Absende-Button geklickt, mit Validierung und submit-Event.
reset() setzt alle Felder auf ihre Standardwerte zurück und löst das reset-Event aus.
checkValidity() und reportValidity() prüfen die Einschränkungen der Constraint Validation API. reportValidity() zeigt dem Nutzer zusätzlich die Fehlermeldungen an.

In modernen Anwendungen fängt man meist das submit-Event ab, ruft event.preventDefault() auf, liest die Daten mit new FormData(form) aus und sendet sie per fetch(). Weitere relevante Events sind formdata, reset und invalid. Das invalid-Event wird an den einzelnen Feldern ausgelöst.

Rückgabewert

Typ

HTMLFormElement

Beschreibung

Wird zum Beispiel von document.forms[0], document.querySelector('form') oder document.createElement('form') zurückgegeben.

Beispiele

Formular abrufen und Felder über elements auslesen

// HTML: <form id="login"><input name="user" value="anna"><input name="pw" type="password"></form>
const form = document.forms.login; // oder document.getElementById('login')

console.log(form instanceof HTMLFormElement);
console.log(form.length);
console.log(form.elements.user.value);
console.log(form.method, form.action);

true 2 anna get https://example.com/aktuelle-seite

Absenden per fetch mit FormData abfangen

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

form.addEventListener('submit', async (event) => {
  event.preventDefault(); // Seitenwechsel verhindern

  const data = new FormData(form, event.submitter);
  const response = await fetch(form.action, {
    method: form.method.toUpperCase(),
    body: data,
  });

  if (response.ok) {
    form.reset(); // Felder zurücksetzen
    console.log('Nachricht gesendet');
  }
});

Nachricht gesendet

Validierung prüfen und requestSubmit() nutzen

const form = document.querySelector('#bestellung');
const saveButton = form.querySelector('button[name="aktion"][value="speichern"]');

// z. B. per Tastenkürzel Strg+S absenden
document.addEventListener('keydown', (e) => {
  if (e.ctrlKey && e.key === 's') {
    e.preventDefault();
    if (form.reportValidity()) {
      // löst submit-Event aus, submitter = saveButton
      form.requestSubmit(saveButton);
    }
  }
});

Formular dynamisch erzeugen und absenden

const form = document.createElement('form');
form.method = 'post';
form.action = '/abmelden';

const token = document.createElement('input');
token.type = 'hidden';
token.name = 'csrf';
token.value = 'abc123';
form.append(token);

document.body.append(form); // muss im Dokument hängen
console.log(form.elements.csrf.value);
form.submit(); // ohne Validierung und ohne submit-Event

abc123

// Wichtig · Fallstricke

submit() und requestSubmit(): submit() überspringt die Validierung, das submit-Event und damit auch eigene Handler. Wenn sich das Absenden wie ein Klick des Nutzers verhalten soll, nimm requestSubmit(). Das ist Baseline seit 2021 (Safari ab Version 16).
Namenskollisionen (DOM Clobbering): Heißt ein Feld name="submit", name="action" oder name="reset", überdeckt es die gleichnamige Eigenschaft oder Methode des Formulars. Dann schlägt zum Beispiel form.submit() mit einem TypeError fehl. Solche Namen solltest du vermeiden. Aus Sicherheitsgründen gilt außerdem: Benannte Felder können eingeschleustes HTML nutzen, um Eigenschaften zu überschreiben. Verlass dich deshalb nicht blind auf form.action, wenn fremdes Markup im Spiel ist.
form.action liefert immer eine absolute URL. Fehlt das Attribut, ist es die URL des Dokuments. form.method liefert den Wert in Kleinbuchstaben ("get", "post", "dialog").
elements enthält keine <input type="image">-Elemente.
Formulare lassen sich nicht verschachteln. Ein innerer <form>-Tag wird vom Parser ignoriert.
Mit submit() muss das Formular im Dokument eingehängt sein, sonst wird es nicht abgesendet.
Der zweite Parameter submitter von new FormData(form, submitter) ist neuer (Baseline 2023).

Siehe auch

HTMLFormControlsCollection HTMLInputElement HTMLFormElement.prototype.requestSubmit() SubmitEvent Document.forms