L'interface HTMLFormElement fournit un ensemble de méthodes pour créer et modifier des éléments <form>.

  • document.forms renvoie un tableau d'objets HTMLFormElement recensant tous les formulaires de la page.
  • document.forms[index] renvoie un objet HTMLFormElement correspondant au formulaire situé à l'index indiqué.
  • document.forms['id'] renvoie un objet HTMLFormElement correspondant au formulaire ayant l'identifiant indiqué (cf. id).
  • document.forms['name'] renvoie un objet HTMLFormElement correspondant au formulaire ayant le nom indiqué (cf. name).

Propriétés

Cette interface hérite également des propriétés de l'interface parente HTMLElement.

HTMLFormElement.elementsLecture seule
Un élément HTMLFormControlsCollection regroupant les différents contrôles associés à ce formulaire.
HTMLFormElement.lengthLecture seule
Une valeur de type long indiquant le nombre de contrôles dans le formulaire.
HTMLFormElement.name
Une chaîne DOMString indiquant la valeur de l'attribut HTML name pour ce formulaire et qui correspond au nom du formulaire.
HTMLFormElement.method
Une chaîne DOMString indiquant la valeur de l'attribut HTML method pour ce formulaire et qui correspond à la méthode HTTP utilisée pour envoyer le formulaires. Seules certaines valeurs peuvent être utilisées avec cette propriété.
HTMLFormElement.target
Une chaîne DOMString indiquant la valeur de l'attribut HTML target pour ce formulaire et qui indique l'emplacement où seront affichées les résultats après envoi du formulaire.
HTMLFormElement.action
Une chaîne DOMString indiquant la valeur de l'attribut HTML action pour ce formulaire et qui contient l'URI d'un programme traitant les informations transmises via le formulaire.
HTMLFormElement.encoding ou HTMLFormElement.enctype
Une chaîne DOMString indiquant la valeur de l'attribut HTML enctype pour ce formulaire et qui correspond au type de contenu utilisé pour transmettre les données du formulaire vers le serveur. Seules certaines valeurs peuvent être utilisées pour cette propriété. Les deux noms indiqués pour la méthode sont synonymes.
HTMLFormElement.acceptCharset
Une chaîne DOMString indiquant la valeur de l'attribut HTML accept-charset pour ce formulaire et qui correspond au jeu de caractères / à l'encodage pris en charge par le serveur.
HTMLFormElement.autocomplete
Une chaîne DOMString indiquant la valeur de l'attribut HTML autocomplete pour ce formulaire et qui indique si les contrôles du formulaire sont automatiquement renseignés par le navigateur.
HTMLFormElement.noValidate
Un booléen indiquant la valeur de l'attribut HTML novalidate pour ce formulaire et qui indique si le formulaire ne devrait pas être validé.

Les champs de saisie nommés sont ajoutés comme propriétés sur leurs formulaires associés. Ces propriétés peuvent surcharger les propriétés natives si elles utilisent le même nom ! Par exemple, un formulaire disposant d'un <<input>> nommé action surchargera la propriété native action et tout appel renverra le champ input plutôt que la valeur de l'attribut HTML action.

Méthodes

Cette interface hérite également de méthode via son interface parente HTMLElement.

HTMLFormElement.submit()
Cette méthode envoie les données du formulaire au serveur.
HTMLFormElement.reset()
Cette méthode réinitialise les valeurs du formulaire à leur état initial.
HTMLFormElement.checkValidity()
Cette méthode renvoie true si les contrôles du formulaire sont soumis à des contraintes de validation et les respectent. Elle renvoie false si certains contrôles ne respectent pas leurs contraintes. Elle déclenche un évènement invalid pour chaque contrôle qui ne respecte pas ses contraintes. De tels contrôles sont considérés invalides si l'évènement n'est pas annulé. C'est au développeur de choisir comment réagir face à la valeur false produite par cette méthode.
HTMLFormElement.reportValidity()
Cette méthode renvoie true si les contrôles du formulaire respectent leurs contraintes de validation. Lorsque false est renvoyé, des évènements annulables invalid sont déclenchés pour chaque contrôle invalide et les problèmes de validation sont rapportés à l'utilisateur.
HTMLFormElement.requestAutocomplete()
Cette méthode déclence une interface native afin d'aider les utilisateurs remplir les champs pour lesquels la valeur nommée de remplissage automatique ne vaut pas off ou on. Le formulaire reçoit un évènement lorsque l'utilisateur a fini d'intéragir avec l'interface, l'événement sera autocomplete si les champs ont bien été remplis ou autocompleteerror s'il y a eu un problème. Cette méthode a été retirée de Chrome et Firefox — cf. bug 1270740 pour plus d'informations et les raisons associées.

Exemples

Création et envoi

Le fragment de code permet de créer un nouveau formulaire, de modifier certains de ces attributs puis de l'envoyer :

var f = document.createElement("form"); // On crée un formulaire
document.body.appendChild(f);           // On l'ajoute au corps du document
f.action = "/cgi-bin/some.cgi";         // On y ajoute des attributs action et method
f.method = "POST"
f.submit();                             // On appelle la méhtode submit pour l'envoyer

