L'entrée de liste de transfert est idéale pour les situations où l'utilisateur final doit sélectionner et trier plusieurs valeurs à partir d'une liste d'options. Dans cet exemple, nous permettons à l'utilisateur final de sélectionner un groupe d'invités et de les déplacer vers une liste VIP :
Dans cette section, nous allons couvrir les bases de la façon de reproduire l'exemple 'Invités vs VIPs' ci-dessus.
Voici un exemple de l'entrée de liste de transfert avec les props minimales requises. Comme vous pouvez le voir, il y a deux boîtes de liste : la boîte de liste source et la boîte de liste cible. La boîte de liste source contiendra la liste des options, et la boîte de liste cible contiendra les options sélectionnées :
Ajoutons quelques props d'étiquettes pour rendre clair à l'utilisateur final comment utiliser l'entrée de liste de transfert. Nous ajouterons une prop label pour expliquer la directive à l'utilisateur, et des props source-label et target-label pour indiquer quelle boîte de liste est la source et laquelle est la cible :
Dans cet état, sans options passées et sans valeurs sélectionnées, nous pouvons afficher un message personnalisé à l'utilisateur en définissant les props source-empty-message et target-empty-message :
La prop options peut accepter trois formats de valeurs différents :
value et label'A', 'B', 'C'{ a: 'A', b: 'B', c: 'C' }Allons-y et peuplons les options de la liste de transfert avec une liste de noms d'invités :
La valeur de l'entrée de la liste de transfert est un tableau. Les valeurs des options sélectionnées de la liste source seront ajoutées au tableau. Pour montrer le changement de valeur dans l'exemple ci-dessous, enveloppons l'entrée de la liste de transfert dans un formulaire FormKit, définissons le nom de l'entrée de la liste de transfert à vips, et montrons la valeur du formulaire lui-même dans une balise <pre> (si vous n'êtes pas familier avec les formulaires FormKit, vous pouvez en savoir plus ici) :
L'entrée de la liste de transfert peut être pré-remplie avec des valeurs en définissant la prop value sur la transferlist elle-même ou un form ou group enveloppant. N'oubliez pas que les valeurs que vous passez à la prop value doivent correspondre aux clés des valeurs dans votre liste d'options :
L'entrée de la liste de transfert peut être rendue recherchable en définissant la prop searchable. Dans cet exemple, nous définirons la prop searchable et définirons également une prop placeholder pour l'entrée de recherche :
L'entrée de la liste de transfert filtrera les options avec sa propre fonction de recherche interne. Vous pouvez remplacer cette fonction de recherche en fournissant à la prop filter une fonction de votre choix. Votre fonction recevra deux arguments, l'option en cours d'itération et la valeur de recherche actuelle :
Par défaut, l'entrée de la liste de transfert effacera l'entrée de recherche lors de la sélection. Vous pouvez modifier ce comportement en définissant la prop clear-on-select à false :
L'entrée de la liste de transfert peut être limitée à un nombre maximum de valeurs sélectionnées en définissant la prop max. Pour cet exemple seulement, définissons la prop max à 2 pour limiter le nombre de VIPs qui peuvent être sélectionnés :
Par défaut, l'entrée de la liste de transfert ajoutera ou supprimera des options au clic. Vous pouvez modifier ce comportement en définissant la propriété transfer-on-select sur false. Maintenant, la liste de transfert se comportera davantage comme une liste de transfert traditionnelle :
Ici, nous avons une entrée de liste de transfert qui charge ses options à partir d'une fonction asynchrone. La fonction est appelée lorsque le composant est monté et les options sont ensuite chargées dans la boîte de liste source :
Supposons maintenant que notre requête API ne récupère pas toutes les options dont nous avons besoin, mais renvoie plutôt une réponse paginée. L'entrée de la liste de transfert peut gérer la pagination avec une configuration mineure de la fonction asynchrone.
Lors de l'attribution de la propriété options à une fonction asynchrone, la fonction sera appelée avec l'objet contexte FormKit comme premier argument. Cet objet contexte contient une propriété page (la page actuelle que nous essayons de charger) qui est suivie par l'entrée de la liste de transfert, et hasNextPage, qui est une fonction de rappel que nous pouvons utiliser pour indiquer à la liste de transfert qu'il y a plus d'options à charger :
L'entrée de la liste de transfert peut également charger des options de manière asynchrone lorsque l'utilisateur effectue une recherche. Dans cet exemple, nous allons ajouter à nouveau la propriété searchable, et changer getGuests() en searchGuests(). Lorsque l'utilisateur effectue une recherche, searchGuests() sera maintenant appelé avec le même objet contexte qu'auparavant, mais cette fois, nous allons déstructurer uniquement la propriété search. De plus, nous allons modifier getGuests() pour ne renvoyer des invités que lorsqu'une valeur de recherche est fournie :
L'entrée de la liste de transfert fournit également une propriété optionLoader qui vous permet de réhydrater des valeurs qui ne sont pas dans la liste d'options. Dans cet exemple, nous allons fournir à la liste de transfert une valeur initiale (un ID d'invité), et attribuer l'optionLoader à une fonction qui fera une requête à l'API pour récupérer les données individuelles de l'invité :
Remarquez dans l'exemple ci-dessus que la fonction optionLoader getGuest reçoit deux arguments : la valeur de l'option sélectionnée (dans ce cas, l'ID du film) et le cachedOption. Le cachedOption est utilisé 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 renvoyer directement le cachedOption.
Vous pouvez également utiliser optionLoader pour récupérer des données supplémentaires sur les valeurs sélectionnées qui ne sont pas déjà dans la liste des options. Dans cet exemple, après avoir sélectionné une option, nous allons effectuer une recherche pour charger l'âge de l'invité sélectionné :
Comme tout autre input FormKit, l'input de la liste de transfert vous permet d'utiliser des slots pour personnaliser son balisage.
Maintenant que nous chargeons des données supplémentaires sur les valeurs sélectionnées (l'âge et l'adresse e-mail de l'invité sélectionné), personnalisons l'apparence des valeurs sélectionnées en utilisant les slots target-option :
L'input de la liste de transfert peut être utilisé pour créer une liste classée, faisons cela avec les plus grands joueurs de la NBA :
| Prop | Type | Par défaut | Description |
|---|---|---|---|
| debounce | number | 200 | Nombre de millisecondes pour différer les appels à une fonction d'options. |
| options | any | [] | La liste des options que l'utilisateur peut sélectionner. |
| filter | function | null | Utilisé pour appliquer votre propre fonction de filtre pour les options statiques. |
| 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. |
| source-empty-message | string | undefined | Affiche un message lorsqu'il n'y a pas d'options à afficher. |
| target-empty-message | string | undefined | Affiche un message lorsqu'il n'y a pas de valeurs à afficher |
| max | number | undefined | Limite le nombre d'options qui peuvent être sélectionnées. |
| clear-on-select | boolean | true | Efface l'input de recherche après avoir sélectionné une option (uniquement pour les options qui ne sont pas chargées via une fonction). |
| searchable | boolean | false | Active l'input de recherche. |
| source-label | string | undefined | Affiche une étiquette pour la liste source. |
| target-label | string | undefined | Affiche une étiquette pour la liste cible. |
| transfer-on-select | boolean | true | Transfère automatiquement les options sélectionnées à la liste cible. Si défini à false, affichera des boutons de transfert vers l'avant et vers l'arrière. |
| 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 "clé" de cette section, ce qui vous permet de modifier les classes de cette section, le HTML (via :sections-schema), ou le contenu (via les slots). Lisez plus sur les sections ici.
| Section-key | Description |
|---|---|
| fieldset | Un élément fieldset qui agit comme l'élément racine pour l'entrée de la liste de transfert. |
| legend | Un élément de légende qui rend le label. |
| source | Un élément div qui contient les sections sourceHeader, sourceControls et sourceListItems. |
| sourceHeader | Un élément div qui contient les sections sourceHeaderLabel et sourceHeaderItemCount |
| sourceHeaderLabel | Un élément de label qui rend la prop sourceLabel. |
| sourceHeaderItemCount | Un élément span qui rend le nombre d'éléments et le nombre d'éléments sélectionnés dans la liste source. |
| sourceControls | Un élément div qui contient les sections sourceSearchInput et sourceSearchClear |
| sourceSearch | Un élément div qui contient les sections sourceSearchInput et sourceSearchClear |
| sourceSearchInput | Un élément d'entrée de texte utilisé pour la recherche. |
| sourceSearchClear | Un élément bouton qui efface l'entrée de recherche. |
| closeIcon | Le span utilisé contenant l'icône pour effacer l'entrée de recherche. |
| sourceListItems | Un élément ul qui contient les sourceListItems. |
| sourceEmptyMessage | Un élément li qui contient la section emptyMessageInner. |
| emptyMessageInner | Un élément span qui rend le texte du message vide fourni. |
| sourceListItem | Un élément li pour la section sourceListItems qui contient la section sourceOption. |
| selectIcon | Un élément span qui rend l'icône sélectionnée lorsque le sourceListItem est défini sur sélectionné. |
| sourceOption | Un élément div qui rend le label de l'option. |
| sourceLoadMore | Un élément li qui contient la section loadMoreInner. |
| loadMoreInner | Un élément span qui rend l'icône de chargement. |
| loaderIcon | Un élément span qui affiche une icône lorsque le chargement est en cours. |
| transferControls | Un élément div qui contient les sections transferButtonForwardAll, transferButtonForward, transferButtonBackward et transferButtonBackwardAll. |
| transferButtonForwardAll | Un élément bouton qui transfère toutes les options à la liste cible. |
| transferButtonForward | Un élément bouton qui transfère les options sélectionnées à la liste cible. |
| transferButtonBackward | Un élément bouton qui transfère les options sélectionnées à la liste source. |
| transferButtonBackwardAll | Un élément bouton qui transfère toutes les options à la liste source. |
| controlLabel | Un élément span qui rend le label de contrôle. |
| fastForwardIcon | Un élément span qui rend l'icône d'avance rapide. |
| moveRightIcon | Un élément span qui rend l'icône de déplacement à droite. |
| moveLeftIcon | Un élément span qui rend l'icône de déplacement à gauche. |
| rewindIcon | Un élément span qui rend l'icône de rembobinage. |
| target | Un élément div qui contient les sections targetHeader, targetControls et targetListItems. |
| targetHeader | Un élément div qui contient les sections targetHeaderLabel et targetHeaderItemCount |
| targetHeaderLabel | Un élément de label qui rend la prop targetLabel. |
| targetHeaderItemCount | Un élément span qui rend le nombre d'éléments et le nombre d'éléments sélectionnés dans la liste cible. |
| targetListItems | Un élément ul qui contient les targetListItems. |
| targetEmptyMessage | Un élément li qui contient la section emptyMessageInner. |
| targetListItem | Un élément li pour la section targetListItems qui contient la section targetOption. |
| targetLoadMore | Un élément li qui contient la section loadMoreInner. |
| 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. |