Aller au contenu principal

Introduction

Téléchargez et gérez des fichiers dans le stockage cloud avec optimisation automatique.

🎯 Que fait ce module ?​

Le module FileUploading vous permet de télécharger, récupérer et supprimer des fichiers dans le stockage cloud OneEntry - images, PDF, vidéos, documents et tout type de fichier avec optimisation automatique et livraison CDN.

Considérez-le comme votre gestionnaire de stockage cloud - vous téléchargez des fichiers une fois, et OneEntry les stocke, optimise automatiquement les images et les sert rapidement via le CDN.

📖 Explication Simple​

Imaginez que vous construisez une application où les utilisateurs peuvent :

  • 📸 Télécharger des photos de profil - redimensionnement et optimisation automatiques
  • 📄 Télécharger des documents - stocker des PDF, DOC en toute sécurité
  • 🖼️ Télécharger des images de produits - plusieurs images par produit
  • 🎥 Télécharger des vidéos - stocker et diffuser du contenu vidéo
  • 📎 Télécharger des pièces jointes - tout type de fichier

Au lieu de gérer votre propre stockage :

  • ✅ Téléchargez des fichiers dans le cloud OneEntry
  • ✅ Optimisation automatique des images (redimensionnement, compression)
  • ✅ Livraison CDN rapide dans le monde entier
  • ✅ Organisez par type d'entité (produit, utilisateur, page)
  • ✅ Obtenez des URL de téléchargement instantanément
  • ✅ Supprimez les fichiers lorsqu'ils ne sont plus nécessaires

Exemple du monde réel :

Sans FileUploading (manuel) :
- Configurer un bucket AWS S3 ❌
- Configurer le CDN ❌
- Écrire du code d'optimisation d'image ❌
- Gérer les autorisations de fichiers ❌
- Générer des URL signées ❌

Avec FileUploading (automatique) :
- Télécharger le fichier → Obtenir l'URL de téléchargement ✅
- Images auto-optimisées ✅
- Livraison CDN intégrée ✅
- Gestion facile des fichiers ✅

✨ Concepts Clés​

Qu'est-ce que le Téléchargement de Fichiers ?​

Le téléchargement de fichiers consiste à stocker des fichiers dans le stockage cloud :

  • Télécharger - Envoyer le fichier dans le cloud OneEntry
  • Stockage - Fichiers stockés en toute sécurité dans le cloud
  • CDN - Livraison rapide depuis des serveurs proches des utilisateurs
  • Optimisation - Images auto-compressées et redimensionnées
  • URL - Obtenez un lien de téléchargement permanent

Types de Fichiers Supportés​

Téléchargez tout type de fichier :

CatégorieTypes de FichiersAuto-Optimisation
ImagesJPG, PNG, GIF, WebP, SVGOui (redimensionner, compresser)
DocumentsPDF, DOC, DOCX, XLS, XLSXNon (stocké tel quel)
VidéosMP4, MOV, AVI, WebMNon (stocké tel quel)
ArchivesZIP, RAR, TAR, GZNon (stocké tel quel)
AutresTout type de fichierNon (stocké tel quel)

Optimisation d'Image​

Lors du téléchargement d'images, OneEntry peut :

  • 📐 Redimensionner - Réduire les dimensions (par exemple, largeur max 1920px)
  • 🗜️ Compresser - Réduire la taille du fichier (plus petit, plus rapide)
  • 🖼️ Format - Convertir au format optimal (WebP)
  • 📱 Réactif - Créer plusieurs tailles

Exemple :

Original : 5MB, 4000x3000px
↓ (auto-optimiser)
Optimisé : 200KB, 1920x1440px

📋 Ce Que Vous Devez Savoir​

Paramètres de Téléchargement​

Lors du téléchargement de fichiers, vous pouvez spécifier :

await FileUploading.upload(file, {
  entity: 'product',     // Type d'entité (obligatoire)
  id: 123,               // ID d'entité (facultatif)
  type: 'image',         // Indice de type de fichier (facultatif)
  width: 1920,           // Largeur max pour les images (facultatif)
  height: 1080,          // Hauteur max pour les images (facultatif)
  compress: true         // Compresser les images (facultatif)
});

Paramètres expliqués :

  • file - L'objet fichier (provenant de l'entrée ou du glisser-déposer)
  • entity - Catégorie : product, page, block, user, form, general
  • id - ID d'entité à associer au fichier (par exemple, ID de produit)
  • type - Indice de type de fichier (généralement détecté automatiquement)
  • width - Largeur max en pixels (images uniquement)
  • height - Hauteur max en pixels (images uniquement)
  • compress - Activer la compression (images uniquement)

Réponse de Téléchargement​

Après le téléchargement, vous obtenez :

{
  filename: "abc123-photo.jpg",              // Nom de fichier unique
  downloadLink: "https://cdn.../photo.jpg",  // URL CDN
  size: 204800,                              // Taille du fichier (octets)
}

Champs importants :

  • downloadLink - Utilisez cette URL dans les balises <img>, <a>, <video>
  • filename - Enregistrez ceci pour supprimer le fichier plus tard
  • size - Taille du fichier en octets (204800 octets = 200KB)

Meilleures Pratiques d'Organisation des Fichiers​

Organisez les fichiers par type d'entité

Options d'Optimisation d'Image​

Contrôlez comment les images sont optimisées :

