HTMLFormElement : méthode requestSubmit()

Syntaxe

requestSubmit()
requestSubmit(submitter)

Paramètres

submitter Facultatif

Un bouton de soumission qui est membre du formulaire.

Si le submitter précise des attributs form*, ils remplaceront le comportement de soumission du formulaire (par exemple, formmethod="POST").

Si le submitter a un attribut name ou s'il s'agit d'un <input type="image">, ses données seront incluses dans la soumission du formulaire (par exemple, btnName=btnValue).

Si vous omettez le paramètre submitter, l'élément formulaire lui‑même est utilisé comme soumetteur.

Valeur de retour

Aucun (undefined).

Exceptions

-- TypeError

• : Levée si le submitter défini n'est pas un bouton de soumission.
• NotFoundError DOMException
  • : Levée si le submitter défini n'est pas membre du formulaire sur lequel requestSubmit() a été appelé. Le submitter doit être soit un descendant de l'élément form, soit disposer d'un attribut form faisant référence au formulaire.

Notes d'utilisation

La question évidente est : pourquoi cette méthode existe‑t‑elle, alors que nous disposons de la méthode submit() depuis toujours ?

La réponse est simple. submit() soumet le formulaire, mais c'est tout ce qu'elle fait. requestSubmit(), en revanche, agit comme si un bouton de soumission avait été cliqué. Le contenu du formulaire est validé, et le formulaire est soumis seulement si la validation réussit. Une fois le formulaire soumis, l'événement submit est renvoyé à l'objet form.

Exemples

Dans l'exemple ci‑dessous, le formulaire est soumis en tentant d'utiliser requestSubmit() si cette méthode est disponible. Si un bouton de soumission ayant pour ID main-submit est trouvé, il est utilisé pour soumettre le formulaire. Sinon, le formulaire est soumis sans paramètre submitter, donc il est soumis directement par l'élément form lui‑même.

Si, en revanche, requestSubmit() n'est pas disponible, ce code revient à appeler la méthode submit() du formulaire.

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();
}

Spécifications

Compatibilité des navigateurs