HTMLFormElement

HTMLFormElement インターフェイスは DOM 内の <form> 要素を表します。これは、フォームのコンポーネント要素へのアクセスだけでなく、フォームの様々な側面へのアクセスや、場合によっては変更を可能にします。

インスタンスプロパティ

このインターフェイスには親である HTMLElement から継承したプロパティもあります。

HTMLFormElement.elements 読取専用

HTMLFormControlsCollection で、このフォーム要素に所属するすべてのフォームコントロールを保持します。

HTMLFormElement.length 読取専用

long で、フォーム内のコントロールの数を反映します。

HTMLFormElement.name

文字列で、フォームの name 属性の値を反映し、フォームの名前を表します。

HTMLFormElement.method

文字列で、フォームの method 属性の値を反映し、フォームを送信するために使用する HTTP メソッドを示します。指定された値のみが設定できます。

HTMLFormElement.target

文字列で、フォームの target 属性の値を反映し、フォームを送信して受け取った結果を表示する場所を示します。

HTMLFormElement.action

文字列で、フォームの action 属性の値を反映し、フォームによって送信された情報を処理するプログラムの URI を示します。

HTMLFormElement.encoding または HTMLFormElement.enctype

文字列で、フォームの enctype 属性の値を反映し、フォームをサーバーへ送信するのに使用するコンテンツの型を示します。指定された方のみが設定できます。二つのプロパティは別名です。

HTMLFormElement.acceptCharset

文字列で、フォームの accept-charset 属性の値を反映し、サーバーが受け付ける文字エンコーディングを表します。

HTMLFormElement.autocomplete

文字列で、フォームの autocomplete 属性の値を反映し、ブラウザーが自動的にこのフォーム内のコントロールの値を生み出すことができるかどうかを示します。

HTMLFormElement.noValidate

Boolean で、フォームの novalidate 属性の値を反映し、フォームの検証を行わないかどうかを示します。

名前の付いた入力欄がプロパティとしてオーナーのフォームのインスタンスに追加され、同じ名前のネイティブのプロパティがあると上書きしてしまいます(例えば、フォームに action という名前の入力欄がある場合、 action プロパティはフォームの action 属性ではなくその入力欄を返します)。

インスタンスメソッド

このインターフェイスには親である HTMLElement から継承したメソッドもあります。

checkValidity()

この要素の子コントロールが制約検証の対象となり、それらの制約を満たしている場合は true を返します。制約を満たさないコントロールがある場合は false を返します。制約を満たさないコントロールに対して、invalid という名前のイベントを発生させます。イベントがキャンセルされない場合、そのようなコントロールは無効とみなされます。false にどう対応するかはプログラマー次第です。

reportValidity()

要素の子コントロールがその検証する制約を満たしている場合、true を返します。false が返された場合、無効な子要素それぞれにキャンセル可能な invalid イベントが発生し、検証上の問題がユーザーに報告されます。

requestSubmit()

指定された送信ボタンとそれに対応する設定を使用してフォームを送信するよう要求します。

reset()

フォームを初期状態にリセットします。

submit()

フォームをサーバーへ送信します。

イベント

これらのイベントを待ち受けするには、addEventListener() を使用するか、このインターフェイスの oneventname プロパティへイベントリスナーを代入するかしてください。

formdata

formdata イベントは、フォームのデータを表す項目リストが構築されると発行されます。

reset

reset イベントはフォームがリセットされたときに発行されます。

submit

submit イベントはフォームが送信されたときに発行されます。

使用上の注意

フォーム要素オブジェクトの取得

HTMLFormElement オブジェクトを取得するには、CSS セレクターと querySelector() を使うか、document の forms プロパティを使ってすべてのフォームのリストを取得できます。

Document.forms は HTMLFormElement オブジェクトの配列、つまりそのページの各フォームの一覧を返します。その後、以下の構文を使用して、個々のフォームを取得することができます。

document.forms[index]

フォーム配列の指定した index のフォームを返します。

document.forms[id]

ID が id であるフォームを返します。

document.forms[name]

name 属性値が name であるフォームを返します。

フォーム内の要素へのアクセス

フォームのデータを含む要素の一覧にアクセスするには、フォームの elements プロパティを調べることでできます。これはフォームのユーザーデータ入力要素をすべて列挙する 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 を使っていなければ、これは問題になりません。

フォームコントロールと見なされる要素

HTMLFormElement.elements および HTMLFormElement.length に含まれる要素は以下のものです。

• <button>
• <fieldset>
• <input> (type が "image" のものは歴史的な理由により除外されます)
• <object>
• <output>
• <select>
• <textarea>

elements が返す一覧には他の要素が記載されないので、フォームを処理する際に最も重要な要素を取得するための優れた方法となります。

例

新しいフォーム要素を作成し、その属性を変更し、送信します。

const f = document.createElement("form"); // フォームを作成
document.body.appendChild(f); // 文書の本体に追加
f.action = "/cgi-bin/some.cgi"; // action および method 属性を追加
f.method = "POST";
f.submit(); // フォームの submit() メソッド

<form> 要素から情報を取り出し、その属性のいくつかを設定します。

<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() {
 // フォームの名前からそのフォームへの参照を取得する
 const f = document.forms["formA"];
 // 関心のあるフォームプロパティ
 const properties = [
 "elements",
 "length",
 "name",
 "charset",
 "action",
 "acceptCharset",
 "action",
 "enctype",
 "method",
 "target",
 ];
 // プロパティを反復処理し、文字列に円関してユーザーに表示できるようにする
 const info = properties
 .map((property) => `${property}: ${f[property]}`)
 .join("\n");
 // フォームの <textarea> にフォームのプロパティを表示するように設定する
 document.forms["formA"].elements["form-info"].value = info; // document.forms["formA"]['form-info'].value would also work
 }
 function setFormInfo(f) {
 // 引数は、フォーム要素の参照でなければならない
 f.action = "a-different-url.cgi";
 f.name = "a-different-name";
 }
</script>

<form> を新しいウィンドウへ送信します。

<!doctype html>
<html lang="en-US">
 <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="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>
 </body>
</html>

仕様書

ブラウザーの互換性

関連情報

• このインターフェイスを実装している HTML 要素: <form>