Le champ autocomplete vous permet de rechercher dans une liste d'options.
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 les options comme un tableau vide, le champ sera rendu dans un état désactivé.
Par défaut, le champ d'autocomplétion sera rendu en mode de sélection unique :
En définissant la propriété multiple, le champ d'autocomplétion sera rendu 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.
Le champ d'autocomplétion 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 :
Au lieu de passer une liste statique à la propriété options, vous pouvez lui assigner une fonction. Cela est utile lorsque vous devez 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 contexte se trouve la propriété search, qui est la valeur de recherche actuelle. Pour effectuer notre recherche, nous utiliserons la valeur de recherche comme paramètre de requête pour notre demande API :
Un scénario courant auquel vous serez confronté est la nécessité de parcourir une API paginée. Cela peut être réalisé 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 correspond au numéro de la page actuelle, et la propriété hasNextPage est une fonction à appeler lorsqu'il y a d'autres pages à charger :
Le champ de saisie automatique de FormKit fournit également une propriété optionLoader qui vous permet de réhydrater des valeurs qui ne figurent pas dans la liste des options. Dans cet exemple, nous fournirons à l'autocomplétion une valeur initiale (un identifiant de film), et nous assignerons l'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. 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.
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 à 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 les options lorsque l'autocomplétion est créée, vous pouvez définir la propriété load-on-created à true, et notre fonction, loadCurrentlyPopularMovies, sera appelée sans que l'utilisateur ait besoin de déployer la liste déroulante :
Le champ de saisie automatique 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 :
Le champ de saisie automatique vous permet de personnaliser l'apparence de l'option sélectionnée.
L'entrée d'autocomplétion vous permet de personnaliser l'apparence de l'option sélectionnée en utilisant la propriété selection-appearance. Pour l'autocomplétion en sélection simple ou multiple, vous pouvez définir la propriété selection-appearance à text-input (par défaut) ou option :
Si vous souhaitez uniquement personnaliser l'affichage de l'option sélectionnée, définissez l'apparence de sélection sur option.
Par défaut, l'entrée d'autocomplétion ne déploiera pas la liste déroulante lorsqu'aucun résultat de recherche n'est trouvé lors du filtrage. Vous pouvez changer ce comportement en attribuant à la propriété empty-message un message à afficher lorsqu'aucun résultat n'est trouvé :
Si vous souhaitez que la liste déroulante reste déployée après avoir sélectionné une valeur, vous pouvez définir close-on-select sur false.
Si vous souhaitez que les options soient rechargées lorsque l'utilisateur valide une sélection, utilisez la propriété reload-on-commit :
Pour activer l'ouverture de la liste déroulante de l'autocomplétion au clic sur son champ de recherche, définissez la propriété open-on-click sur true :
Si vous souhaitez ouvrir la liste déroulante de l'autocomplétion chaque fois que le champ est cliqué, définissez la propriété open-on-focus sur true :
Si open-on-focus est utilisé, open-on-click sera implicitement défini.
Uniquement pour les autocomplétions à sélection unique, si vous souhaitez effacer l'entrée de recherche lorsque la liste déroulante est ouverte, définissez la propriété clear-search-on-open :
Pour une autocomplétion à sélection unique, vous pouvez définir la propriété selection-removable. Lorsqu'elle est définie sur true, un bouton de suppression sera affiché à côté de l'option sélectionnée. Cette propriété est par défaut définie sur true pour les autocomplétions avec une apparence de sélection de type option.
La propriété selection-removable ne peut pas être utilisée pour les sélections multiples.
Si vous souhaitez que la liste déroulante s'étende lorsqu'une sélection est supprimée, utilisez la propriété open-on-remove :
Si vous souhaitez limiter le nombre d'options qui peuvent être sélectionnées, vous pouvez utiliser la propriété max :
Maintenant, combinons ce que nous avons appris jusqu'à présent en utilisant l'emplacement option pour un balisage personnalisé, et en définissant la propriété options sur une fonction qui retournera des pages de films à partir d'une API :
| 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. |
| load-on-scroll | boolean | false | Lorsqu'elle est définie sur `true`, l'autocomplétion essaiera de charger plus d'options en fonction de la position de défilement de l'utilisateur final |
| selection-appearance | string | text-input | Change la manière dont l'étiquette de l'option est affichée. |
| multiple | boolean | false | Permet plusieurs sélections. |
| open-on-click | boolean | false | L'autocomplétion s'étend lors de la mise au point de l'entrée, au lieu d'attendre de s'étendre 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 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. |
| max | number | undefined | Limite le nombre d'options qui peuvent être sélectionnées. |
| open-on-remove | boolean | false | Lorsque la propriété `selection-removable` est définie sur `true`, l'autocomplétion 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`. |
| open-on-focus | boolean | false | |
| options-appearance | string | undefined | Pour les autocomplétions à sélections multiples, 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`. |
| always-load-on-open | boolean | true | Détermine si l'autocomplétion doit toujours charger ses options lorsqu'elle est ouverte ou si elle doit se référer aux options qui ont été précédemment trouvées lors de l'ouverture. |
| load-on-created | boolean | false | Lorsqu'elle est définie sur `true`, l'autocomplétion chargera les options lorsque le nœud sera créé. |
| clear-search-on-open | boolean | false | Lorsqu'elle est définie sur `true`, l'entrée de recherche sera effacée lorsque la liste déroulante sera ouverte. |
| 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 sélections multiples). |
| popover | boolean | false | Affiche la liste déroulante 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.. |
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.
La structure de l'autocomplétion change selon différents scénarios :
selection-appearance est défini sur text-input (par défaut) ou option.multiple.text-inputoption, sélection uniqueoption, sélection multipleCi-dessous se trouve la structure des options internes (listbox) issue des diagrammes ci-dessus :
| Section-key | Description |
|---|---|
| selector | La section sélecteur est un élément bouton qui ouvre la liste déroulante des options. |
| selections | Contient les 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 | 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 lors du chargement. |
| loaderIcon | Un élément pour afficher une icône dans l'élément sélecteur lors du chargement. |
| selectIcon | Un élément pour afficher une icône dans l'élément sélecteur lorsque la liste déroulante 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 liste déroulante. |
| 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 | -1 ou 0 | Priorise l'ordre de focus au clavier en le réglant sur -1 lorsqu'il est désactivé et 0 lorsqu'il est activé. |
| 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 | Guide les suggestions de saisie, présentant une collection de valeurs qui pourraient compléter la saisie de l'utilisateur. | |
| aria-activedescendant | Gère le focus sur l'élément descendant actif courant. | ||
| aria-expanded | Transmet l'état extensible lorsque l'élément est au focus. | ||
| aria-controls | Associe l'élément listbox, avec cet élément. | ||
| listboxButton | tabindex | -1 ou 0 | Priorise l'ordre de focus au clavier en le réglant sur -1 lorsqu'il est désactivé et 0 lorsqu'il est activé. |
| role | button | Indique aux technologies d'assistance que cet élément fonctionne comme un bouton. | |
| 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 au focus. | ||
| aria-controls | Associe l'élément listbox, avec cet élément. | ||
| aria-disabled | Communique l'état désactivé lorsque l'entrée est désactivée. | ||
| selectionWrapper | tabindex | -1 ou 0 | Priorise l'ordre de focus au clavier en le réglant sur -1 lorsqu'il est désactivé et 0 lorsqu'il est activé. |
| selections | aria-live | polite | Communique les changements de contenu dynamique lorsque les sélections sont à l'écran. |
| removeSelection | tabindex | -1 | Supprime la priorisation du focus clavier sur cet élément. |
| aria-controls | Associe l'élément de saisie, avec 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. |