The HTMLFormElement
インターフェイスは DOM 内で <form>
要素を表します。これは、フォームのコンポーネント要素へのアクセスだけでなく、フォームの様々な側面へのアクセスや、場合によっては変更を可能にします。
プロパティ
このインターフェイスは親である HTMLElement
からプロパティを継承しています。
HTMLFormElement.elements
読取専用HTMLFormControlsCollection
で、このフォーム要素に所属するすべてのフォームコントロールを保持します。HTMLFormElement.length
読取専用long
で、フォーム内のコントロールの数を反映します。HTMLFormElement.name
DOMString
で、フォームのname
属性の値を反映し、フォームの名前を表します。HTMLFormElement.method
DOMString
で、フォームのmethod
属性の値を反映し、フォームを送信するために使用する HTTP メソッドを示します。指定された値のみが設定できます。HTMLFormElement.target
DOMString
で、フォームのtarget
属性の値を反映し、フォームを送信して受け取った結果を表示する場所を示します。HTMLFormElement.action
DOMString
で、フォームのaction
属性の値を反映し、フォームによって送信された情報を処理するプログラムの URI を示します。HTMLFormElement.encoding
またはHTMLFormElement.enctype
DOMString
で、フォームのenctype
属性の値を反映し、フォームをサーバーへ送信するのに使用するコンテンツの型を示します。指定された方のみが設定できます。二つのプロパティは別名です。HTMLFormElement.acceptCharset
DOMString
で、フォームのaccept-charset
属性の値を反映し、サーバーが受け付ける文字エンコーディングを表します。HTMLFormElement.autocomplete
DOMString
で、フォームのautocomplete
属性の値を反映し、ブラウザーが自動的にこのフォーム内のコントロールの値を生み出すことができるかどうかを示します。HTMLFormElement.noValidate
Boolean
で、フォームのnovalidate
属性の値を反映し、フォームの検証を行わないかどうかを示します。
名前の付いた入力欄がプロパティとしてオーナーのフォームのインスタンスに追加され、同じ名前のネイティブのプロパティがあると上書きしてしまいます (例えば、フォームに action
という名前の入力欄がある場合、action
プロパティはフォームの action
属性ではなくその入力欄を返します)。
メソッド
このインターフェイスは親である HTMLElement
からメソッドを継承しています。
checkValidity()
- この要素の子コントロールが制約検証の対象となり、それらの制約を満たしている場合は
true
を返します。制約を満たさないコントロールがある場合はfalse
を返します。制約を満たさないコントロールに対して、invalid
という名前のイベントを発生させます。イベントがキャンセルされない場合、そのようなコントロールは無効とみなされます。false
にどう対応するかはプログラマ次第です。 reportValidity()
- 要素の子コントロールがその検証する制約を満たしている場合、
true
を返します。false
が返された場合、無効な子要素それぞれにキャンセル可能なinvalid
イベントが発生し、検証上の問題がユーザーに報告されます。 requestSubmit()
- 指定された送信ボタンとそれに対応する設定を使用してフォームを送信するよう要求します。
reset()
- フォームを初期状態にリセットします。
submit()
- フォームをサーバーへ送信します。
非推奨のメソッド
HTMLFormElement.requestAutocomplete()
- ネイティブのブラウザーインターフェイスを起動して、自動補完フィールド名 の値が
off
またはon
ではないフィールドを補完してユーザーを支援します。ユーザーがインターフェイスの操作を終えると、フォームはフィールドが入力された場合はautocomplete
、問題があった場合はautocompleteerror
のいずれかのイベントを受け取ります。
イベント
これらのイベントを待ち受けするには、addEventListener()
を使用するか、このインターフェイスの oneventname
プロパティへイベントリスナーを代入するかしてください。
使用上の注意
フォーム要素オブジェクトの取得
HTMLFormElement
オブジェクトを取得するには、CSS selector と 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 を使っていなければ、これは問題になりません。
フォームコントロールと見なされる要素
The elements included by HTMLFormElement.elements
and HTMLFormElement.length
are the following:
<button>
<fieldset>
<input>
(with the exception that any whosetype
is"image"
are omitted for historical reasons)<object>
<output>
<select>
<textarea>
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>
XMLHttpRequest を使用したフォームの送信とファイルのアップロード
If you want to know how to serialize and submit a form using the XMLHttpRequest
API, please read this paragraph.
仕様書
仕様書 | 状態 | 備考 |
---|---|---|
HTML Living Standard HTMLFormElement の定義 |
現行の標準 | requestAutocomplete() メソッドを追加。 |
HTML5 HTMLFormElement の定義 |
勧告 | elements プロパティが生の HTMLCollection の代わりに HTMLFormControlsCollection を返すようになった。これは主に技術的な変更。checkValidity() メソッドを追加。autocomplete , noValidate , encoding の各プロパティを追加。 |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
- このインターフェイスを実装している HTML 要素:
<form>