diff options
Diffstat (limited to 'files/ja/web/api/htmlformelement/index.html')
| -rw-r--r-- | files/ja/web/api/htmlformelement/index.html | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/files/ja/web/api/htmlformelement/index.html b/files/ja/web/api/htmlformelement/index.html new file mode 100644 index 0000000000..1cc72796ee --- /dev/null +++ b/files/ja/web/api/htmlformelement/index.html @@ -0,0 +1,266 @@ +--- +title: HTMLFormElement +slug: Web/API/HTMLFormElement +tags: + - API + - Form Element + - Forms + - HTML DOM + - HTML forms + - HTMLFormElement + - Interface + - Reference +translation_of: Web/API/HTMLFormElement +--- +<div>{{APIRef("HTML DOM")}}</div> + +<p><span class="seoSummary">The <code><strong>HTMLFormElement</strong></code> インターフェイスは DOM 内で {{HTMLElement("form")}} 要素を表します。これは、フォームのコンポーネント要素へのアクセスだけでなく、フォームの様々な側面へのアクセスや、場合によっては変更を可能にします。</span></p> + +<p>{{InheritanceDiagram(600,120)}}</p> + +<h2 id="Properties" name="Properties">プロパティ</h2> + +<p><em>このインターフェイスは親である {{domxref("HTMLElement")}} からプロパティを継承しています。</em></p> + +<dl> + <dt>{{domxref("HTMLFormElement.elements")}} {{ReadOnlyInline}}</dt> + <dd>{{domxref("HTMLFormControlsCollection")}} で、このフォーム要素に所属するすべてのフォームコントロールを保持します。</dd> + <dt>{{domxref("HTMLFormElement.length")}}{{ReadOnlyInline}}</dt> + <dd><code>long</code> で、フォーム内のコントロールの数を反映します。</dd> + <dt>{{domxref("HTMLFormElement.name")}}</dt> + <dd>{{domxref("DOMString")}} で、フォームの {{ htmlattrxref("name", "form") }} 属性の値を反映し、フォームの名前を表します。</dd> + <dt>{{domxref("HTMLFormElement.method")}}</dt> + <dd>{{domxref("DOMString")}} で、フォームの {{ htmlattrxref("method", "form") }} 属性の値を反映し、フォームを送信するために使用する HTTP メソッドを示します。指定された値のみが設定できます。</dd> + <dt>{{domxref("HTMLFormElement.target")}}</dt> + <dd>{{domxref("DOMString")}} で、フォームの {{ htmlattrxref("target", "form") }} 属性の値を反映し、フォームを送信して受け取った結果を表示する場所を示します。</dd> + <dt>{{domxref("HTMLFormElement.action")}}</dt> + <dd>{{domxref("DOMString")}} で、フォームの {{ htmlattrxref("action", "form") }} 属性の値を反映し、フォームによって送信された情報を処理するプログラムの URI を示します。</dd> + <dt>{{domxref("HTMLFormElement.encoding")}} または {{domxref("HTMLFormElement.enctype")}}</dt> + <dd>{{domxref("DOMString")}} で、フォームの {{ htmlattrxref("enctype", "form") }} 属性の値を反映し、フォームをサーバーへ送信するのに使用するコンテンツの型を示します。指定された方のみが設定できます。二つのプロパティは別名です。</dd> + <dt>{{domxref("HTMLFormElement.acceptCharset")}}</dt> + <dd>{{domxref("DOMString")}} で、フォームの {{ htmlattrxref("accept-charset", "form") }} 属性の値を反映し、サーバーが受け付ける文字エンコーディングを表します。</dd> + <dt>{{domxref("HTMLFormElement.autocomplete")}}</dt> + <dd>{{domxref("DOMString")}} で、フォームの {{ htmlattrxref("autocomplete", "form") }} 属性の値を反映し、ブラウザーが自動的にこのフォーム内のコントロールの値を生み出すことができるかどうかを示します。</dd> + <dt>{{domxref("HTMLFormElement.noValidate")}}</dt> + <dd>{{jsxref("Boolean")}} で、フォームの {{ htmlattrxref("novalidate", "form") }} 属性の値を反映し、フォームの検証を行わないかどうかを示します。</dd> +</dl> + +<p>名前の付いた入力欄がプロパティとしてオーナーのフォームのインスタンスに追加され、同じ名前のネイティブのプロパティがあると上書きしてしまいます (例えば、フォームに <code>action</code> という名前の入力欄がある場合、<code>action</code> プロパティはフォームの {{ htmlattrxref("action", "form") }} 属性ではなくその入力欄を返します)。</p> + +<h2 id="Methods" name="Methods">メソッド</h2> + +<p><em>このインターフェイスは親である {{domxref("HTMLElement")}} からメソッドを継承しています。</em></p> + +<dl> + <dt>{{domxref("HTMLFormElement.checkValidity", "checkValidity()")}}</dt> + <dd>この要素の子コントロールが<a href="/ja/docs/Web/Guide/HTML/HTML5/Constraint_validation">制約検証</a>の対象となり、それらの制約を満たしている場合は <code>true</code> を返します。制約を満たさないコントロールがある場合は <code>false</code> を返します。制約を満たさないコントロールに対して、{{domxref("HTMLInputElement/invalid_event", "invalid")}} という名前のイベントを発生させます。イベントがキャンセルされない場合、そのようなコントロールは無効とみなされます。<code>false</code> にどう対応するかはプログラマ次第です。</dd> + <dt>{{domxref("HTMLFormElement.reportValidity", "reportValidity()")}}</dt> + <dd>要素の子コントロールがその<a href="/ja/docs/Web/Guide/HTML/HTML5/Constraint_validation">検証する制約</a>を満たしている場合、<code>true</code> を返します。<code>false</code> が返された場合、無効な子要素それぞれにキャンセル可能な {{domxref("HTMLInputElement/invalid_event", "invalid")}} イベントが発生し、検証上の問題がユーザーに報告されます。</dd> + <dt>{{domxref("HTMLFormElement.requestSubmit", "requestSubmit()")}}</dt> + <dd>指定された送信ボタンとそれに対応する設定を使用してフォームを送信するよう要求します。</dd> + <dt>{{domxref("HTMLFormElement.reset", "reset()")}}</dt> + <dd>フォームを初期状態にリセットします。</dd> + <dt>{{domxref("HTMLFormElement.submit", "submit()")}}</dt> + <dd>フォームをサーバーへ送信します。</dd> +</dl> + +<h3 id="Deprecated_methods" name="Deprecated_methods">非推奨のメソッド</h3> + +<dl> + <dt>{{domxref("HTMLFormElement.requestAutocomplete()")}} {{deprecated_inline}}</dt> + <dd>ネイティブのブラウザーインターフェイスを起動して、<a href="https://html.spec.whatwg.org/#autofill-field-name">自動補完フィールド名</a> の値が <code>off</code> または <code>on</code> ではないフィールドを補完してユーザーを支援します。ユーザーがインターフェイスの操作を終えると、フォームはフィールドが入力された場合は {{event("autocomplete")}}、問題があった場合は {{event("autocompleteerror")}} のいずれかのイベントを受け取ります。</dd> +</dl> + +<h2 id="Events" name="Events">イベント</h2> + +<p>これらのイベントを待ち受けするには、<code>addEventListener()</code> を使用するか、このインターフェイスの <code>on<var>eventname</var></code> プロパティへイベントリスナーを代入するかしてください。</p> + +<dl> + <dt>{{domxref("HTMLFormElement/formdata_event", "formdata")}}</dt> + <dd><code>formdata</code> イベントは、フォームのデータを表す項目リストが構築されると発行されます。<br> + {{domxref("GlobalEventHandlers/onformdata", "onformdata")}} プロパティからも利用できます。</dd> + <dt>{{domxref("HTMLFormElement/reset_event", "reset")}}</dt> + <dd><code>reset</code> イベントはフォームがリセットされたときに発行されます。</dd> + <dd>{{domxref("GlobalEventHandlers/onreset", "onreset")}} プロパティからも利用できます。</dd> + <dt>{{domxref("HTMLFormElement/submit_event", "submit")}}</dt> + <dd><code>submit</code> イベントはフォームが送信されたときに発行されます。<br> + {{domxref("GlobalEventHandlers/onsubmit", "onsubmit")}} プロパティからも利用できます。</dd> +</dl> + +<h2 id="Usage_notes" name="Usage_notes">使用上の注意</h2> + +<h3 id="Obtaining_a_form_element_object" name="Obtaining_a_form_element_object">フォーム要素オブジェクトの取得</h3> + +<p><code>HTMLFormElement</code> オブジェクトを取得するには、<a href="/ja/docs/Web/CSS/CSS_Selectors">CSS selector</a> と {{domxref("ParentNode.querySelector", "querySelector()")}}を使うか、document の {{domxref("Document.forms", "forms")}} プロパティを使ってすべてのフォームのリストを取得できます。</p> + +<p>{{domxref("Document.forms")}} は <code>HTMLFormElement</code> オブジェクトの配列、つまりそのページの各フォームの一覧を返します。個別のフォームを取得するには、下記の文法を使うことができます:</p> + +<dl> + <dt><code>document.forms[<var>index</var>]</code></dt> + <dd>フォーム配列の指定した <code><var>index</var></code> のフォームを返します。</dd> + <dt><code>document.forms[<var>id</var>]</code></dt> + <dd>ID が <code><var>id</var></code>であるフォームを返します。</dd> + <dt><code>document.forms[<var>name</var>]</code></dt> + <dd>{{domxref("Element.name", "name")}} 属性値が <code><var>name</var></code>であるフォームを返します。</dd> +</dl> + +<h3 id="Accessing_the_forms_elements" name="Accessing_the_forms_elements">フォーム内の要素へのアクセス</h3> + +<p>フォームのデータを含む要素の一覧にアクセスするには、フォームの{{domxref("HTMLFormElement.elements", "elements")}} プロパティを調べることでできます。これはフォームのユーザーデータ入力要素の全一覧の{{domxref("HTMLFormControlsCollection")}} を返し、これには <code><form></code> の子孫と、<code>form</code> 属性を使ったフォームのメンバーからなるものの両方が返されます。</p> + +<p>フォームの要素を探すのに <code>form</code> のキーとして <code>name</code> 属性を使うこともできますが、 <code>elements</code> を使うのがより良い方法です—フォーム要素<em>のみ</em>を含み、<code>form</code>の他の属性と混合されることがないです。</p> + +<h3 id="Issues_with_Naming_Elements" name="Issues_with_Naming_Elements">要素の名前付けの問題</h3> + +<p>名前によっては JavaScript からのプロパティや要素のアクセスが干渉します。</p> + +<p>例えば、</p> + +<ul> + <li><code><input name="id"></code> は <code><form id="…"></code>に優先します。つまり <code>form.id</code> ではフォームのidを参照せずに、名前が "<code>id</code>"である要素を参照します。その他のプロパティも同様であり、例えば <code><input name="action"></code> や <code><input name="post"></code>もそうです。</li> + <li><code><input name="elements"></code> はフォーム <code>elements</code> のコレクションをアクセス不能にします。<code>form.elements</code> は個別の要素を参照します。</li> +</ul> + +<p>要素名のこうした問題を避けるには:</p> + +<ul> + <li><em>常に</em> <code>elements</code> のコレクションを使って、要素名とフォームプロパティとのあいまいさを避けます。</li> + <li><em>決して</em>要素名に "<code>elements</code>" を使わない。</li> +</ul> + +<p>JavaScript を使っていなければ、これは問題になりません。</p> + +<h3 id="Elements_that_are_considered_form_controls" name="Elements_that_are_considered_form_controls">フォームコントロールと見なされる要素</h3> + +<p>The elements included by <code>HTMLFormElement.elements</code> and <code>HTMLFormElement.length</code> are the following:</p> + +<ul> + <li>{{HTMLElement("button")}}</li> + <li>{{HTMLElement("fieldset")}}</li> + <li>{{HTMLElement("input")}} (with the exception that any whose {{htmlattrxref("type", "input")}} is <code>"image"</code> are omitted for historical reasons)</li> + <li>{{HTMLElement("object")}}</li> + <li>{{HTMLElement("output")}}</li> + <li>{{HTMLElement("select")}}</li> + <li>{{HTMLElement("textarea")}}</li> +</ul> + +<p>No other elements are included in the list returned by <code>elements</code>, which makes it an excellent way to get at the elements most important when processing forms.</p> + +<h2 id="Examples" name="Examples">例</h2> + +<p>Creating a new form element, modifying its attributes, then submitting it:</p> + +<pre class="brush: js notranslate">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 +</pre> + +<p>Extract information from a <code><form></code> element and set some of its attributes:</p> + +<pre class="brush: html notranslate"><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> +</pre> + +<p>Submit a <code><form></code> into a new window:</p> + +<pre class="brush: html notranslate"><!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></pre> + +<h3 id="Submitting_forms_and_uploading_files_using_XMLHttpRequest" name="Submitting_forms_and_uploading_files_using_XMLHttpRequest">XMLHttpRequest を使用したフォームの送信とファイルのアップロード</h3> + +<p>If you want to know how to serialize and submit a form using the {{domxref("XMLHttpRequest")}} API, please read <a href="/ja/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files">this paragraph</a>.</p> + +<h2 id="Specifications" name="Specifications">仕様書</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">仕様書</th> + <th scope="col">状態</th> + <th scope="col">備考</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('HTML WHATWG', "#htmlformelement", "HTMLFormElement")}}</td> + <td>{{Spec2('HTML WHATWG')}}</td> + <td><code>requestAutocomplete()</code> メソッドを追加。</td> + </tr> + <tr> + <td>{{SpecName('HTML5 W3C', "sec-forms.html#htmlformelement", "HTMLFormElement")}}</td> + <td>{{Spec2('HTML5 W3C')}}</td> + <td>elements プロパティが生の {{domxref("HTMLCollection")}} の代わりに {{domxref("HTMLFormControlsCollection")}} を返すようになった。これは主に技術的な変更。<code>checkValidity()</code> メソッドを追加。<code>autocomplete</code>, <code>noValidate</code>, <code>encoding</code> の各プロパティを追加。</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h2> + +<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、<a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div> + +<p>{{Compat("api.HTMLFormElement")}}</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li>このインターフェイスを実装している HTML 要素: {{ HTMLElement("form") }}</li> +</ul> |