The HTMLFormElement インターフェイスは DOM 内で {{HTMLElement("form")}} 要素を表します。これは、フォームのコンポーネント要素へのアクセスだけでなく、フォームの様々な側面へのアクセスや、場合によっては変更を可能にします。
{{InheritanceDiagram(600,120)}}
このインターフェイスは親である {{domxref("HTMLElement")}} からプロパティを継承しています。
long で、フォーム内のコントロールの数を反映します。名前の付いた入力欄がプロパティとしてオーナーのフォームのインスタンスに追加され、同じ名前のネイティブのプロパティがあると上書きしてしまいます (例えば、フォームに action という名前の入力欄がある場合、action プロパティはフォームの {{ htmlattrxref("action", "form") }} 属性ではなくその入力欄を返します)。
このインターフェイスは親である {{domxref("HTMLElement")}} からメソッドを継承しています。
true を返します。制約を満たさないコントロールがある場合は false を返します。制約を満たさないコントロールに対して、{{domxref("HTMLInputElement/invalid_event", "invalid")}} という名前のイベントを発生させます。イベントがキャンセルされない場合、そのようなコントロールは無効とみなされます。false にどう対応するかはプログラマ次第です。true を返します。false が返された場合、無効な子要素それぞれにキャンセル可能な {{domxref("HTMLInputElement/invalid_event", "invalid")}} イベントが発生し、検証上の問題がユーザーに報告されます。off または on ではないフィールドを補完してユーザーを支援します。ユーザーがインターフェイスの操作を終えると、フォームはフィールドが入力された場合は {{event("autocomplete")}}、問題があった場合は {{event("autocompleteerror")}} のいずれかのイベントを受け取ります。これらのイベントを待ち受けするには、addEventListener() を使用するか、このインターフェイスの oneventname プロパティへイベントリスナーを代入するかしてください。
formdata イベントは、フォームのデータを表す項目リストが構築されると発行されます。reset イベントはフォームがリセットされたときに発行されます。submit イベントはフォームが送信されたときに発行されます。HTMLFormElement オブジェクトを取得するには、CSS selector と {{domxref("ParentNode.querySelector", "querySelector()")}}を使うか、document の {{domxref("Document.forms", "forms")}} プロパティを使ってすべてのフォームのリストを取得できます。
{{domxref("Document.forms")}} は HTMLFormElement オブジェクトの配列、つまりそのページの各フォームの一覧を返します。個別のフォームを取得するには、下記の文法を使うことができます:
document.forms[index]index のフォームを返します。document.forms[id]idであるフォームを返します。document.forms[name]nameであるフォームを返します。フォームのデータを含む要素の一覧にアクセスするには、フォームの{{domxref("HTMLFormElement.elements", "elements")}} プロパティを調べることでできます。これはフォームのユーザーデータ入力要素の全一覧の{{domxref("HTMLFormControlsCollection")}} を返し、これには <form> の子孫と、form 属性を使ったフォームのメンバーからなるものの両方が返されます。
フォームの要素を探すのに form のキーとして name 属性を使うこともできますが、 elements を使うのがより良い方法です—フォーム要素のみを含み、formの他の属性と混合されることがないです。
名前によっては JavaScript からのプロパティや要素のアクセスが干渉します。
例えば、
<input name="id"> は <form id="…">に優先します。つまり form.id ではフォームのidを参照せずに、名前が "id"である要素を参照します。その他のプロパティも同様であり、例えば <input name="action"> や <input name="post">もそうです。<input name="elements"> はフォーム elements のコレクションをアクセス不能にします。form.elements は個別の要素を参照します。要素名のこうした問題を避けるには:
elements のコレクションを使って、要素名とフォームプロパティとのあいまいさを避けます。elements" を使わない。JavaScript を使っていなければ、これは問題になりません。
The elements included by HTMLFormElement.elements and HTMLFormElement.length are the following:
"image" are omitted for historical reasons)No other elements are included in the list returned by elements, which makes it an excellent way to get at the elements most important when processing forms.
Creating a new form element, modifying its attributes, then submitting it:
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
Extract information from a <form> element and set some of its attributes:
<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" onclick="getFormInfo();">Info</button>
<button type="button" onclick="setFormInfo(this.form);">Set</button>
<button type="reset">Reset</button>
</p>
<textarea id="form-info" rows="15" cols="20"></textarea>
</form>
<script>
function getFormInfo(){
// Get a reference to the form via its name
var f = document.forms["formA"];
// The form properties we're interested in
var 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
var info = properties.map(function(property) { return 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
}
function setFormInfo(f){ // Argument should be a form element reference.
f.action = "a-different-url.cgi";
f.name = "a-different-name";
}
</script>
Submit a <form> into a new window:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Example new-window form submission</title>
</head>
<body>
<form action="test.php" target="_blank">
<p><label>First name: <input type="text" name="firstname"></label></p>
<p><label>Last name: <input type="text" name="lastname"></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>
</body>
</html>
If you want to know how to serialize and submit a form using the {{domxref("XMLHttpRequest")}} API, please read this paragraph.
| 仕様書 | 状態 | 備考 |
|---|---|---|
| {{SpecName('HTML WHATWG', "#htmlformelement", "HTMLFormElement")}} | {{Spec2('HTML WHATWG')}} | requestAutocomplete() メソッドを追加。 |
| {{SpecName('HTML5 W3C', "sec-forms.html#htmlformelement", "HTMLFormElement")}} | {{Spec2('HTML5 W3C')}} | elements プロパティが生の {{domxref("HTMLCollection")}} の代わりに {{domxref("HTMLFormControlsCollection")}} を返すようになった。これは主に技術的な変更。checkValidity() メソッドを追加。autocomplete, noValidate, encoding の各プロパティを追加。 |
{{Compat("api.HTMLFormElement")}}