L'interfaceHTMLFormElement représente un élément HTML<form> du DOM. Elle permet d'accéder — et, dans certains cas, de modifier — certains aspects du formulaire, ainsi que d'accéder à ses éléments composants.

Propriétés d'instance

Cette interface hérite aussi des propriétés de son parentHTMLElement.

HTMLFormElement.acceptCharset

Une chaîne de caractères reflétant la valeur de l'attribut HTMLaccept-charset de ce formulaire.

HTMLFormElement.action

Une chaîne de caractères reflétant la valeur de l'attribut HTMLaction de ce formulaire, contenant l'URI d'un programme qui traite les informations soumises par le formulaire.

HTMLFormElement.autocomplete

Une chaîne de caractères reflétant la valeur de l'attribut HTMLautocomplete de ce formulaire, indiquant si les contrôles de ce formulaire peuvent voir leurs valeurs renseignées automatiquement par le navigateur.

HTMLFormElement.encoding ouHTMLFormElement.enctype

Une chaîne de caractères reflétant la valeur de l'attribut HTMLenctype de ce formulaire, indiquant le type de contenu utilisé pour transmettre le formulaire au serveur. Seules des valeurs définies peuvent être utilisées. Les deux propriétés sont synonymes.

HTMLFormElement.elementsLecture seule

Un objetHTMLFormControlsCollection regroupant tous les contrôles de formulaire appartenant à cet élément de formulaire.

HTMLFormElement.lengthLecture seule

Un nombrelong reflétant le nombre de contrôles dans le formulaire.

HTMLFormElement.name

Une chaîne de caractères reflétant la valeur de l'attribut HTMLname du formulaire, contenant le nom du formulaire.

HTMLFormElement.noValidate

Une valeur booléenne reflétant la valeur de l'attribut HTMLnovalidate de ce formulaire, indiquant si le formulaire ne doit pas être validé.

HTMLFormElement.method

Une chaîne de caractères reflétant la valeur de l'attribut HTMLmethod du formulaire, indiquant la méthode HTTP utilisée pour soumettre le formulaire. Seules des valeurs définies peuvent être utilisées.

HTMLFormElement.rel

Une chaîne de caractères reflétant la valeur de l'attribut HTMLrel du formulaire, indiquant les types de liens que le formulaire crée, sous forme d'une liste de valeurs séparées par des espaces.

HTMLFormElement.relListLecture seule

Un objetDOMTokenList reflétant l'attribut HTMLrel sous la forme d'une liste de jetons.

HTMLFormElement.target

Une chaîne de caractères reflétant la valeur de l'attribut HTMLtarget du formulaire, indiquant où afficher les résultats reçus lors de l'envoi du formulaire.

