HTMLSelectElement

L'interface HTMLSelectElement représente un élément HTML <select>. Cet élément partage aussi toute les propriétés et méthodes des autres elements HTML via l'interface HTMLElement.

Propriétés

Cette interface hérite des propriétés de HTMLElement, de Element et de Node.

HTMLSelectElement.autofocus (en-US)
Un Boolean reflétant l'attribut HTML autofocus qui indique si le contrôle doit bénéficier d'une priorité d'entrée au chargement de la page, à moins que l'utilisateur ne passe outre, par exemple en saisissant un autre contrôle. Cet attribut ne peut être spécifié que pour un seul élément associé à un formulaire dans un document.
HTMLSelectElement.disabled (en-US)
Un Boolean reflétant l'attribut disabled qui indique si le contrôle est désactivé. S'il est désactivé, il n'accepte pas les clics.
HTMLSelectElement.form (en-US) Lecture seule
Un HTMLFormElement référençant le formulaire auquel cet élément est associé. Si l'élément n'est pas associé à un élément <form>, il retourne null.
HTMLSelectElement.labels (en-US) Lecture seule
Une NodeList d'éléments <label> associés à l'élément.
HTMLSelectElement.length
Un unsigned long, le nombre d'éléments <option> dans cet élément select.
HTMLSelectElement.multiple
Un Boolean reflétant l'attribut multiple qui indique si plusieurs éléments peuvent être sélectionnés.
HTMLSelectElement.name
Une chaîne de caratères DOMString reflétant l'attribut HTML name contenant le nom de ce contrôle utilisé par les serveurs et les fonctions de recherche DOM.
HTMLSelectElement.options (en-US) Lecture seule
Une HTMLOptionsCollection (en-US) représentant l'ensemble des <option> (HTMLOptionElement) contenus par cet élément.
HTMLSelectElement.required
Un Boolean reflétant l'attribut required qui indique si l'utilisateur doit sélectionner une valeur avant de soumettre le formulaire.
HTMLSelectElement.selectedIndex
Un long reflétant l'indice du premier élément <option> sélectionné. La valeur -1 indique qu'aucun élément n'est sélectionné.
HTMLSelectElement.selectedOptions (en-US) Lecture seule
Une HTMLCollection représentant l'ensemble des éléments <option> qui sont sélectionnés.
HTMLSelectElement.size
Un long reflétant l'attribut size attribut HTML, qui contient le nombre d'éléments visibles dans le contrôle. La valeur par défaut est 1, sauf si multiple est true, auquel cas elle est de 4.
HTMLSelectElement.type (en-US) Lecture seule
Une chaîne de caractères DOMString représentant le type du contrôle de formulaire. Lorsque multiple est true, il renvoie "select-multiple" ; sinon, il renvoie "select-one".
HTMLSelectElement.validationMessage Lecture seule
Une chaîne de caractères DOMString représentant un message localisé qui décrit les contraintes de validation que le contrôle ne satisfait pas (le cas échéant). Cet attribut est la chaîne vide si le contrôle n'est pas un candidat à la validation des contraintes (willValidate est faux), ou s'il satisfait à ses contraintes.
HTMLSelectElement.validity Lecture seule
Un ValidityState (en-US) reflétant l'état de validité dans lequel se trouve ce contrôle.
HTMLSelectElement.value
Une chapine de caractères DOMString reflétant la valeur du contrôle de formulaire. Renvoie la propriété value du premier élément d'option sélectionné s'il y en a un, sinon la chaîne vide.
HTMLSelectElement.willValidate Lecture seule
Un Boolean qui indique si le bouton est un candidat à la validation des contraintes. Il vaut false si des conditions l'empêchent de bénéficier de la validation par contrainte.

Méthodes

Cette interface hérite des méthodes de HTMLElement, et de Element et Node.

