HTMLButtonElement.name — Eigenschaft · JavaScript-Referenz

Signatur

HTMLButtonElement.name

Beschreibung

Die Eigenschaft name von HTMLButtonElement spiegelt das HTML-Attribut name des <button>-Elements wider. Sie ist lesbar und schreibbar: Beim Lesen erhält man den aktuellen Attributwert oder "", falls kein Attribut vorhanden ist; beim Schreiben wird das Attribut name gesetzt bzw. überschrieben.

Der Name ist vor allem beim Absenden von Formularen wichtig: Wird ein Formular über einen Submit-Button abgeschickt, landet das Paar name=value dieses Buttons in den Formulardaten. So kann der Server (oder ein submit-Handler über event.submitter) erkennen, welcher von mehreren Buttons geklickt wurde – etwa „Speichern“ vs. „Löschen“.

Außerdem macht ein Name den Button über form.elements[name] bzw. form.elements.namedItem(name) ansprechbar. Buttons ohne Namen oder mit type="button"/type="reset" tragen nichts zu den übermittelten Formulardaten bei.

Rückgabewert

Typ

string

Beschreibung

Der Wert des name-Attributs oder "", wenn keines gesetzt ist. Beim Zuweisen wird der Wert in einen String umgewandelt und als Attribut gesetzt.

Beispiele

Namen lesen und setzen

// <button id="saveBtn" name="action" value="save">Speichern</button>
const btn = document.getElementById('saveBtn');
console.log(btn.name);

btn.name = 'command';
console.log(btn.getAttribute('name'));

const plain = document.createElement('button');
console.log(JSON.stringify(plain.name));

action command ""

Geklickten Submit-Button im submit-Handler erkennen

// <form id="postForm">
//   <button name="action" value="save">Speichern</button>
//   <button name="action" value="delete">Löschen</button>
// </form>
const form = document.getElementById('postForm');

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const { submitter } = event;
  // FormData mit submitter übernimmt name/value des Buttons
  const data = new FormData(form, submitter);
  console.log(submitter.name, '=', data.get(submitter.name));
});

action = delete (nach Klick auf „Löschen“)

Button über form.elements per Name ansprechen

// <form id="f"><button name="sendBtn" type="submit">Senden</button></form>
const form = document.getElementById('f');
const sendBtn = form.elements.namedItem('sendBtn');

sendBtn.disabled = true; // z. B. während eines laufenden Requests
console.log(sendBtn instanceof HTMLButtonElement, sendBtn.name);

true sendBtn

// Wichtig · Fallstricke

Nur der auslösende Button wird übermittelt: Bei mehreren Submit-Buttons gleichen Namens landet nur der tatsächlich geklickte in den Formulardaten. Bei form.submit() wird gar kein Button mitgeschickt; form.requestSubmit(button) dagegen berücksichtigt den übergebenen Button.
new FormData(form) ohne zweites Argument enthält den Submit-Button nicht. Der Parameter submitter ist relativ neu (Chrome 112, Firefox 111, Safari 16.4).
Buttons mit type="button" oder type="reset" sowie deaktivierte Buttons (disabled) werden nie übermittelt, auch wenn sie einen Namen haben.
Vermeide Namen wie submit, action oder reset nicht zwingend, aber beachte: Ein Button mit name="submit" überschattet über die benannte Zugriffsmöglichkeit form.submit die gleichnamige Methode – form.submit() wirft dann einen TypeError.
Der Wert wird nicht bereinigt; beim Einsetzen in HTML (z. B. über innerHTML) muss er wie jeder andere Benutzer- oder Fremdwert escaped werden.
Die Eigenschaft wird von allen Browsern seit Langem unterstützt.

Siehe auch

HTMLButtonElement.type HTMLButtonElement.value HTMLButtonElement.form HTMLButtonElement.labels HTMLButtonElement.command