HTMLFormElement: requestSubmit() メソッド

構文

requestSubmit()
requestSubmit(submitter)

引数

submitter 省略可

このフォームのメンバーである送信ボタンです。

submitter が form* 属性を指定している場合、このフォームの送信動作を上書きします（formmethod="POST" など）。

submitter に name 属性があるか<input type="image"> であった場合、フォームの送信時にそのデータが含まれます（btnName=btnValue など）。

submitter 引数を省略した場合、このフォーム要素自身が送信者として使用されます。

返値

なし (undefined)。

例外

TypeError

指定された submitter が送信ボタンでなかった場合に発生します。

NotFoundError DOMException

指定された submitter が、 requestSubmit() が呼び出されたフォームのメンバーでない場合に発生します。submitter は form 要素の子孫であるか、フォームを参照する form 属性を持たなければなりません。

使用上の注意

明らかな疑問は、なぜこのメソッドが存在するのかということです。 submit() メソッドがあったのに、なぜこのメソッドが存在するのでしょうか？

答えは簡単です。submit() はフォームを送信しますが、それだけです。一方、requestSubmit() は、あたかも送信ボタンがクリックされたかのように動作します。フォームのコンテンツが検証され、検証が成功した場合にのみフォームが送信されます。フォームが送信されると、submit イベントがフォームオブジェクトに返送されます。

例

以下の例では、requestSubmit() が利用できる場合はそれを使用してリクエストの送信を試みることで、フォームを送信しています。 main-submit という ID の送信ボタンが得られた場合は、そのボタンを使用してフォームを送信します。そうでない場合は、 submitter 引数を指定せずに、フォーム自身から直接送信されます。

一方で、 requestSubmit() が利用できない場合、このコードは代わりにフォームの submit() メソッドを呼び出すことで送信を行います。

let myForm = document.querySelector("form");
let submitButton = myForm.querySelector("#main-submit");

if (myForm.requestSubmit) {
  if (submitButton) {
    myForm.requestSubmit(submitButton);
  } else {
    myForm.requestSubmit();
  }
} else {
  myForm.submit();
}

仕様書

ブラウザーの互換性