HTMLFormElement.name — Eigenschaft · JavaScript-Referenz

Signatur

HTMLFormElement.name

Beschreibung

Die Eigenschaft HTMLFormElement.name spiegelt das Inhaltsattribut name eines <form>-Elements wider. Beim Lesen erhältst du den aktuellen Attributwert. Fehlt das Attribut, ist der Wert eine leere Zeichenkette "". Beim Schreiben wird das Attribut name im DOM direkt gesetzt oder überschrieben.

Über den Formularnamen kannst du ein Formular gezielt ansprechen, etwa mit document.forms["login"] oder document.forms.login. Das ist praktisch, wenn eine Seite mehrere Formulare hat und du keine id vergeben willst oder kannst. Laut HTML-Spezifikation darf der Name nicht leer sein und muss unter allen Formularen im Dokument eindeutig sein.

Anders als bei Eingabefeldern wird der Formularname nicht mit den Formulardaten übertragen. Er dient nur zur Identifikation im DOM und im Skript. Mit dem Attribut name der einzelnen Steuerelemente (<input>, <select> usw.) hat er nichts zu tun.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Schreiben: der neue Formularname. Andere Werte werden in eine Zeichenkette umgewandelt, zum Beispiel wird `null` zu `"null"`.

Rückgabewert

Typ

string

Beschreibung

Der Wert des Attributs name oder "", wenn das Attribut fehlt. Achtung: Enthält das Formular ein Steuerelement mit name="name", bekommst du stattdessen dieses Element zurück (siehe Hinweise).

Beispiele

Formularnamen auslesen

// HTML: <form name="kontakt" id="f1">...</form>
const form = document.getElementById('f1');
console.log(form.name);

// Formular ohne name-Attribut
const leer = document.createElement('form');
console.log(JSON.stringify(leer.name));

kontakt ""

Formular über den Namen in document.forms finden

// HTML: <form name="login"><input name="user"></form>
const loginForm = document.forms.login; // oder document.forms['login']

loginForm.addEventListener('submit', (event) => {
  event.preventDefault();
  console.log(`Formular "${loginForm.name}" abgeschickt, Benutzer: ${loginForm.elements.user.value}`);
});

Formular "login" abgeschickt, Benutzer: max

Namen dynamisch setzen

const form = document.createElement('form');
form.name = 'newsletter';
document.body.append(form);

console.log(form.getAttribute('name'));
console.log(document.forms.newsletter === form);

newsletter true

Sicherer Zugriff bei überschattetem Namen

// HTML: <form name="bestellung"><input name="name" value="Anna"></form>
const form = document.forms.bestellung;

console.log(form.name);                  // liefert das <input>-Element!
console.log(form.getAttribute('name'));  // zuverlässig

// Zugriff über den ursprünglichen Getter des Prototyps
const getter = Object.getOwnPropertyDescriptor(HTMLFormElement.prototype, 'name').get;
console.log(getter.call(form));

<input name="name" value="Anna"> bestellung bestellung

// Wichtig · Fallstricke

Überschattung durch Steuerelemente: HTMLFormElement stellt seine Steuerelemente als benannte Eigenschaften bereit, und diese haben Vorrang vor den eingebauten Eigenschaften. Heißt ein Feld im Formular name, liefert form.name dieses Element und nicht die Zeichenkette. Dasselbe passiert mit id, action, submit usw. Lies den Wert in solchen Fällen mit form.getAttribute('name') aus und verwende keine Feldnamen, die mit Formular-Eigenschaften kollidieren.
Benannte Formulare werden zusätzlich als Eigenschaft von document bereitgestellt (document.login). Dieser alte Zugriff ist fehleranfällig und kann globale Namen überschatten. Nutze besser document.forms oder querySelector('form[name="login"]').
Der Name sollte eindeutig und nicht leer sein. Gibt es mehrere Formulare mit demselben Namen, liefert document.forms.name eine HTMLCollection statt eines einzelnen Elements.
Der Formularname wird beim Absenden nicht mit übertragen.
Kompatibilität: Die Eigenschaft wird seit jeher von allen Browsern unterstützt.

Siehe auch

HTMLFormElement Document.forms HTMLFormElement.elements HTMLFormElement.action Element.getAttribute() HTMLInputElement.name HTMLFontElement.face