form
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
L'interface HTMLFormElement
représente un élément <form>
dans le DOM ; il peut être utilisé pour accéder et, dans quelques cas, modifier l'aspect du formulaire, ainsi que pour accéder à ses éléments composants.
Propriétés
Cette interface hérite aussi des propriétés de son parent HTMLElement
.
HTMLFormElement.elements
Lecture seule-
Un élément
HTMLFormControlsCollection
regroupant les différents contrôles associés à ce formulaire. HTMLFormElement.length
Lecture 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 HTMLname
pour ce formulaire et qui correspond au nom du formulaire. HTMLFormElement.method
-
Une chaîne
DOMString
indiquant la valeur de l'attribut HTMLmethod
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 HTMLtarget
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 HTMLaction
pour ce formulaire et qui contient l'URI d'un programme traitant les informations transmises via le formulaire. HTMLFormElement.encoding
ouHTMLFormElement.enctype
-
Une chaîne
DOMString
indiquant la valeur de l'attribut HTMLenctype
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 HTMLaccept-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 HTMLautocomplete
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 aussi des méthodes de son parent HTMLElement
.
HTMLFormElement.submit()
-
soumet le formulaire au serveur.
HTMLFormElement.reset()
-
redéfinit le formulaire à son état initial.
HTMLFormElement.checkValidity()
-
renvoie
true
si les contrôles du formulaire sont soumis à des contraintes de validation et les respectent. Elle renvoiefalse
si certains contrôles ne respectent pas leurs contraintes. Elle déclenche un évènementinvalid
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 valeurfalse
produite par cette méthode. HTMLFormElement.reportValidity()
-
renvoie
true
si les contrôles du formulaire respectent leurs contraintes de validation. Lorsquefalse
est renvoyé, des évènements annulablesinvalid
sont déclenchés pour chaque contrôle invalide et les problèmes de validation sont rapportés à l'utilisateur.
Notes d'utilisation
Obtention d'un objet élément de formulaire
Pour obtenir un objet HTMLFormElement
, vous pouvez utiliser un sélecteur CSS avec querySelector()
ou vous pouvez obtenir une liste de tous les formulaires du document utilisant sa propriété forms
.
Document.forms
renvoie un tableau des objets HTMLFormElement
listant chacun des formulaires de la page. Vous pouvez utiliser alors l'une des syntaxes suivantes pour obtenir un formulaire individuel :
document.forms[index]
-
renvoie le formulaire à l'
index
spécifié dans le tableau du formulaire. document.forms[id]
-
renvoie le formulaire dont l'ID (identifiant) est
id
. document.forms[name]
-
renvoie le formulaire dont la valeur d'attribut de
name
estname
.
Accès aux éléments du formulaire
Vous pouvez accéder à la liste des éléments contenant des données dans le formulaire en examinant la propriété elements
. Ceci retourne une HTMLFormControlsCollection
listant tous les éléments d'entrée de données utilisateur du formulaire, aussi bien ceux qui sont des descendants du <form>
que ceux déclarés membres du formulaire par leurs attributs.
Éléments considérés comme des contrôles de formulaire
Les éléments qui sont inclus par HTMLFormElement.elements
et HTMLFormElement.length
sont :
<button>
(bouton)<fieldset>
(champs)<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)
Exemples
Crée un nouvel élément de formulaire, modifie ses attributs et l'envoie :
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
Extrait des informations d'un élément de formulaire et définit quelques uns de ses attributs :
<form name="formA" action="/cgi-bin/test" method="post">
<p>
Appuyez sur "Info" pour les détails du formulaire, ou "Définir" pour
modifier ces détails.
</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() {
// Obtenir une référence au formulaire par son nom
var f = document.forms["formA"];
// Les propriétés du formulaire qui nous intéressent
var properties = [
"elements",
"length",
"name",
"charset",
"action",
"acceptCharset",
"action",
"enctype",
"method",
"target",
];
// Itérer sur les propriétés en les transformant en une chaîne que nous pouvons afficher à l'utilisateur
var info = properties
.reduce(function (property) {
return property + ": " + f[property];
}, "")
.join("\n");
// Définir les <textarea> du formulaire pour en afficher les propriétés
document.forms["formA"].elements["form-info"].value = info;
}
function setFormInfo(f) {
//L'argument doit être une référence d'élément de formulaire.
f.action = "a-different-url.cgi";
f.name = "a-different-name";
}
</script>
Envoi d'un formulaire dans une nouvelle fenêtre :
<!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>
Envoi de formulaires et téléchargement de fichiers en utilisant 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
Specification |
---|
HTML Standard # htmlformelement |
Compatibilité des navigateurs
BCD tables only load in the browser
Voir aussi
- L'élément HTML qui implémente cette interface
<form>
.