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 (
<FormFileUpload
accept=".csv"
onChange={ ( event ) => {
const fichier = event.target.files[ 0 ];
if ( fichier ) {
onFichierChoisi( fichier );
}
} }
>
Importer un fichier CSV
</FormFileUpload>
);
}onChange reçoit un événement natif, avec une FileList, pas un tableau
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 <input type="file"> 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
acceptaccepte 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.
<FormFileUpload
accept=".csv"
onChange={ gererImport }
render={ ( { openFileDialog } ) => (
<Button variant="secondary" icon="upload" onClick={ openFileDialog }>
Choisir un fichier de configuration
</Button>
) }
/>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.
