La liste de transfert d'entrée 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 parmi 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.
Ci-dessous se trouve un exemple de la liste de transfert d'entrée avec les propriétés requises minimales. 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 propriétés d'étiquette pour clarifier à l'utilisateur final comment utiliser la liste de transfert d'entrée. Nous ajouterons une propriété label pour expliquer la directive à l'utilisateur, et les propriétés 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 propriétés source-empty-message et target-empty-message :
La propriété options peut accepter trois formats différents de valeurs :
value et label'A', 'B', 'C'{ a: 'A', b: 'B', c: 'C' }Allons de l'avant 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 la valeur qui change 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 affichons la valeur du formulaire lui-même dans une balise <pre> (si vous n'êtes pas familier avec les formulaires FormKit, vous pouvez en lire plus ici) :
L'entrée de la liste de transfert peut être pré-remplie avec des valeurs en définissant la propriété value sur la transferlist elle-même ou sur un form ou group englobant. Rappelez-vous que les valeurs que vous passez à la propriété 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 propriété searchable. Dans cet exemple, nous allons définir la propriété searchable et également définir une propriété 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 propriété 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 changer ce comportement en définissant la propriété 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 propriété max. Pour cet exemple seulement, définissons la propriété max à 2 pour limiter le nombre de VIP qui peuvent être sélectionnés :
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é :
Tout comme n'importe quelle autre entrée FormKit, l'entrée de 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'entrée de liste de transfert peut être utilisée 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 temporiser les appels à une fonction d'options. |
| options | any | [] | La liste des options parmi lesquelles l'utilisateur peut choisir. |
| filter | function | null | Utilisé pour appliquer votre propre fonction de filtrage personnalisée 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'entrée 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'entrée 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 vers la liste cible. Si défini sur false, affichera des boutons de transfert vers l'avant et de transfert 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 legend 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 label qui rend la propriété 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 de saisie de texte utilisé pour la recherche. |
| sourceSearchClear | Un élément bouton qui efface la saisie de recherche. |
| closeIcon | Le span utilisé contenant l'icône pour effacer la saisie 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 produit 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 vers la liste cible. |
| transferButtonForward | Un élément bouton qui transfère les options sélectionnées vers la liste cible. |
| transferButtonBackward | Un élément bouton qui transfère les options sélectionnées vers la liste source. |
| transferButtonBackwardAll | Un élément bouton qui transfère toutes les options vers 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 vers la droite. |
| moveLeftIcon | Un élément span qui rend l'icône de déplacement vers la gauche. |
| rewindIcon | Un élément span qui rend l'icône de retour rapide. |
| 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 label qui rend la propriété 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. |
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 |
|---|---|---|---|
| fieldset | role | presentation | Indique aux technologies d'assistance que cet élément fonctionne comme une présentation. |
| aria-describedby | Associe un élément à une description, aidant les lecteurs d'écran. | ||
| sourceHeader | role | presentation | Indique aux technologies d'assistance que cet élément fonctionne comme une présentation. |
| sourceHeaderLabel | for | Associe le label à un élément de saisie. Les utilisateurs peuvent cliquer sur le label pour focaliser la saisie ou pour basculer entre les états. | |
| sourceHeaderItemCount | role | presentation | Indique aux technologies d'assistance que cet élément fonctionne comme une présentation. |
| aria-label | Fournit un nom accessible. | ||
| sourceSearchInput | role | searchbox | Indique aux technologies d'assistance que cet élément fonctionne comme une boîte de recherche. |
| aria-label | Fournit un nom accessible. | ||
| sourceSearchClear | aria-label | Fournit un nom accessible. | |
| sourceListItems | tabindex | -1 or 0 | Priorise l'ordre de focus au clavier en le réglant sur -1 lorsque c'est recherchable ou qu'il n'y a pas d'options de source et 0 dans le cas contraire. |
| aria-activedescendant | Gère le focus vers l'élément descendant actif courant. | ||
| role | listbox | Indique aux technologies d'assistance que cet élément fonctionne comme une liste déroulante. | |
| aria-multiselectable | true | Indique qu'il permet de sélectionner plusieurs éléments simultanément. | |
| aria-roledescription | Fournit une description de ce rôle d'élément. | ||
| sourceListItem | aria-selected | Indique que cet élément est actuellement sélectionné. | |
| role | option | Indique aux technologies d'assistance que cet élément fonctionne comme une option. | |
| sourceLoadMore | tabindex | -1 | Priorise l'ordre de focus au clavier en le réglant sur -1. |
| aria-selected | false | Indique que cet élément n'est jamais sélectionné. | |
| sourceEmptyMessage | role | presentation | Indique aux technologies d'assistance que cet élément fonctionne comme une présentation. |
| targetHeader | role | presentation | Indique aux technologies d'assistance que cet élément fonctionne comme une présentation. |
| targetHeaderLabel | for | Associe le label à un élément de saisie. Les utilisateurs peuvent cliquer sur le label pour focaliser la saisie ou pour basculer entre les états. | |
| targetHeaderItemCount | role | presentation | Indique aux technologies d'assistance que cet élément fonctionne comme une présentation. |
| aria-label | Fournit un nom accessible. | ||
| targetListItems | tabindex | -1 or 0 | Priorise l'ordre de focus au clavier en le réglant sur -1 lorsque c'est recherchable ou qu'il n'y a pas d'options de source et 0 dans le cas contraire. |
| aria-activedescendant | Gère le focus vers l'élément descendant actif courant. | ||
| role | listbox | Indique aux technologies d'assistance que cet élément fonctionne comme une liste déroulante. | |
| aria-multiselectable | true | Indique qu'il permet de sélectionner plusieurs éléments simultanément. | |
| aria-roledescription | Fournit une description de ce rôle d'élément. | ||
| targetListItem | aria-selected | Indique que cet élément est actuellement sélectionné. | |
| role | option | Indique aux technologies d'assistance que cet élément fonctionne comme une option. | |
| targetLoadMore | tabindex | -1 | Priorise l'ordre de focus au clavier en le réglant sur -1. |
| aria-selected | false | Indique que cet élément n'est jamais sélectionné. | |
| targetEmptyMessage | role | presentation | Indique aux technologies d'assistance que cet élément fonctionne comme une présentation. |
| transferButtonForward | aria-label | Fournit un nom accessible. | |
| transferButtonForwardAll | aria-label | Fournit un nom accessible. | |
| transferButtonBackward | aria-label | Fournit un nom accessible. | |
| transferButtonBackwardAll | aria-label | Fournit un nom accessible. | |
| 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. |