HTMLInputElement
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 HTMLInputElement
fournit les propriétés et les méthodes pour manipuler les options, la disposition et la présentation des éléments <input>
.
Propriétés
Certaines propriétés ne s'appliquent qu'aux types d'éléments <input>
qui prennent en charge les attributs correspondants.
align
Obsolète-
Une chaîne de caractères qui représente l'alignement de l'élément. On utilisera CSS à la place.
autocapitalize
Expérimental-
Une chaîne de caractères qui définit le comportement à suivre pour mettre en capitales la valeur saisie. Les valeurs valides sont
none
,off
,characters
,words
, ousentences
. defaultValue
-
Une chaîne de caractères qui permet de lire ou d'écrire la valeur par défaut telle qu'originellement indiquée dans le HTML à l'origine de cet objet.
dirName
-
Une chaîne de caractères qui permet de lire ou d'écrire le sens d'écriture de l'élément.
inputmode
-
Fournit une indication au navigateur quant à la configuration de clavier virtuel à utiliser lors de l'édition de cet élément ou de son contenu.
labels
Lecture seule-
Un tableau
NodeList
contenant une liste des éléments<label>
utilisés comme libellés pour cet élément. list
Lecture seule-
Un objet
HTMLElement
qui correspond à l'élément ciblé par l'attributlist
. Cette propriété peut valoirnull
si aucun élément HTML n'a été trouvé dans le même arbre. multiple
-
Un booléen qui permet de lire ou d'écrire l'attribut
multiple
de l'élément qui indique que plusieurs valeurs sont possibles (par exemple pour sélectionner plusieurs fichiers). name
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
name
de l'élément qui indique le nom identifiant l'élément lors de l'envoi du formulaire. step
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
step
de l'élément. Cet attribut fonctionne avec les attributsmin
etmax
pour limiter l'incrément d'une valeur numérique ou temporelle. Elle peut être la chaîne de caractèresany
ou un nombre décimal positif. Si la valeur n'est pasany
, le contrôle acceptera uniquement les multiples de l'incrément depuis la valeur minimale. type
-
Une chaîne de caractères qui permet de lire ou d'écrire
type
de l'élément qui indique le type de contrôle à afficher. Voir la documentation detype
pour l'élément<input>
pour les valeurs possibles. useMap
Obsolète-
Une chaîne de caractères qui représente une carte d'images côté client.
value
-
Une chaîne de caractères qui permet de lire ou d'écrire la valeur contenue dans le contrôle. Si l'utilisatrice ou l'utilisateur saisit une valeur différente de la valeur attendue, cette propriété pourra renvoyer une chaîne vide.
valueAsDate
-
Un objet
Date
qui permet de lire ou d'écrire la valeur de l'élément interprétée comme une date, ounull
si la conversion n'est pas possible. valueAsNumber
-
Une valeur numérique
double
qui renvoie la valeur de l'élément interprété dans l'ordre comme : une valeur temporelle, un nombre, ouNaN
si la conversion est impossible
Propriétés relatives au formulaire parent
form
Lecture seule-
Un objet
HTMLFormElement
correspondant à l'élément<form>
parent. formAction
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
formaction
de l'élément, qui contient l'URI d'un programme traitant les informations envoyées avec l'élément. Cet attribut HTML surcharge l'attributaction
du formulaire parent. formEnctype
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
formenctype
de l'élément, qui contient le type de contenu utilisé pour envoyer le formulaire au serveur. Cet attribut HTML surcharge l'attributenctype
du formulaire parent. formMethod
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
formmethod
de l'élément, qui contient la méthode HTTP utilisée par le navigateur pour envoyer le formulaire. Cet attribut HTML surcharge l'attributmethod
du formulaire parent. formNoValidate
-
Un booléen qui permet de lire ou d'écrire l'attribut
formnovalidate
de l'élément, qui indique que le formulaire n'a pas à être validé lors de l'envoi. Cet attribut HTML surcharge l'attributnovalidate
du formulaire parent. formTarget
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
formtarget
de l'élément, qui contient un nom ou un mot-clé indiquant où afficher la réponse reçue après l'envoi du formulaire. Cet attribut HTML surcharge l'attributtarget
du formulaire parent.
Propriétés qui s'appliquent à tous les éléments <input>
qui ne sont pas masqués
autofocus
-
Un booléen qui permet de lire ou d'écrire l'attribut
autofocus
de l'élément, qui indique qu'un contrôle de formulaire devrait recevoir le focus au chargement de la page, à moins que la personne ait déjà sélectionné un autre contrôle. Seul un élément de formulaire d'un document peut avoir l'attributautofocus
. disabled
-
Un booléen qui permet de lire ou d'écrire l'attribut
disabled
de l'élément, qui indique qu'on ne peut pas interagir avec le contrôle. La valeur du champ ne sera pas envoyée avec le formulaire. Voir aussireadonly
. required
-
Un booléen qui permet de lire ou d'écrire l'attribut
required
de l'élément, qui indique que le champ doit être renseigné avant de pouvoir envoyer le formulaire. validationMessage
Lecture seule-
Une chaîne de caractères qui renvoie un message localisé qui décrit les éventuelles contraintes de validation qu'il doit respecter. Cette propriété aura la chaîne vide comme valeur si le contrôle ne participe pas à la validation des contraintes (c'est-à-dire si
willValidate
vautfalse
), ou s'il respecte les contraintes. Cette valeur peut être définie avec la méthodesetCustomValidity()
. validity
Lecture seule-
Renvoie un objet
ValidityState
qui traduit l'état de validité courant de l'élément. willValidate
Lecture seule-
Un booléen qui indique si l'élément participe à la validation des contraintes. Il vaut
false
si au moins une condition empêche la validation de contrainte, incluant : l'attributtype
qui vauthidden
,reset
, oubutton
, la présence d'un ancêtre<datalist>
, ou la propriétédisabled
àtrue
.
Propriétés pour <input type="checkbox">
et <input type="radio">
checked
-
Un booleén qui permet de lire ou d'écrire l'état actuel de l'élément.
defaultChecked
-
Un booléen qui permet de lire ou d'écrire l'état par défaut du bouton radio ou de la case à cocher, tel qu'initialement indiqué en HTML par l'attribut
default
. indeterminate
-
Un booléen qui indique si la case à cocher ou le bouton radio est dans un état indéterminé. Pour les cases à cocher, cela se traduit par une case grisée d'une certaine façon (la case n'est ni cochée ni décochée). Cette propriété n'affecte pas la valeur de l'attribut
checked
, et cliquer sur la case à cocher la passera àfalse
(décochée).
Propriétés pour <input type="image">
alt
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
alt
de l'élément, qui contient le texte alternatif à utiliser à la place de l'image. height
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
height
de l'élément, qui définit la hauteur de l'image affichée sur le bouton. src
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
src
de l'élément, qui définit l'URI d'un emplacement d'image à afficher sur le bouton graphique. width
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
width
de l'élément, qui définit la largeur de l'image affichée sur le bouton.
Propriétés pour <input type="file">
accept
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
accept
de l'élément, qui contient une liste de types de fichier, séparés par des virgules, qu'on peut sélectionner. allowdirs
Non standard-
Un booléen qui indique si des répertoires peuvent être sélectionnés via le sélecteur de fichier. Fait partie de l'API non-standard Directory Upload et est uniquement implémentée dans Firefox et accessible via une préférence.
files
-
Un objet
FileList
qui permet de manipuler la liste des objetsFile
qui représente les fichiers sélectionnés pour l'upload. webkitdirectory
Non standard-
Un booléen qui renvoie la valeur de l'attribut
webkitdirectory
de l'élément. S'il vauttrue
, cela indique que l'interface du sélecteur de fichier n'acceptera que les répertoires (plutôt que les fichiers). webkitEntries
Non standard-
Un tableau
FileSystemEntry
qui décrit les fichiers ou répertoires actuellement sélectionnés.
Propriétés qui s'appliquent aux éléments visibles contenant du texte ou des nombres
autocomplete
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
autocomplete
de l'élément, qui indique si la valeur du contrôle peut être automatiquement complétée par le navigateur. max
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
max
de l'élément, qui contient la valeur maximale (numérique ou temporelle) de la valeur pour ce champ. Cette valeur ne doit pas être inférieure à la valeur minimale portée par l'attributmin
. maxLength
-
Une valeur numérique de type
unsigned long
qui permet de lire ou d'écrire l'attributmaxlength
de l'élément, qui contient le nombre maximal de caractères (exprimés en codets Unicode) que doit contenir la valeur. min
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
min
de l'élément, qui contient la valeur minimale (numérique ou temporelle) de la valeur pour ce champ. Cette valeur ne doit pas être supérieure à la valeur maximale portée par l'attributmax
. minLength
-
Une valeur numérique de type
unsigned long
qui permet de lire ou d'écrire l'attributmaxlength
de l'élément, qui contient le nombre minimal de caractères (exprimés en codets Unicode) que doit contenir la valeur. pattern
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
pattern
de l'élément, qui contient une expression rationnelle contre laquelle la valeur du contrôle est testée. On utilisera l'attributtitle
afin de décrire le motif à respecter. Cet attribut s'applique uniquement lorsque l'attributtype
vauttext
,search
,tel
,url
, ouemail
. placeholder
-
Une chaîne de caractères qui permet de lire ou d'écrire l'attribut
placeholder
de l'élément, qui contient une indication fournie à l'utilisatrice ou à l'utilisateur quant à ce qui peut être saisi dans le contrôle. Le texte d'indication ne doit pas contenir de retour chariot ou de passage à la ligne. Cet attribut s'applique uniquement lorsque l'attributtype
vauttext
,search
,tel
,url
, ouemail
. readOnly
-
Un booléen qui permet de lire ou d'écrire l'attribut
readonly
de l'élément, qui indique qu'il n'est pas possible de modifier la valeur du contrôle. Cet attribut est ignoré si l'attributtype
vauthidden
,range
,color
,checkbox
,radio
,file
, oubutton
. selectionEnd
-
Une valeur numérique de type
unsigned long
qui permet de lire ou d'écrire l'indice de fin pour le texte sélectionné. Lorsqu'il n'y a aucune sélection, cette propriété renvoie le décalage du caractère qui suit immédiatement le curseur pour le champ texte actuel. selectionStart
-
Une valeur numérique de type
unsigned long
qui permet de lire ou d'écrire l'indice de début pour le text sélectionné. Lorsqu'il n'y a aucune sélection, cette propriété renvoie la position du curseur de saisie à l'intérieur de l'élément<input>
. selectionDirection
-
Une chaîne de caractères qui permet de lire ou d'écrire la direction selon laquelle la sélection est effectuée. Les valeurs possibles sont :
forward
(la sélection a été effectuée dans le sens d'écriture de la locale courante),backward
(le sens opposé), ounone
(la direction est inconnue). size
-
Une valeur numérique de type
unsigned long
qui permet de lire ou d'écrire l'attributsize
de l'élément, qui contient la taille visuelle du contrôle. La valeur est exprimée en pixels à moins quetype
vailletext
oupassword
, auquel cas il s'agit du nombre de caractères. Cet attribut s'applique uniquement lorsque l'attributtype
vauttext
,search
,tel
,url
,email
, oupassword
.
Méthodes
blur()
-
Retire le focus de l'élément, les saisies au clavier qui suivent seront perdues.
click()
-
Simule un clic sur l'élément
focus()
-
Passe le focus à l'élément, les saisies au clavier qui suivent s'appliqueront à cet élément.
select()
-
Sélectionne tout le texte de l'élément et lui donne le focus afin que l'utilisatrice ou l'utilisateur puisse remplacer le contenu.
setSelectionRange()
-
Sélectionne un intervalle de texte de l'élément (mais ne lui donne pas le focus).
setRangeText()
-
Remplace un intervalle de texte de l'élément avec un nouveau texte.
setCustomValidity()
-
Définit un message de validité spécifique pour l'élément. Si ce message n'est pas la chaîne vide, l'élément souffrira d'une erreur de validation spécifique et ne sera pas valide.
showPicker()
-
Affiche le sélecteur du navigateur pour une date, une heure, une couleur, ou des fichiers.
checkValidity()
-
Renvoie un booléen qui vaut
false
si l'élément est candidat à la validation des contraintes, mais qu'il ne les respecte pas toutes. Dans ce cas, un évènementinvalid
est également déclenché sur l'élément. Cette méthode renvoietrue
si l'élément ne participe pas à la validation des contraintes ou si les contraintes sont respectées. reportValidity()
-
Exécute la méthode
checkValidity()
et, si celle-ci renvoiefalse
(si un champ est invalide ou si aucun motif n'a été fourni), fourni la même indication à l'utilisatrice ou l'utilisateur, que celle affichée en cas de champ invalide lorsque le formulaire est envoyé. stepDown()
-
Décrémente la valeur de l'attribut
value
de (step
* n), où n vaut 1 par défaut. Cette méthode déclenche une exception si : stepUp()
-
Incrémente la valeur de l'attribut
value
de (step
* n), où n vaut 1 par défaut. Cette méthode déclenche une exception si :
Évènements
Pour écouter ces évènements, on utilisera la méthode addEventListener()
ou on affectera un gestionnaire d'évènements à la propriété onnomevenement
correspondante de cette interface :
input
-
Déclenché lorsque la valeur d'un élément
<input>
,<select>
, or<textarea>
a changé. On notera qu'à strictement parler, cet évènement est déclenché sur l'interfaceHTMLElement
et s'applique également aux éléments qui ont l'attributcontenteditable
. Toutefois, nous l'avons indiqué ici, car il est fréquemment utilisé avec les éléments de formulaire. Également disponible via la propriétéoninput
. invalid
-
Déclenché lorsqu'un élément ne respecte pas les contraintes lors de la validation des contraintes. Également disponible via la propriété
oninvalid
. search
-
Déclenché lorsqu'une recherche est initiée sur un élément
<input>
qui atype="search"
. Également disponible via la propriétéonsearch
. selectionchange
Expérimental-
Déclenché lorsque la sélection du texte à l'intérieur d'un élément
<input>
a changé.
Spécifications
Specification |
---|
HTML Standard # htmlinputelement |
Compatibilité des navigateurs
BCD tables only load in the browser
Voir aussi
- L'élément HMTL qui porte cette interface,
<input>