HTMLFormElement.enctype — Eigenschaft · JavaScript-Referenz

Signatur

HTMLFormElement.enctype

Beschreibung

Die Eigenschaft enctype eines <form>-Elements legt fest, wie die Formulardaten beim Absenden kodiert werden. Sie spiegelt das HTML-Attribut enctype wider und ist lesbar und beschreibbar. Die Kodierung spielt nur bei method="post" eine Rolle, weil bei GET die Daten immer als Query-String an die URL angehängt werden.

Erlaubt sind drei Werte:

application/x-www-form-urlencoded: der Standardwert. Schlüssel-Wert-Paare werden URL-kodiert, zum Beispiel name=Max&alter=30.
multipart/form-data: Pflicht, sobald das Formular Dateien über <input type="file"> hochlädt.
text/plain: ungenormte Klartext-Kodierung. Sie ist nur für Debugging gedacht und lässt sich maschinell nicht zuverlässig auslesen.

Beim Lesen gibt die Eigenschaft immer einen gültigen Wert zurück. Fehlt das Attribut oder enthält es einen ungültigen Wert, erhält man "application/x-www-form-urlencoded". Ein Absende-Button kann den Wert mit dem Attribut formenctype für einen einzelnen Absendevorgang überschreiben.

Die Eigenschaft HTMLFormElement.encoding ist ein älterer Alias und verhält sich genauso.

Parameter

Name	Typ	Default	Beschreibung
$value	string	"application/x-www-form-urlencoded"	Nur beim Setzen: der neue MIME-Typ. Gültig sind `application/x-www-form-urlencoded`, `multipart/form-data` und `text/plain`. Groß- und Kleinschreibung spielt keine Rolle.

Rückgabewert

Typ

string

Beschreibung

Der aktuell gültige Kodierungstyp in Kleinbuchstaben. Ist das Attribut ungültig oder fehlt es, wird "application/x-www-form-urlencoded" zurückgegeben.

Beispiele

Kodierungstyp auslesen

// <form id="kontakt" method="post" action="/senden"></form>
const form = document.getElementById('kontakt');
console.log(form.enctype);

// Ungültiger Wert fällt auf den Standardwert zurück
form.setAttribute('enctype', 'application/json');
console.log(form.enctype);

application/x-www-form-urlencoded application/x-www-form-urlencoded

Für den Datei-Upload auf multipart umschalten

const form = document.querySelector('#profil');
const fileInput = form.querySelector('input[type="file"]');

fileInput.addEventListener('change', () => {
  // Sobald eine Datei gewählt ist, muss multipart verwendet werden
  if (fileInput.files.length > 0) {
    form.method = 'post';
    form.enctype = 'multipart/form-data';
  }
  console.log(form.enctype, form.getAttribute('enctype'));
});

multipart/form-data multipart/form-data

enctype beim Absenden per fetch berücksichtigen

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

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  // Liefert den Button-Override (formenctype) oder form.enctype
  const enctype = event.submitter?.formEnctype || form.enctype;
  const data = new FormData(form, event.submitter);

  // multipart: FormData direkt senden, Browser setzt Content-Type samt boundary
  const body = enctype === 'multipart/form-data'
    ? data
    : new URLSearchParams(data);

  const response = await fetch(form.action, { method: 'POST', body });
  console.log(enctype, response.status);
});

application/x-www-form-urlencoded 200

// Wichtig · Fallstricke

Datei-Uploads: Ohne multipart/form-data wird bei <input type="file"> nur der Dateiname übertragen, nicht der Inhalt der Datei. Dieser Fehler passiert oft.
Nur bei POST wirksam: Bei method="get" wird enctype ignoriert.
Kein JSON: application/json ist kein gültiger Wert und fällt stillschweigend auf den Standardwert zurück. JSON sendet man stattdessen mit fetch() und JSON.stringify().
Override durch Buttons: formenctype am Absende-Button hat Vorrang. form.enctype zeigt diesen Override nicht an. Den tatsächlich verwendeten Wert findet man über event.submitter heraus.
fetch mit FormData: Den Header Content-Type: multipart/form-data nicht selbst setzen. Sonst fehlt der boundary-Parameter, und der Server kann die Daten nicht auslesen.
text/plain: Diese Kodierung ist nicht eindeutig und kann bei Cross-Origin-Anfragen CSRF-Angriffe begünstigen, weil sie als „einfache Anfrage“ ohne CORS-Vorabprüfung (Preflight) verschickt wird. In Produktivsystemen nicht verwenden.
Die Eigenschaft wird von allen Browsern unterstützt, auch von sehr alten.

Siehe auch

HTMLFormElement HTMLFormElement.method HTMLFormElement.action HTMLFormElement.encoding HTMLButtonElement.formEnctype