# FormFileUpload : déclencher un import de fichier hors média WordPress
> Un bloc qui importe un CSV de configuration n'a rien à faire dans la médiathèque WordPress. FormFileUpload ouvre un sélecteur de fichier natif du système, sans passer par la bibliothèque.
- Auteur : WordPress Développement
- Publié le : 2026-10-02
- Mis à jour le : 2026-09-30
- Catégorie : Blocs Gutenberg
- URL : https://www.wpmoderne.fr/blocs/formfileupload-import-fichier-hors-media/
## L’essentiel
- render personnalise entièrement le bouton déclencheur, un accès natif reste requis derrière
- accept filtre les extensions proposées, sans empêcher un contournement côté utilisateur
- onChange reçoit une FileList, pas un tableau JavaScript classique
## Un bloc qui a besoin d'un fichier, sans que ce fichier ne devienne un média
La médiathèque de WordPress convient parfaitement à une image, une vidéo ou un document destiné à être affiché sur le site. Elle convient nettement moins à un fichier de configuration, un CSV de correspondance de données, ou un export ponctuel qu'un bloc doit simplement lire une fois pour en extraire une information, sans jamais l'exposer publiquement ni le conserver comme pièce jointe. `FormFileUpload`, composant de `@wordpress/components`, répond précisément à ce second cas : il ouvre le sélecteur de fichier natif du système d'exploitation, sans jamais transiter par la bibliothèque de médias de WordPress.
```
import { FormFileUpload } from '@wordpress/components';
function ImportCsvConfiguration( { onFichierChoisi } ) {
return (
{
const fichier = event.target.files[ 0 ];
if ( fichier ) {
onFichierChoisi( fichier );
}
} }
>
Importer un fichier CSV
);
}
```
## onChange reçoit un événement natif, avec une FileList, pas un tableau
> L'essentiel à retenir : render personnalise entièrement le bouton déclencheur, un accès natif reste requis derrière ; accept filtre les extensions proposées, sans empêcher un contournement côté utilisateur ; onChange reçoit une FileList, pas un tableau JavaScript classique
Un piège fréquent pour un développeur habitué aux composants de `@wordpress/components` qui transmettent directement une valeur simplifiée à `onChange` (comme `TextControl` ou `ToggleControl`) : `FormFileUpload` transmet en réalité un événement DOM natif, exactement comme un `` classique. La liste des fichiers sélectionnés se récupère donc via `event.target.files`, une `FileList`, une structure proche d'un tableau mais qui n'en possède pas toutes les méthodes natives comme `.map()` directement.
```
{ /* Incorrect : FileList n'a pas .map() nativement dans tous les environnements */ }
onChange={ ( event ) => {
event.target.files.map( ( fichier ) => console.log( fichier.name ) );
} }
{ /* Correct : conversion explicite en tableau avant manipulation */ }
onChange={ ( event ) => {
Array.from( event.target.files ).forEach( ( fichier ) => {
console.log( fichier.name );
} );
} }
```
## accept filtre l'affichage du sélecteur, jamais une garantie côté serveur
La prop `accept` transmet une contrainte au sélecteur de fichier natif du système d'exploitation, qui masque par défaut les fichiers ne correspondant pas à l'extension ou au type MIME indiqué. C'est une aide ergonomique réelle, mais absolument pas une garantie de sécurité : un utilisateur peut toujours choisir « Tous les fichiers » dans la fenêtre native, ou renommer un fichier pour contourner ce filtre visuel.
- toute validation réelle du contenu du fichier doit se faire côté serveur, après réception, jamais uniquement côté navigateur
- `accept` accepte une liste d'extensions séparées par des virgules, comme `".csv,.json"`, ou des types MIME comme `"text/csv"`
- un fichier accepté par le filtre visuel peut malgré tout contenir un contenu corrompu ou d'un format différent de son extension, une vérification du contenu réel reste indispensable après upload
## render : personnaliser entièrement l'apparence sans perdre l'accessibilité native
Par défaut, `FormFileUpload` affiche un bouton standard de `@wordpress/components`. La prop `render` permet de remplacer entièrement cet affichage par un élément personnalisé, tout en conservant le comportement d'ouverture du sélecteur de fichier natif attaché à cet élément.
```
(
) }
/>
```
Le paramètre reçu par la fonction `render`, ici déstructuré en `openFileDialog`, doit impérativement être relié à un déclencheur véritablement interactif (bouton, lien), sous peine de rendre le sélecteur de fichier inaccessible au clavier si l'élément personnalisé ne peut pas recevoir le focus.
> Un fichier de configuration qui atterrit dans la médiathèque du site n'est ni un média, ni vraiment un déchet : c'est une pièce jointe orpheline que personne ne pensera jamais à nettoyer.
## Quand FormFileUpload n'est pas le bon choix
Pour tout fichier destiné à être affiché ou réutilisé sur le site (image, vidéo, document public), la médiathèque WordPress reste la solution appropriée, via `MediaUpload` ou `MediaPlaceholder` : elle gère la génération des tailles d'image, l'indexation, et la réutilisation entre plusieurs contenus, ce que `FormFileUpload` ne fait jamais. Ce dernier se réserve strictement aux fichiers à usage technique ponctuel, lus côté serveur puis généralement écartés ou transformés, sans jamais devenir un média du site.
Enfin, pour un import de fichier volumineux nécessitant un découpage en plusieurs morceaux ou une barre de progression détaillée, `FormFileUpload` ne fournit lui-même aucun mécanisme de suivi de transfert : il faut construire cette logique séparément, généralement avec l'API native de progression d'upload du navigateur.
## En résumé
`FormFileUpload` ouvre un sélecteur de fichier natif sans passer par la médiathèque, à condition de bien comprendre que `onChange` transmet un événement natif avec une `FileList`, que `accept` ne garantit rien côté sécurité, et que `render` permet une personnalisation complète tant que l'accessibilité du déclencheur reste préservée.