Statut
Component checklist
Usage
<dsa-combobox
id="combobox"
name="name"
label="Pays"
>
<dsa-option value="fr_FR">France</dsa-option>
<dsa-option value="en_UK">Angleterre</dsa-option>
<dsa-option value="en_US">États-Unis</dsa-option>
<dsa-option value="fr_BE">Belgique</dsa-option>
</dsa-combobox>
<script type="text/typescript">
import '@ds-autonomie/web-components/dist/components/combobox/combobox.js'
import '@ds-autonomie/web-components/dist/components/option/option.js'
import type { DSACombobox, DSAOption } from '@ds-autonomie/web-components';
const el = document.querySelector<DSACombobox>('#combobox')
if (el !== null) {
console.log(el.value)
}
</script>
API
Attributs et propriétés
|
Propriété |
Description |
Type |
Valeur par défaut |
|---|---|---|---|
|
accessibleName accessible-name |
Fournit un nom accessible dans le cas où aucun label n'est fourni. |
string |
- |
|
clearable |
Affiche le bouton supprimer lorsque le champ a une valeur |
boolean |
false |
|
debounceTimeout |
Délai entre la saisie du nouveau caractère et l'envoi de l'événement dsa-input. |
number |
300 |
|
defaultValue |
La valeur par défaut du contrôle. Utilisé principalement pour la remise à zero du form |
string |
- |
|
description |
Fournit une description au composant pour une meilleure accessibilité. |
string |
'' |
|
disabled |
Désactive le champ de saisie |
boolean |
false |
|
error |
Indique si le composant doit être en état d'erreur |
boolean |
false |
|
errorMessage |
Un message d'erreur qui est affiché lorsque l'attribut error est définie à true. Si plusieurs messages doivent être affichés, les ajouter dans la chaine de caractères séparés par des pipes "|". |
string | string[] |
'' |
|
fetchingState |
En utilisation asynchrone, permet de spécifier l'état de chargement. |
loading error success idle |
idle |
|
form |
Par défaut, les contrôles de formulaire sont associés à l'élément de formulaire parent le plus proche. Cet attribut permet de placer le contrôle de formulaire en dehors d'un formulaire et de l'associer au formulaire qui a cet identifiant. Le formulaire doit être dans le même document ou racine fantôme pour que cela fonctionne |
string |
'' |
|
helpText help-text |
Le help-text du champ. Pour afficher du HTML, utilisez le slot help-text |
string |
'' |
|
hoist |
Activez cette option pour éviter que le panneau ne soit coupé lorsque le composant est placé à l'intérieur d'un conteneur avec overflow : scroll \| auto. Hoisting utilise une stratégie de positionnement fixe qui fonctionne dans de nombreux cas, mais pas dans tous |
boolean |
false |
|
items (pas d’attribut) |
Tableau contenant une liste d'options. À utiliser, en tant qu'alternative au slot listbox d'options. |
DSAOption[] |
[] |
|
label |
Le label du champ. Pour afficher du HTML, utilisez le slot label |
string |
'' |
|
maxOptionsVisible max-options-visible |
Le nombre maximum d'options sélectionnées lorsque multiple est à true. Une fois le maximum atteint, "+n" affichera le nombre d'options additionnelles sélectionnées. Fournir la valeur 0 pour enlever la limite |
number |
3 |
|
multiple |
Permet la selection de une ou plusieurs options |
boolean |
false |
|
keepSearchAfterSelection keep-search-after-selection |
En selection multiple, conserve le terme de recherche courant après la selection d'une option. |
boolean |
false |
|
name |
Le nom du champ, soumis sous la forme d'une paire nom/valeur avec les données du formulaire |
string |
'' |
|
noSyncWidth no-sync-width |
Le dropdown n'aura pas la même taille que son ancre |
boolean |
false |
|
open |
Indique si le combobox est ouverte ou non. Utiliser cet attribut pour afficher ou cacher le combobox, ou utiliser les propriétés show() et hide() |
boolean |
false |
|
overrideDefaultFiltering override-default-filtering |
Désactive la logique interne de filtre des options |
boolean |
false |
|
placeholder |
Le placement privilégier du panneau de dropdown. As savoir que le placement peux varier en fonction des besoins pour afficher le panneau à l'intérieur du viewport |
string |
'' |
|
placement |
Le placement privilégier du panneau de dropdown. As savoir que le placement peux varier en fonction des besoins pour afficher le panneau à l'intérieur du viewport |
top top-start top-end bottom bottom-start bottom-end right right-start right-end left left-start left-end |
bottom-start |
|
readonly |
Désactive le champ de saisie tout en le gardant focusable |
boolean |
false |
|
required |
Rend le champ obligatoire |
boolean |
false |
|
size |
La taille du champ de saisie |
small medium large |
medium |
|
title |
Le title contient un texte représentant des informations consultatives relatives à l'élément auquel il appartient |
string |
'' |
|
value |
La valeur actuelle de la combobox, représentant une liste des options sélectionnées (ou une seule option si multiple est désactivé). |
string | string[] |
'' |
|
variant |
La variante du champ de saisie |
layer base |
base |
|
visibleListLength visible-list-length |
Le nombre d'options qui seront affichées dans la liste par défaut. Si le nombre d'options est supérieur à celui-ci, ces options seront cachées par défaut, et un bouton "voir plus" permettra de les révéler. La valeur par défaut `undefined` permet de ne pas limiter la liste |
number |
- |
Méthodes
|
Nom |
Description |
Type |
|---|---|---|
|
blur()
|
Enlève le focus du champ |
() => void |
|
checkValidity() |
Vérifie la validité du champ mais ne montre pas de message de validation |
() => boolean |
|
focus() |
Met le focus sur le champ |
(options?: FocusOptions) => void |
|
getForm() |
Obtient le formulaire associé si il existe |
() => HTMLFormElement | null |
|
hide() |
Cache le panneau du dropdown |
() => Promise<void> |
|
reportValidity() |
Vérifie la validité et montre le message du navigateur si le champ est invalide |
() => boolean |
|
setCustomValidity() |
Défini un message de validation personnalisé |
(message: string) => void |
|
show() |
Affiche le panneau du dropdown |
() => Promise<void> |
Slots
|
Nom |
Description |
|---|---|
|
(defaut) |
Le contenu principale du dropdown, généralement une liste de dsa-option. Sinon, vous pouvez utiliser la propriété 'items' |
|
label |
Le slot du libellé du champ de saisie. Alternativement, vous pouvez utiliser l'attribut label |
|
prefix |
Utilisé pour ajouter une icône de présentation ou un élément similaire à l'entrée |
|
help-text |
Texte qui décrit comment utiliser le champ de saisie. Alternativement, vous pouvez utiliser l'attribut help-text |
|
tooltip |
Texte qui permet de passer des informations additionnelles à coté du libellé |
Événements
|
Nom |
Description |
|---|---|
|
dsa-after-hide |
Émis une fois que le panneau est caché |
|
dsa-after-show |
Émis une fois que le panneau est ouvert |
|
dsa-blur |
Émis lorsque le champ perd le focus |
|
dsa-change |
Émis lorsque la valeur du champ change |
|
dsa-clear |
Émis lorsque la valeur du champ est effacé |
|
dsa-focus |
Émis lorsque le champ obtient le focus |
|
dsa-hide |
Émis quand le panneau est caché |
|
dsa-input |
Émis lorsque le champ reçoit une entrée. Envoi décalé en fonction de la valeur de debounce-timeout |
|
dsa-invalid |
Émis lorsque le contrôle de formulaire vérifie la validité du champ et que les contraintes ne sont pas respectées |
|
dsa-show |
Émis quand le panneau s'ouvre |
Performances
Le combobox est un champ de sélection conçu pour gérer un grand nombre d'options. Toutefois, lorsque ce nombre devient excessif, des problèmes de performance peuvent survenir. Ces problèmes sont principalement causés par le fait que chaque option proposée à l'utilisateur est représentée par un élément distinct dans le DOM. Pour atténuer ces problèmes, nous vous recommandons de suivre les bonnes pratiques suivantes :
1. Utiliser l'attribut items pour rendre les options
Privilégiez l'utilisation de l'attribut items pour fournir les options au lieu d'insérer directement les éléments dans le slot par défaut. Cela permet de ne rendre les options que lorsque cela est nécessaire, c'est-à-dire lorsqu'elles correspondent à la recherche saisie par l'utilisateur. Les éléments transmis via cet attribut ne sont pas directement insérés dans le DOM, ce qui contribue à alléger la structure du DOM et à améliorer les performances.
2. Utiliser l'attribut visible-list-length
L'attribut visible-list-length permet de limiter le nombre d'options affichées initialement à l'utilisateur. Lorsque le nombre d'options est particulièrement élevé, cet attribut garantit la réactivité de l'interface. L'utilisateur a la possibilité d'étendre l'affichage en cliquant sur le bouton "voir plus", qui apparaîtra à la fin de la liste d'options.
3. Retarder l’affichage des options
Pour optimiser encore davantage les performances, il est recommandé de ne déclencher l'affichage des options que lorsque l'utilisateur a saisi un nombre minimum de caractères. Cela permet de limiter naturellement le nombre d’options qui seront affichées et donc d’alléger le DOM en ne rendant que les éléments qui correspondent aux besoins de l’utilisateur.