HTMLSelectElement.add() (en-US)
Ajoute un élément à la collection d'éléments option pour cet élément select.
HTMLSelectElement.blur() This is an obsolete API and is no longer guaranteed to work.
Supprime le focus d'entrée de cet élément. Cette méthode est maintenant mise en œuvre sur HTMLElement..
HTMLSelectElement.checkValidity() (en-US)
Vérifie si l'élément a des contraintes et s'il les satisfait. Si l'élément ne respecte pas ses contraintes, le navigateur déclenche un événement invalid (en-US) annulable sur l'élément (et retourne false).
HTMLSelectElement.focus() This is an obsolete API and is no longer guaranteed to work.
Donne le focus d'entrée à cet élément. Cette méthode est maintenant mise en œuvre sur HTMLElement.
HTMLSelectElement.item() (en-US)
Obtient un élément de la collection d'options de l'élément <select>. Vous pouvez également accéder à un élément en spécifiant l'index entre des parenthèses ou des crochets de style tableau, sans appeler cette méthode explicitement.
HTMLSelectElement.namedItem() (en-US)
Obtient l'élément dans la collection d'options avec le nom spécifié. La chaîne de nom peut correspondre soit au id, soit à l'attribut name d'un nœud d'option. Vous pouvez également accéder à un élément en spécifiant le nom entre des crochets de style tableau ou des parenthèses, sans appeler cette méthode explicitement.
HTMLSelectElement.remove()
Supprime l'élément à l'indice spécifié de la collection d'options pour cet élément select.
HTMLSelectElement.reportValidity()
Cette méthode signale à l'utilisateur les problèmes liés aux contraintes sur l'élément, le cas échéant. S'il y a des problèmes, elle déclenche un événement invalid (en-US) annulable sur l'élément, et retourne false ; s'il n'y a pas de problèmes, elle retourne true.
HTMLSelectElement.setCustomValidity()
Définit le message de validation personnalisé pour l'élément de sélection au message spécifié. Utilisez la chaîne vide pour indiquer que l'élément n'a pas d'erreur de validité personnalisée.

Événements

Écoutez ces événements en utilisant addEventListener() ou en affectant un écouteur d'événements à la propriété oneventname de cette interface :

Événement input
S'active lorsque la valeur d'un élément <input>, <select> ou <textarea> a été modifiée.

Exemple

Obtenir des informations sur l'option sélectionnée

/* en supposant que nous ayons le HTML suivant
<select id='s'>
    <option>Premier</option>
    <option selected>Deuxième</option>
    <option>Troisième</option>
</select>
*/

const select = document.getElementById('s');

// renvoie l'index de l'option sélectionnée
console.log(select.selectedIndex); // 1

// retourne la valeur de l'option sélectionnée
console.log(select.options[select.selectedIndex].value) // Deuxième

Une meilleure façon de suivre les modifications apportées à la sélection de l'utilisateur consiste à surveiller l'événement change qui se produit sur le <select>. Cela vous indiquera quand la valeur change, et vous pourrez alors mettre à jour ce dont vous avez besoin. Voir l'exemple fourni dans la documentation de l'événement change pour plus de détails.

Spécifications

Spécification Statut Commentaire
HTML Living Standard
La définition de 'HTMLSelectElement' dans cette spécification.
Standard évolutif Ajoute la propriété autocomplete et la méthode reportValidity().
HTML5
La définition de 'HTMLSelectElement' dans cette spécification.
Recommendation Ajoute les propriétés autofocus, form, required, labels, selectedOptions, willValidate, validity et validationMessage.
La propriété tabindex et les méthodes blur() et focus() ont été déplacées vers HTMLElement.
Les méthodes item(), namedItem(), checkValidity() et setCustomValidity().
Document Object Model (DOM) Level 2 HTML Specification
La définition de 'HTMLSelectElement' dans cette spécification.
Obsolete options retourne désormais un HTMLOptionsCollection (en-US).
length retourne désormais un unsigned long.
Document Object Model (DOM) Level 1 Specification
La définition de 'HTMLSelectElement' dans cette spécification.
Obsolete Définition initiale.

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi

  • L'élément HTML <select>, qui implémente cette interface.