HTMLFormElement

Instanz-Eigenschaften

Dieses Interface erbt auch Eigenschaften von seinem übergeordneten Element, HTMLElement.

HTMLFormElement.acceptCharset

Ein String, der den Wert des HTML-Attributs accept-charset des Formulars widerspiegelt.

HTMLFormElement.action

Ein String, der den Wert des HTML-Attributs action des Formulars widerspiegelt und die URI eines Programms enthält, das die vom Formular übermittelten Informationen verarbeitet.

HTMLFormElement.autocomplete

Ein String, der den Wert des HTML-Attributs autocomplete des Formulars widerspiegelt, welches angibt, ob die Steuerungen in diesem Formular automatisch vom Browser ausgefüllt werden können.

HTMLFormElement.encoding oder HTMLFormElement.enctype

Ein String, der den Wert des HTML-Attributs enctype des Formulars widerspiegelt, der den Typ des Inhalts angibt, der verwendet wird, um das Formular zum Server zu übertragen. Nur angegebene Werte können gesetzt werden. Die beiden Eigenschaften sind synonym.

HTMLFormElement.elements Schreibgeschützt

Eine HTMLFormControlsCollection, die alle Formularsteuerungen enthält, die zu diesem Formularelement gehören.

HTMLFormElement.length Schreibgeschützt

Ein long, der die Anzahl der Steuerungen im Formular widerspiegelt.

HTMLFormElement.name

Ein String, der den Wert des HTML-Attributs name des Formulars widerspiegelt und den Namen des Formulars enthält.

HTMLFormElement.noValidate

Ein boolescher Wert, der den Wert des HTML-Attributs novalidate des Formulars widerspiegelt und angibt, ob das Formular nicht validiert werden soll.

HTMLFormElement.method

Ein String, der den Wert des HTML-Attributs method des Formulars widerspiegelt, der die HTTP-Methode angibt, die für das Einreichen des Formulars verwendet wird. Nur angegebene Werte können gesetzt werden.

HTMLFormElement.rel

Ein String, der den Wert des HTML-Attributs rel des Formulars widerspiegelt, welcher die Art der vom Formular erstellten Links als durch Leerzeichen getrennte Liste von aufgezählten Werten darstellt.

HTMLFormElement.relList Schreibgeschützt

Eine DOMTokenList, die das HTML-Attribut rel als Liste von Tokens widerspiegelt.

HTMLFormElement.target

Ein String, der den Wert des HTML-Attributs target des Formulars widerspiegelt und angibt, wo die Ergebnisse der Formularübermittlung angezeigt werden sollen.

Benannte Eingaben werden ihrer Besitzerform als Eigenschaften hinzugefügt und können native Eigenschaften überschreiben, wenn sie denselben Namen teilen (z.B. ein Formular mit einer Eingabe namens action wird seine action Eigenschaft anstelle des HTML-Attributs action des Formulars zurückgeben).

Instanz-Methoden

Dieses Interface erbt auch Methoden von seinem übergeordneten Element, HTMLElement.

checkValidity()

Gibt true zurück, wenn die untergeordneten Steuerungen des Elements der Constraint-Validierung unterliegen und diese Einschränkungen erfüllen; gibt false zurück, wenn einige Steuerungen ihre Einschränkungen nicht erfüllen. Löst ein Ereignis namens invalid bei jeder Steuerung aus, die ihre Einschränkungen nicht erfüllt; solche Steuerungen gelten als ungültig, wenn das Ereignis nicht abgebrochen wird. Es liegt am Programmierer, zu entscheiden, wie auf false reagiert wird.

reportValidity()

Gibt true zurück, wenn die untergeordneten Steuerungen des Elements ihre Validierungseinschränkungen erfüllen. Wenn false zurückgegeben wird, werden stornierbare invalid Ereignisse für jedes ungültige Kind ausgelöst und Validierungsprobleme dem Benutzer gemeldet.

requestSubmit()

Fordert an, dass das Formular unter Verwendung des angegebenen Absende-Buttons und seiner entsprechenden Konfiguration gesendet wird.

reset()

Setzt das Formular in seinen Anfangszustand zurück.

submit()

Sendet das Formular zum Server.

Ereignisse

Sie können diese Ereignisse mit addEventListener() überwachen oder einen Ereignis-Listener der Eigenschaft oneventname dieses Interfaces zuweisen.

formdata

Das formdata Ereignis wird ausgelöst, nachdem die Eintragsliste, die die Formulardaten darstellt, erstellt wurde.

reset

Das reset Ereignis wird ausgelöst, wenn ein Formular zurückgesetzt wird.

submit

Das submit Ereignis wird ausgelöst, wenn ein Formular gesendet wird.

Anwendungshinweise

Abrufen eines Formularelement-Objekts

Um ein HTMLFormElement Objekt zu erhalten, können Sie einen CSS-Selektor mit querySelector() verwenden, oder Sie können eine Liste aller Formulare im Dokument mit seiner forms Eigenschaft abrufen.

Document.forms gibt ein Array von HTMLFormElement Objekten zurück, das jedes Formular auf der Seite auflistet. Sie können dann eine der folgenden Syntaxen verwenden, um ein einzelnes Formular zu erhalten:

document.forms[index]

Gibt das Formular am angegebenen index im Array der Formulare zurück.

document.forms[id]

Gibt das Formular zurück, dessen ID das id ist.

