HTMLFormElement

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

  <div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 20%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 120" preserveAspectRatio="xMinYMin meet"><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/EventTarget" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25  121,20  121,30  111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/Node" target="_top"><rect x="151" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="188.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Node</text></a><polyline points="226,25  236,20  236,30  226,25" stroke="#D4DDE4" fill="none"/><line x1="236" y1="25" x2="266" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/Element" target="_top"><rect x="266" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="303.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Element</text></a><polyline points="341,25  351,20  351,30  341,25" stroke="#D4DDE4" fill="none"/><line x1="351" y1="25" x2="381" y2="25" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/HTMLElement" target="_top"><rect x="381" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="436" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLElement</text></a><polyline points="491,25  501,20  501,30  491,25" stroke="#D4DDE4" fill="none"/><line x1="501" y1="25" x2="509" y2="25" stroke="#D4DDE4"/><line x1="509" y1="25" x2="509" y2="90" stroke="#D4DDE4"/><line x1="509" y1="90" x2="492" y2="90" stroke="#D4DDE4"/><a xlink:href="https://developer.mozilla.org/ja/docs/Web/API/HTMLFormElement" target="_top"><rect x="341" y="65" width="150" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text  x="416" y="94" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLFormElement</text></a></svg></div>

  a:hover text { fill: #0095DD; pointer-events: all;}

プロパティ

このインターフェイスは親である 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 プロパティへイベントリスナーを代入するかしてください。

formdata

formdata イベントは、フォームのデータを表す項目リストが構築されると発行されます。
onformdata プロパティからも利用できます。

reset

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

onreset プロパティからも利用できます。

submit

submit イベントはフォームが送信されたときに発行されます。
onsubmit プロパティからも利用できます。

使用上の注意

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

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 whose type 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 要素: <form>