Extraction d'informations et définition d'attributs

<form name="formA" id="formA" action="/cgi-bin/test" method="POST">
 <p>Click "Info" for form details; "Set" to change settings.</p>
 <p>
  <input type="button" value="info" onclick="getFormInfo();">
  <input type="button" value="set"  onclick="setFormInfo(this.form);">
  <input type="reset" value="reset"><br>
  <textarea id="tex" style="height:15em; width:20em"></textarea>
 </p>
</form>

<script type="text/javascript">
  function getFormInfo(){
    var info;
    var f = document.forms["formA"]; //Get a reference to the form via id.
    info = "elements: " + f.elements     + "\n"
         + "length: "   + f.length       + "\n"
         + "name: "     + f.name         + "\n"
         + "charset: "  + f.acceptCharset+ "\n"
         + "action: "   + f.action       + "\n"
         + "enctype: "  + f.enctype      + "\n"
         + "encoding: " + f.encoding     + "\n"
         + "method: "   + f.method       + "\n"
         + "target: "   + f.target;
    document.forms["formA"].elements['tex'].value = info;
  }
  function setFormInfo(f){ //Argument is a reference to the form.
    f.method = "GET";
    f.action = "/cgi-bin/evil_executable.cgi";
    f.name   = "totally_new";
  }
</script>

Envoyer un formulaire via une popup

<!doctype html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>MDN Example</title>
<script type="text/javascript">
function popupSend (oFormElement) {
  if (oFormElement.method && oFormElement.method.toLowerCase() !== "get") {
    console.error("This script supports the GET method only.");
    return;
  }
  var oField, sFieldType, nFile, sSearch = "";
  for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) {
    oField = oFormElement.elements[nItem];
    if (!oField.hasAttribute("name")) { continue; }
    sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT";
    if (sFieldType === "FILE") {
      for (nFile = 0; nFile < oField.files.length; sSearch += "&" + escape(oField.name) + "=" + escape(oField.files[nFile++].name));
    } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) {
      sSearch += "&" + escape(oField.name) + "=" + escape(oField.value);
    }
  }
  open(oFormElement.action.replace(/(?:\?.*)?$/, sSearch.replace(/^&/, "?")), "submit-" + (oFormElement.name || Math.floor(Math.random() * 1e6)), "resizable=yes,scrollbars=yes,status=yes");
}
</script>

</head>
 
<body>

<form name="yourForm" action="test.php" method="get" onsubmit="popupSend(this); return false;">
  <p>First name: <input type="text" name="firstname" /><br />
  Last name: <input type="text" name="lastname" /><br />
  Password: <input type="password" name="pwd" /><br />
  <input type="radio" name="sex" value="male" /> Male <input type="radio" name="sex" value="female" /> Female</p>
  <p><input type="checkbox" name="vehicle" value="Bike" />I have a bike<br />
  <input type="checkbox" name="vehicle" value="Car" />I have a car</p>
  <p><input type="submit" value="Submit" /></p>
</form>

</body>
</html>

Envoyer des formulaires et des fichiers via XMLHttpRequest

Vous pouvez consulter ce paragraphe si vous souhaitez en savoir plus pour sérialiser et envoyer un formulaire grâce à l'API XMLHttpRequest.

Spécifications

Spécification État Commentaires
HTML Living Standard
La définition de 'HTMLFormElement' dans cette spécification.
Standard évolutif Ajout de la méthode requestAutocomplete().
HTML5
La définition de 'HTMLFormElement' dans cette spécification.
Recommendation Les propriétés de l'élément renvoient un élément HTMLFormControlsCollection plutôt qu'un HTMLCollection (changement principalement technique). Ajout de la méthode checkValidity(). Ajout des propriétés autocomplete, noValidate et encoding.
Document Object Model (DOM) Level 2 HTML Specification
La définition de 'HTMLFormElement' dans cette spécification.
Obsolete Aucune modification.
Document Object Model (DOM) Level 1 Specification
La définition de 'HTMLFormElement' dans cette spécification.
Obsolete Définition initiale.

Compatibilité des navigateurs

Nous convertissons les données de compatibilité dans un format JSON. Ce tableau de compatibilité utilise encore l'ancien format car nous n'avons pas encore converti les données qu'il contient. Vous pouvez nous aider en contribuant !

Fonctionnalité Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support simple (Oui) (Oui) 1.0 (1.7 ou moins)[1] (Oui) (Oui) (Oui)
Fonctionnalité Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Support simple (Oui) (Oui) 1.0 (1.0)[1] (Oui) (Oui) (Oui)

[1] Pour Firefox 56, l'implémentation a été mise à jour afin que la propriété action renvoie l'URL d'envoi correcte telle qu'indiqué dans la spécification, cf. bug 1366361.

Voir aussi

  • L'élément HTML qui implémente cette interface <form>.

Étiquettes et contributeurs liés au document

Étiquettes : 
 Contributeurs à cette page : SphinxKnight, teoli, khalid32, Mgjbot, BenoitL, Fredchat
 Dernière mise à jour par : SphinxKnight,