Les champs nommés sont ajoutés à leur instance de formulaire propriétaire en tant que propriétés et peuvent écraser les propriétés natives si elles portent le même nom (par exemple, un formulaire avec une entrée nomméeaction verra sa propriétéaction retourner cette entrée plutôt que la valeur de l'attribut HTMLaction).

Méthodes d'instance

Cette interface hérite aussi des méthodes de son parentHTMLElement.

checkValidity()

Retournetrue si les contrôles enfants de l'élément sont soumis à lavalidation des contraintes et respectent ces contraintes ; retournefalse si certains contrôles ne les respectent pas. Pour chaque contrôle invalide, un évènement annulableinvalid est déclenché ; ces contrôles sont considérés invalides si l'évènement n'est pas annulé. C'est au développeur·euse de décider de la conduite à tenir lorsque la méthode retournefalse.

reportValidity()

Retournetrue si les contrôles enfants de l'élément respectent leurs contraintes de validation. Lorsquefalse est retourné, des évènements annulablesinvalid sont déclenchés pour chaque contrôle invalide et les problèmes de validation sont signalés à l'utilisateur·ice.

requestSubmit()

Demande que le formulaire soit soumis en utilisant le bouton d'envoi indiqué et sa configuration associée.

reset()

Redéfinit le formulaire à son état initial.

submit()

Soumet le formulaire au serveur.

Évènements

Écoutez ces évènements en utilisantaddEventListener(), ou en assignant un écouteur d'événement à la propriétéoneventname de cette interface.

formdata

L'évènementformdata est déclenché après la construction de la liste d'entrées représentant les données du formulaire.

reset

L'évènementreset est déclenché lorsque le formulaire est réinitialisé.

submit

L'évènementsubmit est déclenché lorsque le formulaire est soumis.

Notes d'utilisation

Obtention d'un objet élément de formulaire

Pour obtenir un objetHTMLFormElement, vous pouvez utiliser unsélecteur CSS avecquerySelector() ou vous pouvez obtenir une liste de tous les formulaires du document utilisant sa propriétéforms.

Document.forms retourne un tableau des objetsHTMLFormElement listant chacun des formulaires de la page. Vous pouvez utiliser alors l'une des syntaxes suivantes pour obtenir un formulaire individuel :

document.forms[index]

retourne le formulaire à l'index défini dans le tableau du formulaire.

document.forms[id]

retourne le formulaire dont l'ID (identifiant) estid .

document.forms[name]

retourne le formulaire dont la valeur d'attribut dename estname.

Accès aux éléments du formulaire

Vous pouvez accéder à la liste des éléments contenant des données du formulaire en examinant la propriétéelements du formulaire. Celle-ci retourne unHTMLFormControlsCollection listant tous les éléments d'entrée de données utilisateur·ice du formulaire, aussi bien ceux qui sont des descendants du<form> que ceux qui sont déclarés membres du formulaire via leur attributform.

Vous pouvez aussi obtenir un élément du formulaire en utilisant son attributname comme clé duform, mais utiliserelements est une meilleure approche — il contientseulement les éléments du formulaire et ne peut pas être confondu avec d'autres attributs duform.

Problèmes liés au nommage des éléments

Certains noms peuvent interférer avec l'accès en JavaScript aux propriétés et aux éléments du formulaire.

Par exemple :

• <input name="id"> prendra le pas sur<form>. Cela signifie queform.id ne fera pas référence à l'identifiant du formulaire, mais à l'élément dont le nom est"id". Cela vaut pour toute autre propriété de formulaire, comme<input name="action"> ou<input name="post">.
• <input name="elements"> rendra la collectionelements du formulaire inaccessible. La référenceform.elements renverra désormais à l'élément individuel.

Pour éviter de tels problèmes liés aux noms d'éléments :

• Utilisez toujours la collectionelements pour éviter toute ambiguïté entre le nom d'un élément et une propriété du formulaire.
• Ne jamais utiliser"elements" comme nom d'élément.

Si vous n'utilisez pas JavaScript, cela ne posera pas de problème.

Éléments considérés comme des contrôles de formulaire

Les éléments qui sont inclus parHTMLFormElement.elements etHTMLFormElement.length sont :

• <button> (bouton)
• <fieldset> (_champ_s)
• <input> (entrée) (à l'exception de ceux donttype est"image" omis pour des raisons historiques)
• <object> (objet)
• <output> (sortie)
• <select> (sélection)
• <textarea> (zone de texte)

Aucun autre élément n'est inclus dans la liste retournée parelements, ce qui en fait un excellent moyen d'accéder aux éléments les plus importants lors du traitement des formulaires.

Exemples

Crée un nouvel élément de formulaire, modifie ses attributs et l'envoie :

const f = document.createElement("form"); // Crée un formulairedocument.body.appendChild(f); // L'ajoute au corps du documentf.action = "/cgi-bin/some.cgi"; // Ajoute les attributs action et methodf.method = "POST";f.submit(); // Appelle la méthode submit() du formulaire

Extraire des informations d'un élément<form> et définir certains de ses attributs :

<form name="formA" action="/cgi-bin/test" method="post">  <p>    Appuyez sur «&nbsp;Info&nbsp;» pour les détails du formulaire, ou sur    «&nbsp;Définir&nbsp;» pour les modifier.  </p>  <p>    <button type="button">Info</button>    <button type="button">Définir</button>    <button type="reset">Réinitialiser</button>  </p>  <textarea rows="15" cols="20"></textarea></form>

document.getElementById("info").addEventListener("click", () => {  // Récupère une référence au formulaire via son nom  const f = document.forms["formA"];  // Les propriétés du formulaire qui nous intéressent  const properties = [    "elements",    "length",    "name",    "charset",    "action",    "acceptCharset",    "action",    "enctype",    "method",    "target",  ];  // Parcourt les propriétés et les transforme en une chaîne de caractères pour affichage  const info = properties    .map((property) => `${property}: ${f[property]}`)    .join("\n");  // Remplit le <textarea> du formulaire avec les propriétés  document.forms["formA"].elements["form-info"].value = info; // document.forms["formA"]['form-info'].value fonctionnerait aussi});document.getElementById("set-info").addEventListener("click", (e) => {  // Récupère une référence au formulaire via la cible de l'événement  // e.target est le bouton, et .form est le formulaire auquel il appartient  const f = e.target.form;  // L'argument doit être une référence à un élément de formulaire.  f.action = "a-different-url.cgi";  f.name = "a-different-name";});

Envoi d'un formulaire dans une nouvelle fenêtre :

<form action="test.php">  <p>    <label>Prénom&nbsp;: <input type="text" name="first-name" /></label>  </p>  <p>    <label>Nom&nbsp;: <input type="text" name="last-name" /></label>  </p>  <p>    <label><input type="password" name="pwd" /></label>  </p>  <fieldset>    <legend>Animal préféré</legend>    <p>      <label><input type="radio" name="pet" value="cat" /> Chat</label>    </p>    <p>      <label><input type="radio" name="pet" value="dog" /> Chien</label>    </p>  </fieldset>  <fieldset>    <legend>Véhicules possédés</legend>    <p>      <label        ><input type="checkbox" name="vehicle" value="Bike" />J'ai un        vélo</label      >    </p>    <p>      <label        ><input type="checkbox" name="vehicle" value="Car" />J'ai une        voiture</label      >    </p>  </fieldset>  <p><button>Envoyer</button></p></form>

Spécifications

Compatibilité des navigateurs

Voir aussi

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