HTMLInputElement
================

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>`.

EventTarget

Node

Element

HTMLElement

HTMLInputElementProprié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` (en-US)

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` (en-US)

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()` (en-US).

`validity` Lecture seule 

Renvoie un objet `ValidityState` (en-US) 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` (en-US)

Un objet `FileList` qui permet de manipuler la liste des objets `File` qui représente les fichiers sélectionnés pour l'*upload*.

`webkitdirectory` (en-US) 
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` (en-US) 
Non-standard

Un tableau `FileSystemEntry` (en-US) 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()` (en-US)

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()` (en-US)

Sélectionne un intervalle de texte de l'élément (mais ne lui donne pas le focus).

`setRangeText()` (en-US)

Remplace un intervalle de texte de l'élément avec un nouveau texte.

`setCustomValidity()` (en-US)

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()` (en-US)

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` (en-US) 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()` (en-US)

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()` (en-US)

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()` (en-US)

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` (en-US).

`invalid` (en-US)

Déclenché lorsqu'un élément ne respecte pas les contraintes lors de la validation des contraintes. Également disponible via la propriété `oninvalid` (en-US).

`search` (en-US)

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` (en-US) 
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 with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

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