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 dropdown vous permet de personnaliser à la fois son apparence et son comportement.
La prop options peut accepter trois formats de valeurs différents :
value et label (voir exemple ci-dessus)['A', 'B', 'C']{ a: 'A', b: 'B', c: 'C' }Si vous attribuez des options sous forme de tableau vide, l'entrée sera rendue dans un état désactivé.
L'entrée dropdown sera rendue en mode de sélection unique par défaut.
Les entrées dropdown avec la prop multiple définie seront rendues en mode de sélection multiple.
Remarquez dans l'exemple ci-dessus que parce que la prop multiple est définie, la prop value doit être un tableau.
Au lieu de passer une liste statique à la prop options, les options peuvent être attribuées de manière dynamique.
Dans cet exemple, la fonction, loadHorrorMovies, fait une demande à l'API pour TMDB pour charger une liste de films d'horreur. L'attribution de la fonction à la prop options chargera les options lorsque l'utilisateur final ouvre la liste.
Par défaut, le dropdown ne chargera les options de manière asynchrone qu'une seule fois (lors de l'expansion de la liste). La définition de la prop always-load-on-open fera en sorte que le dropdown charge les options chaque fois que la liste est étendue.
La prop load-on-created fera en sorte que le dropdown charge les options dès qu'il est créé.
Une fonction assignée à la prop 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 prop load-on-scroll sur true, et notre fonction, loadCurrentlyPopularMovies sera appelée à nouveau :
L'input dropdown de FormKit fournit également une prop optionLoader qui vous permet de réhydrater les valeurs qui ne sont pas dans la liste des options. Dans cet exemple, le dropdown est fourni avec une valeur initiale (deux IDs 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'ID du film) et le cachedOption. La prop cachedOption est utilisée pour éviter les recherches inutiles. Si le cachedOption n'est pas null, cela signifie que l'option sélectionnée a déjà été chargée, et vous pouvez retourner directement le cachedOption.
Contrairement aux éléments de sélection natifs, l'input dropdown peut être personnalisé via. balisage.
L'input dropdown vous permet de personnaliser l'apparence de chaque option en utilisant le slot d'option. Dans cet exemple, nous utilisons le slot d'option pour afficher l'actif de chaque option ; logo et nom :
L'input dropdown vous permet de personnaliser l'apparence de l'option(s) sélectionnée(s).
Lors de l'utilisation de l'input dropdown comme un multi-select, vous pouvez personnaliser l'apparence des options sélectionnées en définissant la prop selection-appearance sur truncate (par défaut) ou tags.
Si vous souhaitez uniquement personnaliser l'affichage de l'option sélectionnée, utilisez le slot de sélection (par opposition au slot d'option mentionné ci-dessus) :
Le slot de sélection n'existe pas sur le dropdown multi-sélection avec l'apparence de sélection truncate.
Les props suivantes vous permettent de personnaliser le comportement de l'input de la liste déroulante.
Par défaut, l'input de la liste déroulante sera rendu dans un état désactivé si aucune option n'est passée. En option, vous pouvez passer le prop empty-message un message à afficher lorsqu'aucune option n'est disponible :
Lors de l'utilisation de la liste déroulante avec des options statiques, la liste déroulante de FormKit est également dotée d'une fonction appelée overscroll :
Si vous souhaitez permettre aux utilisateurs de supprimer la valeur sélectionnée, définissez le prop selection-removable sur true. Cela affichera une icône de fermeture à côté de la valeur sélectionnée :
Le prop selection-removable ne peut pas être utilisé pour les multi-sélections.
Par défaut, lorsque le prop selection-removable est défini sur true, la liste déroulante ne s'ouvrira pas après la suppression de la valeur sélectionnée. Vous pouvez modifier ce comportement en définissant le prop open-on-remove sur true :
Par défaut, lorsque le prop multiple est défini, la liste déroulante ne se ferme pas après la sélection d'une option. Vous pouvez modifier ce comportement en définissant le prop close-on-select sur true :
Si vous souhaitez déployer la listbox dès que l'input de la liste déroulante est mis au point, vous pouvez utiliser le prop open-on-focus :
Si vous souhaitez limiter le nombre d'options qui peuvent être sélectionnées, vous pouvez utiliser le prop max :
| Prop | Type | Par défaut | Description |
|---|---|---|---|
| options | any | [] | La liste des options que l'utilisateur peut sélectionner. |
| load-on-scroll | boolean | false | Lorsqu'il est défini sur `true`, la liste déroulante 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 listes déroulantes multi-sélections, ce prop vous permet de personnaliser l'apparence des options sélectionnées. Les valeurs possibles sont `truncate` (par défaut) ou `tags`. |
| selection-removable | boolean | false | Pour les listes déroulantes à sélection unique, ce prop vous permet de supprimer la valeur sélectionnée. |
| open-on-remove | boolean | false | Lorsque le prop `selection-removable` est défini sur `true`, la liste déroulante ne s'ouvrira pas après la suppression de la valeur sélectionnée. Vous pouvez modifier ce comportement en définissant le prop `open-on-remove` sur `true`. |
| close-on-select | boolean | false | Lorsque le prop `multiple` est défini, la liste déroulante ne se ferme pas après la sélection d'une option. Vous pouvez modifier ce comportement en définissant le prop `close-on-select` sur `true`. |
| open-on-focus | boolean | false | Si vous souhaitez déployer la listbox dès que l'input de la liste déroulante est mis au point, vous pouvez utiliser le prop `open-on-focus`. |
| options-appearance | string | undefined | Pour les listes déroulantes multi-sélections, ce prop vous permet de personnaliser l'apparence des options sélectionnées. Les valeurs possibles sont `default` (par défaut) ou `checkbox`. |
| multiple | boolean | false | Lorsqu'il est défini sur `true`, la liste déroulante permettra à l'utilisateur de sélectionner plusieurs options. |
| behavior | string | undefined | Lorsqu'il est défini sur `overscroll`, la liste déroulante permettra à l'utilisateur de sélectionner plusieurs options. |
| always-load-on-open | boolean | false | Lorsqu'il est défini sur `true`, la liste déroulante chargera toujours les options lorsque la listbox est ouverte. |
| load-on-created | boolean | false | Lorsqu'il est défini sur `true`, la liste déroulante 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 le prop `max` (s'applique uniquement aux multi-sélections). |
| 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 du 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 de liste qui contient la section d'option. |
| option | Une 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. Une 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 lorsque le chargement est en cours. |
| 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 le menu déroulant est fermé. |
| 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 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 sert d'enveloppe pour l'icône de chargement dans la section loadMore. |
| emptyMessage | Un élément de liste qui est rendu conditionnellement lorsqu'il n'y a pas d'options à afficher. |
| emptyMessageInner | Un élément span qui sert d'enveloppe pour la section emptyMessage. |
| tagsWrapper | Un élément div qui enveloppe la section des 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 selectorSelectionsItem. |
| truncationCount | Un élément div qui contient le contenu de truncationCount. |
| 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. |