OptionCe Qu'elle FaitExemple
widthLargeur max (maintient le ratio d'aspect)width: 1920
heightHauteur max (maintient le ratio d'aspect)height: 1080
compressRéduire la taille du fichiercompress: true

Le ratio d'aspect est préservé :

Original : 4000x3000 (ratio 4:3)
Avec largeur : 800
Résultat : 800x600 (toujours ratio 4:3)

Suppression de Fichiers​

Fournissez toujours l'entité, l'id et le nom de fichier pour supprimer :

await FileUploading.delete({
  entity: 'product',
  id: productId,
  filename: 'abc123-photo.jpg'
});

Pourquoi les trois ? Les fichiers sont organisés par entité → id → nom de fichier.

📊 Tableau de Référence Rapide - Méthodes​

MéthodeCe Qu'elle FaitQuand l'utiliser
upload()Télécharger un fichier dans le stockage cloudL'utilisateur télécharge une image, un document
getFile()Obtenir des informations sur le fichier (taille, type, URL)Vérifier si le fichier existe
delete()Supprimer un fichier du stockageSupprimer des fichiers anciens

❓ Questions Fréquemment Posées (FAQ)​

Quels types de fichiers puis-je télécharger ?​

Tout type de fichier est supporté :

  • Images : JPG, PNG, GIF, WebP, SVG, BMP, TIFF
  • Documents : PDF, DOC, DOCX, XLS, XLSX, PPT, TXT
  • Vidéos : MP4, MOV, AVI, WebM, MKV
  • Archives : ZIP, RAR, TAR, GZ
  • Autres : Tout type de fichier

Seules les images sont auto-optimisées. Les autres fichiers sont stockés tels quels.

Quelle est la taille maximale des fichiers ?​

Vérifiez les limites de votre plan OneEntry. Typiquement :

  • Plan gratuit : 5MB par fichier
  • Plans payants : 50MB - 100MB par fichier

Meilleure pratique : Optimisez les images avant de les télécharger pour réduire la taille.

Les fichiers sont-ils stockés de manière permanente ?​

Oui, les fichiers sont stockés jusqu'à ce que vous les supprimiez manuellement en utilisant FileUploading.delete().

Important : Nettoyez les fichiers inutilisés pour économiser de l'espace de stockage.

Puis-je télécharger des fichiers depuis le frontend (navigateur) ?​

Oui ! Utilisez l'entrée de fichier ou le glisser-déposer.

Comment valider les fichiers avant le téléchargement ?​

Vérifiez le type et la taille du fichier.

Puis-je obtenir une liste de tous les fichiers téléchargés pour une entité ?​

Pas directement avec ce SDK. Vous devez :

  1. Suivre les noms de fichiers lors du téléchargement (enregistrer dans la base de données)
  2. Utiliser l'API Admin OneEntry pour lister les fichiers

Meilleure pratique : Enregistrez les noms de fichiers téléchargés dans votre base de données.

Comment gérer les erreurs de téléchargement ?​

Utilisez toujours try/catch.

Puis-je télécharger des fichiers directement sur le CDN ?​

Non, les téléchargements passent par l'API OneEntry, qui :

  1. Valide le fichier
  2. Optimise les images (si activé)
  3. Stocke dans le cloud
  4. Retourne l'URL CDN

Cela garantit la sécurité et l'optimisation.

Que se passe-t-il avec les fichiers si je supprime une entité (produit, utilisateur) ?​

Les fichiers restent dans le stockage même si l'entité est supprimée.

Meilleure pratique : Supprimez les fichiers avant de supprimer l'entité.

Puis-je redimensionner les images à des dimensions exactes ?​

Non, le ratio d'aspect est toujours préservé pour éviter la distorsion.

Comment cela fonctionne :

  • Vous définissez width: 800, height: 600
  • L'image est redimensionnée pour s'adapter dans 800x600
  • Le ratio d'aspect est préservé

Exemple :

Original : 1000x500 (ratio 2:1)
Avec largeur : 800, hauteur : 600
Résultat : 800x400 (toujours ratio 2:1, s'adapte dans 800x600)

💡 Notes Importantes​

Sécurité des Fichiers​

Les fichiers téléchargés sont accessibles publiquement via le CDN :

  • ✅ Idéal pour les images, documents publics
  • ⚠️ Ne téléchargez pas de fichiers sensibles (mots de passe, données privées)

Pour les fichiers privés :

  • Utilisez l'API Admin OneEntry avec authentification
  • Ou implémentez votre propre contrôle d'accès

Limites de Stockage​

Surveillez votre utilisation de stockage :

  • Chaque plan a des limites de stockage
  • Nettoyez régulièrement les fichiers inutilisés
  • Compressez les images avant de les télécharger

Conseils d'Optimisation d'Image​

Pour de meilleurs résultats :

  • ✅ Téléchargez des originaux de haute qualité (laissez OneEntry optimiser)
  • ✅ Utilisez compress: true pour les images web
  • ✅ Définissez des dimensions appropriées (par exemple, 1920px pour les images héro, 500px pour les vignettes)
  • ❌ Ne téléchargez pas d'images déjà compressées (perte de qualité)

Tailles recommandées :

  • Photos de profil : 500x500
  • Images de produits : 1920x1920
  • Bannières héro : 1920x1080
  • Vignettes : 300x300

🎓 Meilleures Pratiques​

  • Validez le type et la taille du fichier avant le téléchargement
  • Associez les fichiers avec des ID d'entité pour l'organisation
  • Activez la compression pour les images web
  • Gérez les erreurs de téléchargement avec soin
  • Enregistrez les noms de fichiers pour supprimer des fichiers plus tard
  • Nettoyez régulièrement les fichiers inutilisés
  • Montrez la progression du téléchargement aux utilisateurs

Définition du module FileUploading​


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Documentation Connexe​