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 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 rapide via CDN 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 :

Without FileUploading (manual):
- Set up AWS S3 bucket ❌
- Configure CDN ❌
- Write image optimization code ❌
- Manage file permissions ❌
- Generate signed URLs ❌

With FileUploading (automatic):
- Upload file → Get download URL ✅
- Images auto-optimized ✅
- CDN delivery built-in ✅
- Easy file management ✅

✨ 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 vers 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 automatiquement 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 des Images​

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-optimize)
Optimized: 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',     // Entity type (required)
  id: 123,               // Entity ID (optional)
  type: 'image',         // File type hint (optional)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true         // Compress images (optional)
});

Paramètres expliqués :

  • file - L'objet fichier (provenant de l'entrée ou du glisser-déposer)
  • entity - Catégorie : produit, page, bloc, utilisateur, formulaire, général
  • id - ID de l'entité à associer au fichier (par exemple, ID du 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 au Téléchargement​

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

{
  filename: "abc123-photo.jpg",              // Unique filename
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size (bytes)
}

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 = 200 Ko)

Meilleures Pratiques d'Organisation des Fichiers​

Organisez les fichiers par type d'entité

Options d'Optimisation des Images​

Contrôlez comment les images sont optimisées :

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

Le rapport d'aspect est préservé :

Original: 4000x3000 (4:3 ratio)
With width: 800
Result: 800x600 (still 4:3 ratio)

Suppression de Fichiers​

Fournissez toujours l'entité, l'id et le nom de fichier à 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 anciens fichiers

❓ 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 : 5 Mo par fichier
  • Plans payants : 50 Mo - 100 Mo par fichier

Meilleure pratique : Optimisez les images avant le téléchargement 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 rapport 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 rapport d'aspect est préservé

Exemple :

Original: 1000x500 (2:1 ratio)
With width: 800, height: 600
Result: 800x400 (still 2:1 ratio, fits within 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 le téléchargement

Conseils d'Optimisation des Images​

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 les 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 les 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​