Sélecteur de fichiers
Le frère en zone de dépôt de VFileInput : une surface plutôt qu'un champ, avec les mêmes règles de filtrage et la même liste de fichiers en valeur.
Utilisation
Exemples
Titre et sous-titre
title est obligatoire et subtitle est l'endroit où écrire les règles en clair. Les deux ont un slot, qui n'accepte que du texte et des éléments en ligne.
La liste des fichiers
preview dit où va la liste des fichiers choisis, sous la zone ou à côté, ou la retire. À côté, elle repasse dessous dès que le composant est étroit.
Icônes personnalisées
icon est le grand glyphe en haut de la zone. typeIcons remplace le glyphe affiché par une ligne pour un type de fichier, en ne nommant que les types à changer, et removeIcon celui du bouton qui retire une ligne.
Vignettes
Une image est affichée telle quelle, par une adresse temporaire créée dans la page. hideThumbnails affiche à la place l'icône de son type.
Fichiers multiples
multiple permet à la zone de prendre plusieurs fichiers, les suivants étant écartés sinon. La valeur est une liste dans les deux cas, et reject est émis une fois par fichier refusé.
Types acceptés
accept accepte la syntaxe du navigateur et filtre la boîte de dialogue système comme un fichier déposé. Un fichier qui échoue revient par reject avec la raison type.
Taille maximale
maxSize est la taille maximale d'un fichier, en octets. Chacun est pesé séparément.
Taille totale et nombre
maxTotalSize et maxFiles bornent la sélection dans son ensemble, en comptant ce qui est déjà dans la liste. Le filtrage suit un ordre fixe : type, puis taille, puis nombre, puis taille totale.
États
readonly montre ce qui a été pris sans rien laisser changer, boutons de retrait compris. disabled grise la zone et l'empêche d'accepter quoi que ce soit, y compris en cours de glisser.
API
Props
| Prop | Type | Défaut |
|---|---|---|
title | string | aucune |
| Ce qu'on demande au lecteur de déposer, en une ligne. C'est OBLIGATOIRE : une zone de dépôt sans consigne n'est qu'un rectangle. Elle masque l'attribut HTML du même nom, compromis accepté. | ||
subtitle | string | aucune |
| Une seconde ligne dessous, pour les contraintes en clair : genres, tailles, nombre. | ||
icon | IconSource | cloud_upload |
| La grande icône en haut de la zone. | ||
hideBrowse | boolean | false |
| Masque le séparateur et le bouton de parcours sous la consigne. Cela change la NATURE de la zone : elle devient alors le contrôle elle-même, un vrai bouton, si bien qu'Entrée, Espace et le focus viennent de la plateforme plutôt que d'un conteneur qui se contente de réagir aux clics. | ||
browseText | string | aucune |
| Le texte affiché sur le bouton de parcours, qui lui sert aussi de nom accessible. Il retombe sur le dictionnaire du design system. | ||
preview | FilePickerPreviewfalse | 'bottom' | 'end' | false |
| Où les fichiers pris sont listés : sous la zone, ou à côté, auquel cas la liste repasse dessous quand le COMPOSANT est étroit, en suivant la largeur qu'on lui a donnée et non celle de la fenêtre. Par défaut, rien n'est listé du tout. | ||
hideThumbnails | boolean | false |
| Affiche l'icône de genre pour chaque fichier de cette liste, images comprises : la porte de sortie quand une liste contient beaucoup d'images, ou de très grandes. Sans lui, une image est montrée en vignette : elle reçoit une adresse temporaire, créée dans le navigateur seulement et libérée dès que le fichier quitte la liste ou que le composant disparaît. | ||
typeIcons | Partial<Record<FilePickerKind, IconSource>> | aucune |
| Remplace l'icône d'un ou plusieurs genres de fichiers. | ||
removeIcon | IconSource | close |
| L'icône du bouton qui retire un fichier de la liste. | ||
multiple | boolean | false |
| Permet de prendre plusieurs fichiers. Avec un seul, tout fichier supplémentaire est écarté. | ||
accept | string | aucune |
| Quels genres de fichiers sont acceptés, dans la syntaxe du navigateur. C'est appliqué deux fois : en attribut, ce qui filtre la boîte de dialogue du système, et de nouveau en code, seule chose capable de filtrer un fichier déposé. | ||
maxSize | number | aucune |
| La taille maximale d'UN fichier, en octets. | ||
maxTotalSize | number | aucune |
| La taille maximale de toute la sélection, en octets. | ||
maxFiles | number | aucune |
| Combien de fichiers peuvent être pris au plus. | ||
disabled | boolean | false |
| Rend la zone inutilisable, grisée par les tokens de couleur. | ||
readonly | boolean | false |
| Montre ce qui a été pris sans permettre de le changer : ni boîte de dialogue, ni dépôt, ni retrait. Ses boutons restent atteignables au clavier, annoncés comme indisponibles. | ||
invalid | boolean | false |
| Marque la zone comme invalide, ce qui colore son contour et s'annonce sur le contrôle que l'on atteint. C'est pour une règle à vous : rien ici n'est vérifié par le navigateur, le vrai champ étant masqué. | ||
loading | boolean | false |
| Affiche un indicateur à la place de l'icône de la zone, typiquement pendant un envoi. Il dit que quelque chose se passe et ne change rien d'autre : les fichiers peuvent toujours être déposés et la boîte de dialogue s'ouvre encore. | ||
loadingText | string | aucune |
| Ce que les lecteurs d'écran annoncent pendant que l'indicateur tourne. Sa valeur par défaut vient du dictionnaire du design system. | ||
v-model | File[] | [] |
| Toujours une LISTE de fichiers, que plusieurs soient permis ou non, jamais un fichier seul. La forme ne dépend pas d'une prop : vous n'avez donc jamais à restreindre une union que TypeScript ne sait pas discriminer. | ||
Événements
| Événement | Type |
|---|---|
change | [files: File[]] |
| La sélection a changé, avec toute la liste telle qu'elle est désormais. | |
reject | [rejection: FileRejection] |
| Un fichier a été écarté, avec lequel et pourquoi. | |
remove | [file: File, index: number] |
| Un fichier a été retiré de la liste, avec lequel et où il se trouvait. | |
Slots
| Slot | Type |
|---|---|
icon | {} |
| La grande icône, pour une illustration que la prop ne peut pas exprimer. Elle doit rester non interactive, et les deux suivantes aussi : avec le bouton de parcours masqué, la zone EST un bouton, et rien d'interactif ne peut se trouver dans un bouton. | |
title | {} |
| La consigne. Texte et éléments en ligne seulement, pour la même raison. | |
subtitle | {} |
| La seconde ligne. Même contrat que la consigne. | |
browse | FilePickerBrowseSlotProps |
Le bouton de parcours. Appelez le open qu'il reçoit : sans lui, un bouton à vous ne pourrait plus ouvrir la boîte de dialogue du tout. | |
item | FilePickerRow |
| TOUTE une ligne de la liste, la porte de sortie pour une ligne montrant sa propre progression d'envoi. Elle reçoit tout ce qu'avait la ligne standard. | |
thumbnail | FilePickerRow |
| Le carré en début de ligne seulement : pour une vignette produite par votre serveur, l'image d'accroche d'une vidéo, ou un format que le navigateur ne sait pas décoder. | |
remove | FilePickerRemoveSlotProps |
Le contrôle qui retire une ligne. remove est la seule chose qui peut sortir le fichier, et removeLabel est le nom accessible tout prêt, celui du fichier compris, sans lequel le bouton ne serait annoncé comme rien du tout. | |
Types
Les types que les tables ci-dessus nomment, écrits comme la librairie les déclare. Ceux qui portent export s'importent depuis vectis-ui pour typer votre propre code ; les autres décrivent la forme de ce qu'un slot fournit.
export interface BuiltinIcon {
name: string
paths: readonly [string] | readonly [string, string]
}export interface FilePickerBrowseSlotProps {
open: () => void
disabled: boolean
}export type FilePickerKind = 'image' | 'pdf' | 'audio' | 'video' | 'archive' | 'spreadsheet' | 'code' | 'file'
export interface FilePickerRemoveSlotProps {
file: File
index: number
remove: () => void
removeLabel: string
}export interface FilePickerRow {
file: File
index: number
kind: FilePickerKind
thumbnail: string | undefined
icon: IconSource
sizeText: string
remove: () => void
}export type FileRejectReason = 'type' | 'size' | 'count' | 'total-size'
export interface FileRejection {
file: File
reason: FileRejectReason
}export type IconRender =
| { path: string; viewBox?: string }
| { component: Component; props?: Record<string, unknown> }
| { src: string }
| { text: string; class?: string }
| { class: string }export type IconSource = string | BuiltinIcon | IconRender
Variables CSS
| Token | Valeur |
|---|---|
--vectis-control-size-file-picker-min-block | 10rem |
--vectis-control-size-file-picker-icon | 2.5rem |
--vectis-control-size-file-picker-thumb | 2.5rem |