L'entrée autocomplete vous permet de rechercher dans une liste d'options.
La propriété 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é.
Par défaut, l'entrée autocomplete sera rendue en mode de sélection unique :
En définissant la propriété multiple, l'entrée autocomplete sera rendue 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.
L'entrée autocomplete 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 search actuelle :
Au lieu de passer une liste statique à la propriété options, vous pouvez l'attribuer à 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 attribuer à la propriété options la fonction searchMovies. En faisant cela, searchMovies recevra l'objet context en argument. Dans 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 probable que vous rencontrerez est la nécessité de rechercher à travers une API paginée. Cela peut être fait en référençant le même objet context qu'auparavant. Dans cet objet, nous pouvons utiliser les propriétés page et hasNextPage. La propriété page est le numéro de page actuel, et la propriété hasNextPage est une fonction à appeler lorsqu'il y a plus de pages à charger :
L'entrée d'auto-complétion 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, nous fournirons à l'auto-complétion une valeur initiale (un ID 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 valeur de l'option sélectionnée (dans ce cas, l'ID du film) et l'option en cache. La prop option en cache est utilisée pour éviter les recherches inutiles. Si l'option en cache n'est pas null, cela signifie que l'option sélectionnée a déjà été chargée, et vous pouvez retourner directement l'option en cache.
Au lieu d'exiger que vos utilisateurs cliquent sur le bouton Charger plus pour charger des options supplémentaires, vous pouvez définir la prop loadOnScroll sur true, ce qui paginera les options lorsque vous défilerez jusqu'au bas de la liste des options.
Si vous préférez charger les options lorsque l'auto-complétion est créée, vous pouvez définir la prop load-on-created sur true, et notre fonction, loadCurrentlyPopularMovies sera appelée sans que l'utilisateur ait besoin d'élargir la liste :
L'entrée d'auto-complétion 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'entrée d'auto-complétion vous permet de personnaliser l'apparence de l'option sélectionnée.
L'input 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 à sélection unique 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 la sélection sur option.
Par défaut, l'input d'autocomplétion n'élargira pas la liste déroulante lorsqu'aucun résultat de recherche n'est trouvé lors du filtrage. Vous pouvez modifier 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 la sélection d'une valeur, vous pouvez définir close-on-select sur false.
Si vous voulez 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 input 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 l'input 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.
Pour les autocomplétions à sélection unique uniquement, si vous souhaitez effacer l'input de recherche lorsque la liste déroulante est ouverte, définissez la propriété clear-search-on-open :
Pour un autocomplete à 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 autocompletes avec une apparence de sélection option.
La propriété selection-removable ne peut pas être utilisée pour les sélections multiples.
Si vous voulez que la liste se déploie 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 le slot option pour un balisage personnalisé, et en définissant la propriété options à 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 différer les appels à une fonction d'options. |
| options | any | [] | La liste des options que l'utilisateur peut sélectionner. |
| load-on-scroll | boolean | false | Lorsqu'il est défini sur `true`, l'autocomplete 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 façon dont l'étiquette de l'option est affichée. |
| multiple | boolean | false | Permet de faire plusieurs sélections. |
| open-on-click | boolean | false | L'autocomplete est déployé lors de la mise au point de l'entrée, au lieu d'attendre pour se déployer jusqu'à ce qu'une valeur de recherche soit entrée. |
| 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. |
| 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'autocomplete 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 autocompletes à sélection multiple, 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 | false | Lorsqu'il est défini sur `true`, l'autocomplete chargera toujours les options lorsque la liste est ouverte. |
| load-on-created | boolean | false | Lorsqu'il est défini sur `true`, l'autocomplete chargera les options lorsque le nœud est créé. |
| clear-search-on-open | boolean | false | Lorsqu'il est défini sur `true`, l'entrée de recherche sera effacée lorsque la liste est 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 à la sélection multiple). |
| 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 en fonction de quelques scénarios différents :
selection-appearance a été défini sur text-input (par défaut) ou option.multiple.text-inputoption, sélection uniqueoption, sélection multipleCi-dessous se trouve la structure de la liste d'options interne (listbox) des diagrammes ci-dessus :
| Section-key | Description |
|---|---|
| selector | La section sélecteur est un élément bouton qui ouvre la liste d'options déroulantes. |
| selections | Contient des sections de sélection individuelles. |
| 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 d'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é. |
| loadMore | Un élément de liste qui est rendu conditionnellement au bas de la liste d'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. |
| removeSelection | Un élément bouton utilisé pour supprimer 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 le menu déroulant. |
| 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. |
| 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. |