L'entrée taglist permet aux utilisateurs de rechercher dans une liste d'options et d'appliquer un nombre quelconque de tags. Les utilisateurs peuvent également glisser-déposer les tags pour les réordonner :
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 taglist permet aux utilisateurs de rechercher dans une liste d'options et d'appliquer un nombre quelconque de tags. Les utilisateurs peuvent également glisser-déposer les tags pour les réordonner :
L'entrée de liste de tags 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 actuelle de search :
L'entrée de liste de tags, contrairement aux entrées de type liste déroulante ou autocomplétion, vous permet de saisir une valeur arbitraire (une valeur qui n'est pas dans la liste des options). Cela est utile pour créer de nouveaux tags à la volée. Pour activer cette fonctionnalité, définissez la propriété allow-new-values sur true.
Au lieu de passer une liste statique à la propriété options, vous pouvez lui assigner une fonction. Cela est utile lorsque vous avez besoin de charger des options à partir d'une API ou d'une autre source.
Dans cet exemple, nous allons assigner à la propriété options la fonction searchMovies. En faisant cela, searchMovies recevra l'objet context en argument. Au sein de cet objet context se trouve la propriété search, qui est la valeur de recherche actuelle. Pour effectuer notre recherche, nous utiliserons la valeur search comme paramètre de requête pour notre demande API :
Un scénario probable auquel vous serez confronté est la nécessité de parcourir une API paginée. Cela peut être fait en référençant le même objet context que précédemment. Au sein de cet objet, nous pouvons utiliser les propriétés page et hasNextPage. La propriété page est le numéro de la page actuelle, et la propriété hasNextPage est une fonction à appeler lorsqu'il y a d'autres pages à charger :
Au lieu d'exiger que vos utilisateurs cliquent sur le bouton Charger plus pour charger des options supplémentaires, vous pouvez définir la propriété loadOnScroll sur true, ce qui paginera les options au fur et à mesure que vous défilez vers le bas de la liste des options.
L'entrée taglist 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, nous allons fournir à la taglist une valeur initiale (un identifiant de film), et assigner à optionLoader une fonction qui fera une requête à l'API pour obtenir le film :
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. Le cachedOption est utilisé pour éviter des 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.
Au lieu d'exiger que vos utilisateurs cliquent sur le bouton Charger plus pour charger des options supplémentaires, vous pouvez définir la propriété loadOnScroll sur true, ce qui paginera les options au fur et à mesure que vous défilez vers le bas de la liste des options.
Si vous préférez charger des options lorsque la taglist est créée, vous pouvez définir la propriété load-on-created sur true, et notre fonction, loadCurrentlyPopularMovies, sera appelée sans que l'utilisateur ait besoin de déployer la liste déroulante :
Tout comme l'entrée taglist ou l'entrée Autocomplete, l'entrée taglist vous permet d'utiliser des slots pour personnaliser l'apparence de la liste des options et de l'option sélectionnée en tirant parti du modèle de composant sans rendu.
Dans cet exemple, nous allons utiliser le slot tag pour personnaliser l'apparence des tags :
Par défaut, le champ de saisie taglist ne déploiera pas la liste déroulante lorsqu'aucun résultat de recherche n'est trouvé pendant le filtrage. Vous pouvez changer ce comportement en attribuant à la propriété empty-message un message à afficher lorsqu'aucun résultat n'est trouvé :
La propriété max vous permet de limiter le nombre d'options qui peuvent être sélectionnées. Lorsque la limite max est atteinte, le champ de saisie taglist désactivera la liste déroulante :
Si vous souhaitez que la liste déroulante du taglist reste ouverte entre les sélections, définissez la propriété close-on-select sur false :
Si vous souhaitez que les options soient rechargées (avec des options statiques, cela filtrerait les options avec la valeur de chaîne vide, et avec des options dynamiques, cela ferait une requête au chargeur d'options avec la valeur de chaîne vide) lorsque l'utilisateur valide une sélection, utilisez la propriété reload-on-commit :
Pour activer l'ouverture de la liste déroulante du taglist lors d'un clic sur son champ de recherche, définissez la propriété open-on-click sur true :
Si vous souhaitez ouvrir la liste déroulante du taglist à chaque fois que son champ de recherche est mis au point, définissez la propriété open-on-focus sur true :
Ouvrir lors du focus englobe ouvrir au clic.
Si vous souhaitez que la liste déroulante se déploie lorsqu'une sélection est supprimée, utilisez la propriété open-on-remove :
Maintenant, combinons ce que nous avons appris jusqu'à présent en utilisant le slot tag pour un balisage personnalisé, et en définissant la prop options à une fonction qui retournera des pages de films depuis une API :
| Prop | Type | Par défaut | Description |
|---|---|---|---|
| debounce | number | 200 | Nombre de millisecondes pour temporiser les appels à une fonction options. |
| options | any | [] | La liste des options que l'utilisateur peut sélectionner. |
| load-on-scroll | boolean | false | Lorsque défini à `true`, la taglist essaiera de charger plus d'options en fonction de la position de défilement de l'utilisateur final |
| open-on-click | boolean | false | L'autocomplétion s'ouvre lors du focus sur l'entrée, au lieu d'attendre de s'ouvrir jusqu'à ce qu'une valeur de recherche soit entrée. |
| 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 requête supplémentaire pour charger plus d'informations sur une option sélectionnée. |
| allow-new-values | boolean | false | Permet à l'utilisateur final d'entrer une nouvelle valeur qui n'existe pas dans la liste des options. |
| disable-drag-and-drop | boolean | true | Empêche l'utilisateur final de trier les tags en les glissant et déposant. |
| empty-message | string | undefined | Affiche un message lorsqu'il n'y a pas d'options à afficher. |
| max | number | undefined | Limite le nombre d'options qui peuvent être sélectionnées. |
| close-on-select | boolean | true | Ferme la liste des options lorsqu'une option est sélectionnée. |
| open-on-remove | boolean | false | Lorsque la prop `selection-removable` est définie à `true`, la taglist ne s'ouvrira pas après que la valeur sélectionnée est retirée. Vous pouvez changer ce comportement en définissant la prop `open-on-remove` à `true`. |
| open-on-focus | boolean | false | |
| options-appearance | string | undefined | Pour les taglists multi-sélection, cette prop vous permet de personnaliser l'apparence des options sélectionnées. Les valeurs possibles sont `default` (par défaut) ou `checkbox`. |
| always-load-on-open | boolean | true | Détermine si la taglist doit toujours charger ses options lorsqu'elle est ouverte ou si elle doit se référer aux options qui ont été trouvées précédemment lors de l'ouverture. |
| load-on-created | boolean | false | Lorsque défini à `true`, la taglist chargera les options lorsque le nœud est créé. |
| popover | boolean | false | Affiche la liste des options de l'entrée 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.. |
| Section-key | Description |
|---|---|
| selector | La section sélecteur est un élément bouton qui ouvre la liste des options de la taglist. |
| selections | Contient des sections de sélection individuelles. |
| 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. |
| taglistWrapper | 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 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 la taglist est fermée. |
| 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. |
| removeSelection | Un élément bouton utilisé pour retirer une sélection spécifique. |
| closeIcon | Un élément pour afficher une icône à l'intérieur du bouton removeSelection. |
| listboxButton | Un élément bouton qui est utilisé pour ouvrir la taglist. |
| 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. |
| 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 |
|---|---|---|---|
| input | tabindex | 0 | Priorise l'ordre de focus au clavier en le définissant à 0. |
| role | combobox | Indique aux technologies d'assistance que cet élément fonctionne comme une combobox. | |
| readonly | Restreint les modifications par l'utilisateur, assurant l'intégrité des données et une expérience utilisateur contrôlée et informative. | ||
| aria-autocomplete | list | Oriente les suggestions de saisie, présentant une collection de valeurs qui pourraient compléter la saisie de l'utilisateur. | |
| aria-expanded | Transmet l'état extensible lorsque l'élément est en focus. | ||
| aria-controls | Associe l'élément listbox, à cet élément. | ||
| aria-describedby | Associe un élément à une description, aidant les lecteurs d'écran. | ||
| aria-activedescendant | Gère le focus sur l'élément descendant actif courant. | ||
| listboxButton | tabindex | -1 | Priorise l'ordre de focus au clavier en le définissant à -1. |
| aria-haspopup | true | Signale qu'un élément déclenche un pop-up ou un menu | |
| aria-expanded | Transmet l'état extensible lorsque l'élément est en focus. | ||
| aria-controls | Associe l'élément listbox, à cet élément. | ||
| tagWrapper | tabindex | -1 | Priorise l'ordre de focus au clavier en le définissant à -1. |
| tag | role | button | Indique aux technologies d'assistance que cet élément fonctionne comme un bouton. |
| tags | aria-live | polite | Communique les changements de contenu dynamique lorsque les sélections sont à l'écran. |
| removeSelection | tabindex | -1 | Supprime la priorisation du focus au clavier sur cet élément. |
| aria-controls | Associe l'élément de saisie, à cet élément. | ||
| 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. |