L'entrée dropdown permet aux utilisateurs de sélectionner une valeur à partir d'une liste d'options. Contrairement aux éléments de sélection natifs, l'entrée déroulante vous permet de personnaliser à la fois son apparence et son comportement.
La propriété options peut accepter trois formats différents de valeurs :
value et label (voir l'exemple ci-dessus)['A', 'B', 'C']{ a: 'A', b: 'B', c: 'C' }Si vous assignez des options sous forme de tableau vide, l'entrée sera rendue dans un état désactivé.
L'entrée déroulante sera rendue en mode de sélection unique par défaut.
Les entrées déroulantes avec la propriété multiple définie seront rendues en mode de sélection multiple.
Remarquez dans l'exemple ci-dessus que parce que la propriété multiple est définie, la propriété value doit être un tableau.
Au lieu de passer une liste statique à la propriété options, les options peuvent être assignées de manière dynamique.
Dans cet exemple, la fonction, loadHorrorMovies, fait une requête à l'API pour TMDB afin de charger une liste de films d'horreur. Assigner la fonction à la propriété options chargera les options lorsque l'utilisateur final ouvrira la liste déroulante.
Par défaut, le menu déroulant ne chargera les options de manière asynchrone qu'une seule fois (lorsque la liste est déployée). Définir la propriété always-load-on-open fera en sorte que le menu déroulant charge les options chaque fois que la liste est déployée.
La propriété load-on-created fera en sorte que le menu déroulant charge les options dès qu'il est créé.
Une fonction assignée à la propriété options recevra deux arguments : page et hasNextPage. L'argument page indique le numéro de la page actuelle, et hasNextPage est une fonction de rappel qui indique s'il y a d'autres pages à charger.
Si vous préférez permettre à l'utilisateur de charger plus d'options sans avoir à cliquer sur l'option Charger plus en bas de la liste des options, vous pouvez définir la propriété load-on-scroll sur vrai, et notre fonction, loadCurrentlyPopularMovies, sera appelée à nouveau :
L'entrée déroulante de FormKit fournit également une propriété optionLoader qui vous permet de réhydrater des valeurs qui ne sont pas dans la liste des options. Dans cet exemple, le menu déroulant se voit attribuer une valeur initiale (deux identifiants de films). La fonction optionLoader est appelée pour chaque valeur qui n'est pas dans la liste des options.
Remarquez dans l'exemple ci-dessus que la fonction optionLoader reçoit deux arguments : la value de l'option sélectionnée (dans ce cas, l'identifiant du film) et le cachedOption. La propriété cachedOption est utilisée pour éviter des recherches inutiles. Si cachedOption n'est pas null, cela signifie que l'option sélectionnée a déjà été chargée, et vous pouvez retourner directement cachedOption.
Contrairement aux éléments de sélection natifs, l'entrée déroulante peut être personnalisée via le balisage.
L'entrée déroulante vous permet de personnaliser l'apparence de chaque option en utilisant l'emplacement des options. Dans cet exemple, nous utilisons l'emplacement des options pour afficher l'actif de chaque option ; logo et nom :
L'entrée déroulante vous permet de personnaliser l'apparence de l'option ou des options sélectionnées.
Lorsque vous utilisez l'entrée déroulante comme un multi-select, vous pouvez personnaliser l'apparence des options sélectionnées en définissant la propriété selection-appearance soit sur truncate (la valeur par défaut), soit sur tags.
Si vous souhaitez uniquement personnaliser l'affichage de l'option sélectionnée, utilisez l'emplacement de sélection (par opposition à l'emplacement d'option mentionné ci-dessus) :
L'emplacement de sélection n'existe pas sur le menu déroulant multi-sélection avec l'apparence de sélection truncate.
Les props suivantes vous permettent de personnaliser le comportement de l'entrée de menu déroulant.
Par défaut, l'entrée de menu déroulant sera rendue dans un état désactivé si aucune option n'est transmise. Facultativement, vous pouvez passer la prop empty-message avec un message à afficher lorsqu'aucune option n'est disponible :
Si vous souhaitez permettre aux utilisateurs de retirer la valeur sélectionnée, définissez la prop selection-removable sur true. Cela affichera une icône de fermeture à côté de la valeur sélectionnée :
La prop selection-removable ne peut pas être utilisée pour les multi-sélections.
Par défaut, lorsque la prop selection-removable est définie sur true, le menu déroulant ne s'ouvrira pas après que la valeur sélectionnée a été retirée. Vous pouvez changer ce comportement en définissant la prop open-on-remove sur true :
Par défaut, lorsque la prop multiple est définie, le menu déroulant ne se fermera pas après qu'une option a été sélectionnée. Vous pouvez changer ce comportement en définissant la prop close-on-select sur true :
Si vous souhaitez déployer la liste dès que l'entrée du menu déroulant est mise au point, vous pouvez utiliser la prop open-on-focus :
Lors de l'utilisation du menu déroulant avec des options statiques, le menu déroulant de FormKit est également doté d'une fonctionnalité appelée overscroll. Définir la prop behavior sur overscroll affichera la liste directement au-dessus de l'entrée pour maximiser la taille disponible pour la liste :
Si vous souhaitez limiter le nombre d'options qui peuvent être sélectionnées, vous pouvez utiliser la propriété max :
| Prop | Type | Par défaut | Description |
|---|---|---|---|
| options | any | [] | La liste des options parmi lesquelles l'utilisateur peut choisir. |
| load-on-scroll | boolean | false | Lorsqu'il est défini sur `true`, le menu déroulant essaiera de charger plus d'options en fonction de la position de défilement de l'utilisateur final |
| option-loader | function | null | Utilisé pour hydrater la valeur initiale, ou effectuer une demande supplémentaire pour charger plus d'informations sur une option sélectionnée. |
| empty-message | string | undefined | Affiche un message lorsqu'il n'y a pas d'options à afficher. |
| selection-appearance | string | truncate | Pour les menus déroulants multi-sélections, cette propriété vous permet de personnaliser l'apparence des options sélectionnées. Les valeurs possibles sont `truncate` (la valeur par défaut) ou `tags`. |
| selection-removable | boolean | false | Pour les menus déroulants à sélection unique, cette propriété vous permet de supprimer la valeur sélectionnée. |
| open-on-remove | boolean | false | Lorsque la propriété `selection-removable` est définie sur `true`, le menu déroulant ne s'ouvrira pas après que la valeur sélectionnée a été supprimée. Vous pouvez changer ce comportement en définissant la propriété `open-on-remove` sur `true`. |
| close-on-select | boolean | false | Lorsque la propriété `multiple` est définie, le menu déroulant ne se fermera pas après qu'une option a été sélectionnée. Vous pouvez changer ce comportement en définissant la propriété `close-on-select` sur `true`. |
| open-on-focus | boolean | false | Si vous souhaitez déployer la liste des options dès que le champ du menu déroulant est focalisé, vous pouvez utiliser la propriété `open-on-focus`. |
| options-appearance | string | undefined | Pour les menus déroulants multi-sélections, cette propriété vous permet de personnaliser l'apparence des options sélectionnées. Les valeurs possibles sont `default` (la valeur par défaut) ou `checkbox`. |
| multiple | boolean | false | Lorsqu'il est défini sur `true`, le menu déroulant permettra à l'utilisateur de sélectionner plusieurs options. |
| behavior | string | undefined | Affiche la liste des options directement au-dessus du champ pour maximiser la taille disponible pour la liste. |
| always-load-on-open | boolean | false | Détermine si le menu déroulant doit toujours charger ses options lorsqu'il est ouvert ou s'il doit se référer aux options qui ont été trouvées précédemment lors de l'ouverture. |
| load-on-created | boolean | false | Lorsqu'il est défini sur `true`, le menu déroulant chargera les options lorsque le nœud est créé. |
| max | number | string | undefined | Si vous souhaitez limiter le nombre d'options qui peuvent être sélectionnées, vous pouvez utiliser la propriété `max` (s'applique uniquement aux multi-sélections). |
| deselect | boolean | true | Lorsqu'il est défini sur `false`, l'utilisateur final ne peut pas désélectionner une option sélectionnée dans la liste. |
| popover | boolean | false | Affiche la liste des options du champ en utilisant l'API Popover du navigateur. |
| Afficher Universel props | |||
| config | Object | {} | Options de configuration à fournir au nœud d'entrée et à tout nœud descendant de cette entrée. |
| delay | Number | 20 | Nombre de millisecondes à attendre avant que la valeur d'une entrée ne soit déclenchée avant que le commit hook ne soit déclenché. |
| dirtyBehavior | string | touched | Détermine comment le drapeau "dirty" de cette entrée est défini. Peut être défini sur touched ou compare — touched (par défaut) est plus performant, mais ne détectera pas lorsque le formulaire correspond à nouveau à son état initial. |
| errors | Array | [] | Tableau de chaînes à afficher comme messages d'erreur sur ce champ. |
| help | String | '' | Texte pour le texte d'aide associé à l'entrée. |
| id | String | input_{n} | L'identifiant unique de l'entrée. Fournir un identifiant permet également d'accéder globalement au nœud de l'entrée. |
| ignore | Boolean | false | Empêche une entrée d'être incluse dans un parent (groupe, liste, formulaire, etc). Utile lors de l'utilisation d'entrées pour l'interface utilisateur au lieu de valeurs réelles. |
| index | Number | undefined | Permet d'insérer une entrée à l'index donné si le parent est une liste. Si la valeur de l'entrée est indéfinie, elle hérite de la valeur de cette position d'index. Si elle a une valeur, elle l'insère dans les valeurs de la liste à l'index donné. |
| label | String | '' | Texte pour l'élément label associé à l'entrée. |
| name | String | input_{n} | Le nom de l'entrée tel qu'identifié dans l'objet de données. Cela doit être unique au sein d'un groupe de champs. |
| parent | FormKitNode | contextual | Par défaut, le parent est un groupe d'enrobage, une liste ou un formulaire — mais cette propriété permet une affectation explicite du nœud parent. |
| prefix-icon | String | '' | Spécifie une icône à placer dans la section prefixIcon. |
| preserve | boolean | false | Conserve la valeur de l'entrée sur un groupe parent, une liste ou un formulaire lorsque l'entrée est démontée. |
| preserve-errors | boolean | false | Par défaut, les erreurs définies sur les entrées à l'aide de setErrors sont automatiquement effacées lors de l'entrée, en définissant cette propriété sur true, l'erreur est maintenue jusqu'à ce qu'elle soit explicitement effacée. |
| sections-schema | Object | {} | Un objet de clés de section et de valeurs partielles de schéma, où chaque partie de schéma est appliquée à la section respective. |
| suffix-icon | String | '' | Spécifie une icône à placer dans la section suffixIcon. |
| type | String | text | Le type d'entrée à afficher à partir de la bibliothèque. |
| validation | String, Array | [] | Les règles de validation à appliquer à l'entrée. |
| validation-visibility | String | blur | Détermine quand afficher les règles de validation en échec d'une entrée. Les valeurs valides sont blur, dirty et live. |
| validation-label | String | {label prop} | Détermine quelle étiquette utiliser dans les messages d'erreur de validation, par défaut, elle utilise la propriété label si elle est disponible, sinon elle utilise la propriété name. |
| validation-rules | Object | {} | Règles de validation personnalisées supplémentaires à rendre disponibles pour la propriété de validation. |
| value | Any | undefined | Initialise la valeur initiale d'une entrée et/ou de ses enfants. Non réactif. Peut initialiser des groupes entiers (formulaires) et des listes.. |
Vous pouvez cibler une section spécifique d'une entrée en utilisant la "key" de cette section, ce qui vous permet de modifier les classes de cette section, le HTML (via :sections-schema) ou le contenu (via des emplacements)). En savoir plus sur les sections ici.
| Section-key | Description |
|---|---|
| selector | La section sélecteur est un élément bouton qui ouvre la liste des options déroulantes. |
| selection | Contient l'option sélectionnée. |
| listitem | Un élément d'élément de liste qui contient la section option. |
| option | Un div qui contient le contenu de l'option. |
| listbox | La section listbox est un élément ul qui contient la liste des options. |
| dropdownWrapper | Enveloppe la section listbox. Un div qui gère le défilement de la listbox. |
| optionLoading | Un élément span qui est rendu conditionnellement à l'intérieur de l'option sélectionnée lors du chargement. |
| loaderIcon | Un élément pour afficher une icône dans l'élément sélecteur lorsque le chargement est en cours. |
| selectIcon | Un élément pour afficher une icône dans l'élément sélecteur lorsque la liste déroulante est fermée. |
| selectedIcon | Un élément pour afficher une icône à côté de l'option sélectionnée à l'intérieur de la listbox. |
| loadMore | Un élément d'élément de liste qui est rendu conditionnellement en bas de la liste des options lorsqu'il y a plus de pages à charger. |
| loadMoreInner | Un élément span qui agit comme un enveloppe pour l'icône de chargement à l'intérieur de la section loadMore. |
| emptyMessage | Un élément d'élément de liste qui est rendu conditionnellement lorsqu'il n'y a pas d'options à afficher. |
| emptyMessageInner | Un élément span qui agit comme un enveloppe pour la section emptyMessage. |
| tagsWrapper | Un élément div qui enveloppe la section tags. |
| tags | Un élément div qui contient les tags. |
| tagWrapper | Un élément div qui enveloppe le tag. |
| tag | Un élément div qui contient l'étiquette du tag et la section removeSelection. |
| tagLabel | Un élément span qui contient l'étiquette du tag. |
| removeSelection | Un élément span qui contient l'icône removeSelection. |
| selectorSelectionsWrapper | Un élément div qui enveloppe la section selectorSelections. |
| selectorSelections | Un élément div qui contient les sections selectorSelectionsItem. |
| selectorSelectionsItem | Un élément div qui contient le contenu de l'élément selectorSelectionsItem. |
| truncationCount | Un élément div qui contient le contenu du compteur de troncature. |
| Afficher Universel section keys | |
| outer | L'élément d'enrobage le plus externe. |
| wrapper | Un enrobage autour de l'étiquette et de l'entrée. |
| label | L'étiquette de l'entrée. |
| prefix | N'a pas de sortie par défaut, mais permet du contenu directement avant un élément d'entrée. |
| prefixIcon | Un élément pour afficher une icône avant la section de préfixe. |
| inner | Un enrobage autour de l'élément d'entrée réel. |
| suffix | N'a pas de sortie par défaut, mais permet du contenu directement après un élément d'entrée. |
| suffixIcon | Un élément pour afficher une icône après la section de suffixe. |
| input | L'élément d'entrée lui-même. |
| help | L'élément contenant le texte d'aide. |
| messages | Un enrobage autour de tous les messages. |
| message | L'élément (ou plusieurs éléments) contenant un message — le plus souvent des messages de validation et d'erreur. |
Tous les champs de saisie FormKit sont conçus en tenant compte des considérations d'accessibilité suivantes. Aidez-nous à améliorer continuellement l'accessibilité pour tous en signalant les problèmes d'accessibilité ici :
| Clé de Section | Attribut | Par défaut | Description |
|---|---|---|---|
| selector | tabindex | 0 | Priorise l'ordre de focus au clavier en le définissant à 0 |
| aria-haspopup | listbox | Signale la présence d'une liste déroulante activée par interaction. | |
| aria-expanded | Indique si l'élément déroulant est actuellement déployé ou réduit. | ||
| aria-controls | Associe cet élément à l'ID de l'élément de liste. | ||
| aria-describedBy | Associe cet élément à du texte descriptif d'un autre élément. | ||
| placeholder | aria-hidden | true | Rend cet élément non exposé à l'API d'accessibilité lorsqu'aucun espace réservé n'existe. |
| removeSelection | tabindex | -1 | Priorise l'ordre de focus au clavier en le définissant à -1 |
| aria-controls | Associe cet élément à l'ID de l'élément de saisie. | ||
| selections | aria-live | polite | Annonce aux lecteurs d'écran que cet élément a été mis à jour dynamiquement sans interrompre la tâche en cours. |
| aria-hidden | true | Rend cet élément non exposé à l'API d'accessibilité. | |
| selectionsItem | aria-hidden | true | Rend cet élément non exposé à l'API d'accessibilité lorsque l'indice visible final et l'indice sont supérieurs à l'indice visible final. |
| tagWrapper | tabindex | 0 | Priorise l'ordre de focus au clavier en le définissant à 0 |
| tag | tabindex | 0 | Priorise l'ordre de focus au clavier en le définissant à 0 |
| tagsWrapper | aria-live | polite | Annonce aux lecteurs d'écran que cet élément a été mis à jour dynamiquement sans interrompre la tâche en cours. |
| Afficher Universel clé de section | |||
| label | label | for | Associe cela à un élément de saisie, améliorant l'accessibilité et l'expérience utilisateur |
| input | input | disabled | Désactive un élément HTML, empêchant l'interaction de l'utilisateur et signalant un état non interactif |
| aria-describedby | Améliore l'accessibilité en associant un élément à une description, facilitant la lecture par les lecteurs d'écran | ||
| aria-required | Ajoute l'état requis lorsque la validation est requise. | ||
| icon | icon | for | Chaque fois qu'une icône est définie comme libellé, elle la relie à un élément de saisie, améliorant l'accessibilité et l'expérience utilisateur |
| Événement clavier | Description |
|---|---|
| Tab | Déplace le focus vers la prochaine entrée pouvant être ciblée sur la page. |
| Shift + Tab | Déplace le focus vers l'entrée précédente pouvant être ciblée sur la page. |