L'entrée file utilise l'entrée de fichier native HTML. Elle permet aux utilisateurs de sélectionner des fichiers depuis leur appareil pour les télécharger. En plus des fonctionnalités d'entrée natives, elle ajoute le support pour :
La valeur du type file doit toujours être un tableau d'objets où chaque objet contient un name (chaîne de caractères) et une propriété file (File) optionnelle. Lors de la sélection de nouveaux fichiers depuis l'appareil d'un utilisateur, FormKit convertira la FileList native en la structure basée sur un tableau requise automatiquement.
Cette structure peut être utilisée pour pré-remplir une entrée de fichier avec des valeurs de fichiers précédemment téléchargés :
Pré-remplir une entrée avec des noms de fichiers est uniquement à des fins d'affichage. C'est une fonctionnalité optionnelle qui fournit une interface cohérente pour indiquer qu'un fichier a été précédemment téléchargé — cependant — une FileList n'est pas attachée à la balise <input> réelle pour le téléchargement.
Le processus de téléchargement de fichiers est laissé à la gestion de soumission de votre formulaire. Lors de la soumission du formulaire via une requête de page complète, aucun traitement supplémentaire n'est nécessaire, cependant lors de la soumission via une requête XHR/Fetch, vous devrez créer une instance de FormData avec les fichiers joints. Voici un exemple fonctionnel :
L'entrée file a quelques props uniques. Il y a aussi plusieurs attributs HTML natifs couramment utilisés qui aident à contrôler les téléchargements de fichiers.
| Prop | Type | Par défaut | Description | ||
|---|---|---|---|---|---|
| Commonly used native attributes | |||||
| accept | -- | -- | Voir sur MDN | ||
| capture | -- | -- | Voir sur MDN | ||
| multiple | -- | -- | Voir sur MDN | ||
| webkitdirectory | -- | -- | Voir sur MDN | ||
| Props | |||||
| file-item-icon | String | ’’ | Spécifie une icône à placer dans la section fileItemIcon. S'affiche uniquement lorsqu'un fichier est sélectionné. Par défaut, c'est l'icône fileDoc. | ||
| file-remove-icon | String | ’’ | Spécifie une icône à placer dans la section fileRemoveIcon. S'affiche uniquement lorsqu'un fichier est sélectionné. Par défaut, c'est l'icône close. | ||
| no-files-icon | String | ’’ | Spécifie une icône à placer dans la section noFilesIcon. S'affiche uniquement lorsqu'aucun fichier n'est sélectionné. Par défaut, c'est l'icône fileDoc. | ||
| 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.
| Section-key | Description |
|---|---|
| fileList | Un conteneur pour la liste complète des fichiers. |
| fileItemIcon | Un élément contenant une icône de fileItem optionnelle. |
| fileItem | Un élément contenant le fileName et l'action de suppression pour chaque fichier. |
| fileName | L'élément contenant le nom d'un fichier. |
| fileRemove | L'élément qui supprime un fichier de la liste. |
| fileRemoveIcon | Un élément contenant l'icône de suppression de fichier. |
| noFiles | L'élément affiché lorsqu'aucun fichier n'est sélectionné. |
| noFilesIcon | Un élément contenant une icône dans la section noFiles. |
| 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 |
|---|---|---|---|
| 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. |