HTMLFormElement
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
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()
-
フォームをサーバーへ送信します。
イベント
使用上の注意
フォーム要素オブジェクトの取得
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>
仕様書
Specification |
---|
HTML Standard # htmlformelement |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
- このインターフェイスを実装している HTML 要素:
<form>