L'interfaceHTMLInputElement 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.

alignObsolète

Une chaîne de caractères qui représente l'alignement de l'élément.On utilisera CSS à la place.

autocapitalizeExpérimental

Une chaîne de caractères qui définit le comportement à suivre pour mettre en capitales la valeur saisie. Les valeurs valides sontnone,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.

labelsLecture seule

Un tableauNodeList contenant une liste des éléments<label> utilisés comme libellés pour cet élément.

listLecture seule

Un objetHTMLElement 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'attributmultiple 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'attributname 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'attributstep 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'écriretype 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.

useMapObsolè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 objetDate 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ériquedouble 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

formLecture seule

Un objetHTMLFormElement correspondant à l'élément<form> parent.

formAction

Une chaîne de caractères qui permet de lire ou d'écrire l'attributformaction 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'attributformenctype 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'attributformmethod 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'attributformnovalidate 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'attributformtarget 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'attributautofocus 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'attributdisabled 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'attributrequired de l'élément, qui indique que le champ doit être renseigné avant de pouvoir envoyer le formulaire.

validationMessageLecture 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 siwillValidate vautfalse), ou s'il respecte les contraintes. Cette valeur peut être définie avec la méthodesetCustomValidity().

validityLecture seule

Renvoie un objetValidityState qui traduit l'état de validité courant de l'élément.

willValidateLecture seule

Un booléen qui indique si l'élément participe à la validation des contraintes. Il vautfalse 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'attributdefault.

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'attributchecked, 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'attributalt 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'attributheight 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'attributsrc 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'attributwidth 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'attributaccept de l'élément, qui contient une liste de types de fichier, séparés par des virgules, qu'on peut sélectionner.

allowdirsNon 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-standardDirectory Upload et est uniquement implémentée dans Firefox et accessible via une préférence.

files

Un objetFileList qui permet de manipuler la liste des objetsFile qui représente les fichiers sélectionnés pour l'upload.

webkitdirectoryNon standard

Un booléen qui renvoie la valeur de l'attributwebkitdirectory 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).

webkitEntriesNon standard

Un tableauFileSystemEntry 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'attributautocomplete 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'attributmax 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 typeunsigned 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'attributmin 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 typeunsigned 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'attributpattern 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'attributplaceholder 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'attributreadonly 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 typeunsigned 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 typeunsigned 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 typeunsigned 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 vautfalse 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éthodecheckValidity() 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'attributvalue de (step * n), où n vaut 1 par défaut. Cette méthode déclenche une exception si :

• Elle n'est pas applicable pour un champ qui a cet attributtype,
• L'élément n'a pas de valeur pour l'attributstep,
• Si l'attributvalue ne peut pas être converti en nombre,
• Si la valeur résultante est supérieure àmax ou inférieure àmin.

stepUp()

Incrémente la valeur de l'attributvalue de (step * n), où n vaut 1 par défaut. Cette méthode déclenche une exception si :

• Elle n'est pas applicable pour un champ qui a cet attributtype,
• L'élément n'a pas de valeur pour l'attributstep,
• Si l'attributvalue ne peut pas être converti en nombre,
• Si la valeur résultante est supérieure àmax ou inférieure àmin.

Évènements

Pour écouter ces évènements, on utilisera la méthodeaddEventListener() 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.

selectionchangeExpérimental

Déclenché lorsque la sélection du texte à l'intérieur d'un élément<input> a changé.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'élément HMTL qui porte cette interface,<input>