HTMLButtonElement.formEnctype — Eigenschaft · JavaScript-Referenz

Signatur

HTMLButtonElement.formEnctype

Beschreibung

Die Eigenschaft formEnctype spiegelt das HTML-Attribut formenctype eines <button>-Elements wider. Sie legt fest, wie die Formulardaten kodiert werden, wenn das Formular über genau diesen Absende-Button abgeschickt wird, und überschreibt dabei das enctype-Attribut des zugehörigen <form>-Elements.

Gültige Werte sind:

application/x-www-form-urlencoded – Standardwert, Schlüssel-Wert-Paare URL-kodiert.
multipart/form-data – notwendig für Datei-Uploads über <input type="file">.
text/plain – unkodierter Klartext, hauptsächlich zum Debuggen.

Typischer Einsatz: Ein Formular besitzt mehrere Absende-Buttons, z. B. „Nur Text speichern“ und „Mit Anhang hochladen“. Der zweite Button kann per formEnctype auf multipart/form-data umschalten, ohne das Formular selbst zu ändern. Die Eigenschaft wirkt nur bei Buttons mit type="submit" (Standard) und nur bei method="post".

Beim Lesen liefert der Getter einen normalisierten Wert: Ist das Attribut ungültig, erhält man application/x-www-form-urlencoded; fehlt es ganz, ist das Ergebnis je nach Browser ein leerer String bzw. der Standardwert.

Parameter

Name	Typ	Default	Beschreibung
$value	string	"application/x-www-form-urlencoded"	Beim Setzen: einer der Werte `application/x-www-form-urlencoded`, `multipart/form-data` oder `text/plain`. Wird als Attribut `formenctype` geschrieben.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Kodierungstyp als String. Ungültige Attributwerte werden zu application/x-www-form-urlencoded normalisiert.

Beispiele

Wert auslesen

// HTML: <form method="post" action="/upload"><button id="upload" formenctype="multipart/form-data">Hochladen</button></form>
const btn = document.querySelector('#upload');
console.log(btn.formEnctype);

multipart/form-data

Kodierung abhängig von Dateiauswahl umschalten

const form = document.querySelector('#nachricht');
const fileInput = form.querySelector('input[type="file"]');
const sendBtn = form.querySelector('button[type="submit"]');

fileInput.addEventListener('change', () => {
  // Nur bei ausgewählter Datei multipart verwenden
  sendBtn.formEnctype = fileInput.files.length > 0
    ? 'multipart/form-data'
    : 'application/x-www-form-urlencoded';
  console.log('Kodierung:', sendBtn.formEnctype);
});

Kodierung: multipart/form-data

Ungültige Werte werden normalisiert

const btn = document.createElement('button');
btn.formEnctype = 'application/json';
console.log(btn.getAttribute('formenctype'));
console.log(btn.formEnctype);

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

Im submit-Event den verwendeten Button prüfen

document.querySelector('form').addEventListener('submit', (event) => {
  const submitter = event.submitter;
  const enctype = submitter?.formEnctype || event.target.enctype;
  console.log('Gesendet mit:', enctype);
});

Gesendet mit: multipart/form-data

// Wichtig · Fallstricke

Nur bei POST wirksam: Bei method="get" werden die Daten immer als URL-Query angehängt; formEnctype wird ignoriert.
Kein JSON: application/json ist kein gültiger Wert. Für JSON-Übertragung fetch() mit JSON.stringify() verwenden.
Nur für Submit-Buttons: Bei type="button" oder type="reset" hat die Eigenschaft keine Wirkung.
Datei-Uploads: Ohne multipart/form-data wird bei Dateifeldern nur der Dateiname gesendet, nicht der Inhalt.
Wenn du Formulare per fetch(url, { body: new FormData(form) }) sendest, wird formEnctype nicht beachtet; FormData wird immer als multipart/form-data übertragen.
Kompatibilität: In allen modernen Browsern unterstützt; event.submitter gibt es erst seit Safari 15.4.

Siehe auch

HTMLButtonElement.formAction HTMLButtonElement.formMethod HTMLButtonElement.form HTMLButtonElement.formTarget HTMLButtonElement.type