document.forms[name]

Gibt das Formular zurück, dessen name Attributswert name ist.

Zugriff auf die Elemente des Formulars

Sie können auf die Liste der datenhältigen Elemente des Formulars zugreifen, indem Sie die Eigenschaft elements des Formulars untersuchen. Dies gibt eine HTMLFormControlsCollection zurück, die alle Benutzerdateneingabeelemente des Formulars auflistet, sowohl die, die Nachkommen des <form> sind, als auch die, die Mitglieder des Formulars sind, indem sie ihre form Attribute verwenden.

Sie können auch das Element des Formulars mit seinem name Attribut als Schlüssel des form erhalten, aber die Verwendung von elements ist ein besserer Ansatz – es enthält nur die Elemente des Formulars und kann nicht mit anderen Attributen des form gemischt werden.

Probleme mit der Benennung von Elementen

Einige Namen werden die JavaScript-Zugriffe auf die Eigenschaften und Elemente des Formulars beeinträchtigen.

Zum Beispiel:

• <input name="id"> wird gegenüber <form id="…"> Vorrang haben. Das bedeutet, dass form.id sich nicht auf die ID des Formulars bezieht, sondern auf das Element, dessen Name "id" ist. Dies wird bei allen anderen Formulareigenschaften der Fall sein, wie <input name="action"> oder <input name="post">.
• <input name="elements"> wird die elements-Sammlung des Formulars unzugänglich machen. Der Verweis form.elements wird jetzt auf das individuelle Element verweisen.

Um solche Probleme mit Elementnamen zu vermeiden:

• Verwenden Sie immer die elements-Sammlung, um Mehrdeutigkeiten zwischen einem Elementnamen und einer Formulareigenschaft zu vermeiden.
• Verwenden Sie niemals "elements" als Elementnamen.

Wenn Sie kein JavaScript verwenden, wird dies kein Problem verursachen.

Elemente, die als Formularsteuerelemente gelten

Die vom HTMLFormElement.elements und HTMLFormElement.length eingeschlossenen Elemente sind die folgenden:

• <button>
• <fieldset>
• <input> (mit der Ausnahme, dass alle, deren type "image" ist, aus historischen Gründen weggelassen werden)
• <object>
• <output>
• <select>
• <textarea>

Keine anderen Elemente sind in der Liste enthalten, die von elements zurückgegeben wird, was es zu einer ausgezeichneten Möglichkeit macht, die wichtigsten Elemente beim Verarbeiten von Formularen zu erfassen.

Beispiele

Erstellung eines neuen Formularelements, Änderung seiner Attribute und anschließendem Absenden:

const f = document.createElement("form"); // Create a form
document.body.appendChild(f); // Add it to the document body
f.action = "/cgi-bin/some.cgi"; // Add action and method attributes
f.method = "POST";
f.submit(); // Call the form's submit() method

Extraktion von Informationen aus einem <form>-Element und Festlegung einiger seiner Attribute:

<form name="formA" action="/cgi-bin/test" method="post">
  <p>Press "Info" for form details, or "Set" to change those details.</p>
  <p>
    <button type="button" id="info">Info</button>
    <button type="button" id="set-info">Set</button>
    <button type="reset">Reset</button>
  </p>

  <textarea id="form-info" rows="15" cols="20"></textarea>
</form>

document.getElementById("info").addEventListener("click", () => {
  // Get a reference to the form via its name
  const f = document.forms["formA"];
  // The form properties we're interested in
  const properties = [
    "elements",
    "length",
    "name",
    "charset",
    "action",
    "acceptCharset",
    "action",
    "enctype",
    "method",
    "target",
  ];
  // Iterate over the properties, turning them into a string that we can display to the user
  const info = properties
    .map((property) => `${property}: ${f[property]}`)
    .join("\n");

  // Set the form's <textarea> to display the form's properties
  document.forms["formA"].elements["form-info"].value = info; // document.forms["formA"]['form-info'].value would also work
});

document.getElementById("set-info").addEventListener("click", (e) => {
  // Get a reference to the form via the event target
  // e.target is the button, and .form is the form it belongs to
  const f = e.target.form;
  // Argument should be a form element reference.
  f.action = "a-different-url.cgi";
  f.name = "a-different-name";
});

Einreichen eines <form> in einem neuen Fenster:

<form action="test.php" target="_blank">
  <p>
    <label>First name: <input type="text" name="first-name" /></label>
  </p>
  <p>
    <label>Last name: <input type="text" name="last-name" /></label>
  </p>
  <p>
    <label><input type="password" name="pwd" /></label>
  </p>

  <fieldset>
    <legend>Pet preference</legend>

    <p>
      <label><input type="radio" name="pet" value="cat" /> Cat</label>
    </p>
    <p>
      <label><input type="radio" name="pet" value="dog" /> Dog</label>
    </p>
  </fieldset>

  <fieldset>
    <legend>Owned vehicles</legend>

    <p>
      <label
        ><input type="checkbox" name="vehicle" value="Bike" />I have a
        bike</label
      >
    </p>
    <p>
      <label
        ><input type="checkbox" name="vehicle" value="Car" />I have a car</label
      >
    </p>
  </fieldset>

  <p><button>Submit</button></p>
</form>

Spezifikationen

Browser-Kompatibilität

Weitere Informationen

• Das HTML-Element, das dieses Interface implementiert: <form>.