HTMLFormElement

この記事は翻訳が完了していません。 この記事の翻訳にご協力ください

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 プロパティへイベントリスナーを代入するかしてください。

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

使用上の注意

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

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

Document.formsHTMLFormElement オブジェクトの配列、つまりそのページの各フォームの一覧を返します。個別のフォームを取得するには、下記の文法を使うことができます:

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:

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 の各プロパティを追加。

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
HTMLFormElementChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 1IE 完全対応 9Opera 完全対応 8Safari 完全対応 3WebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 10.1Safari iOS 完全対応 1Samsung Internet Android 完全対応 1.0
acceptCharsetChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
actionChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
autocompleteChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
checkValidityChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
elementsChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 1IE 完全対応 9Opera 完全対応 8Safari 完全対応 3WebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 10.1Safari iOS 完全対応 1Samsung Internet Android 完全対応 1.0
encodingChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
enctypeChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
formdata eventChrome 完全対応 77Edge 完全対応 79Firefox 完全対応 72IE 未対応 なしOpera 完全対応 64Safari 未対応 なしWebView Android 完全対応 77Chrome Android 完全対応 77Firefox Android 未対応 なしOpera Android 完全対応 55Safari iOS 未対応 なしSamsung Internet Android 完全対応 12.0
lengthChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
methodChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
nameChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
noValidateChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
reportValidityChrome 完全対応 40Edge 完全対応 17Firefox 完全対応 49IE 未対応 なしOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 40Chrome Android 完全対応 40Firefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 4.0
requestAutocomplete
非推奨非標準
Chrome 未対応 なしEdge 未対応 なしFirefox 未対応 なしIE ? Opera 未対応 なしSafari ? WebView Android 未対応 なしChrome Android 未対応 なしFirefox Android 未対応 なしOpera Android 未対応 なしSafari iOS ? Samsung Internet Android 未対応 なし
requestSubmit()Chrome 完全対応 76Edge 完全対応 79Firefox 完全対応 75IE 未対応 なしOpera 完全対応 63Safari 未対応 なしWebView Android 完全対応 76Chrome Android 完全対応 76Firefox Android 未対応 なしOpera Android 完全対応 54Safari iOS 未対応 なしSamsung Internet Android 完全対応 12.0
resetChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 1IE 完全対応 9Opera 完全対応 8Safari 完全対応 3WebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 10.1Safari iOS 完全対応 1Samsung Internet Android 完全対応 1.0
reset eventChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
submitChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE 完全対応 ありOpera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり
submit eventChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 1IE 完全対応 9Opera 完全対応 8Safari 完全対応 3WebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 10.1Safari iOS 完全対応 1Samsung Internet Android 完全対応 1.0
targetChrome 完全対応 ありEdge 完全対応 12Firefox 完全対応 ありIE ? Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 ありChrome Android 完全対応 ありFirefox Android 完全対応 ありOpera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 あり

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
非標準。ブラウザー間の互換性が低い可能性があります。
非標準。ブラウザー間の互換性が低い可能性があります。
非推奨。新しいウェブサイトでは使用しないでください。
非推奨。新しいウェブサイトでは使用しないでください。

関連情報

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