HTMLInputElement

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, ou sentences.

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'attribut list. Cette propriété peut valoir null 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 attributs min et max pour limiter l'incrément d'une valeur numérique ou temporelle. Elle peut être la chaîne de caractères any ou un nombre décimal positif. Si la valeur n'est pas any, 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 de type 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, ou null 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, ou NaN 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'attribut action 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'attribut enctype 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'attribut method 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'attribut novalidate 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'attribut target 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'attribut autofocus.

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 aussi readonly.

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 vaut false), ou s'il respecte les contraintes. Cette valeur peut être définie avec la méthode setCustomValidity().

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'attribut type qui vaut hidden, reset, ou button, 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 objets File 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 vaut true, 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'attribut min.

maxLength

Une valeur numérique de type unsigned long qui permet de lire ou d'écrire l'attribut maxlength 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'attribut max.

minLength

Une valeur numérique de type unsigned long qui permet de lire ou d'écrire l'attribut maxlength 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'attribut title afin de décrire le motif à respecter. Cet attribut s'applique uniquement lorsque l'attribut type vaut text, search, tel, url, ou email.

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'attribut type vaut text, search, tel, url, ou email.

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'attribut type vaut hidden, range, color, checkbox, radio, file, ou button.

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é), ou none (la direction est inconnue).

size

Une valeur numérique de type unsigned long qui permet de lire ou d'écrire l'attribut size de l'élément, qui contient la taille visuelle du contrôle. La valeur est exprimée en pixels à moins que type vaille text ou password, auquel cas il s'agit du nombre de caractères. Cet attribut s'applique uniquement lorsque l'attribut type vaut text, search, tel, url, email, ou password.

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ènement invalid est également déclenché sur l'élément. Cette méthode renvoie true 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 renvoie false (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 :

• Elle n'est pas applicable pour un champ qui a cet attribut type,
• L'élément n'a pas de valeur pour l'attribut step,
• Si l'attribut value 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'attribut value 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 attribut type,
• L'élément n'a pas de valeur pour l'attribut step,
• Si l'attribut value 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é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'interface HTMLElement et s'applique également aux éléments qui ont l'attribut contenteditable. 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 a type="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

Compatibilité des navigateurs

Voir aussi

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