Aller au contenu principal

Introduction

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

Plus d'informations sur l'interface utilisateur du module https://doc.oneentry.cloud/docs/attributes/types/#File

🎯 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, tout type de fichier - avec optimisation automatique des images et livraison via 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.

🚀 Démarrage rapide​

Initialisez le module depuis defineOneEntry :


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

Téléchargez un fichier et lisez le lien de téléchargement retourné :

// upload() returns an ARRAY of uploaded files (IUploadingReturn[]).
const uploaded = await FileUploading.upload(file, {
  entity: "product",
  id: 123,
  type: "image",
  compress: true,
});

const { filename, downloadLink, size } = uploaded[0];
console.log(downloadLink); // use in <img>, <a>, <video>

Plus tard, supprimez-le par nom de fichier (l'entité/id résout le dossier de stockage) :

await FileUploading.delete(filename, { entity: "product", id: 123 });

✨ 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 et à obtenir un lien CDN permanent en retour :

  • Télécharger - envoyer un File ou Blob vers le cloud OneEntry
  • Stockage - les fichiers sont stockés, organisés par entity → id → filename
  • CDN - livraison rapide depuis des serveurs proches des utilisateurs
  • Optimisation - les images peuvent être automatiquement compressées et redimensionnées
  • URL - le downloadLink de la réponse est le lien permanent

Types de fichiers pris en charge​

Tout type de fichier est accepté. Seules les images sont auto-optimisées ; tout le reste est stocké tel quel.

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)

📋 Ce que vous devez savoir​

Paramètres de téléchargement​

upload(file, fileQuery?) prend le fichier plus un objet de requête optionnel :

await FileUploading.upload(file, {
  entity: 'product',     // Storage folder name (optional, any string)
  id: 123,               // Entity ID (optional)
  type: 'image',         // Folder/type hint (optional, any string)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true,        // Compress images (optional)
});
  • file — le File ou Blob à télécharger (d'un input ou par glisser-déposer)
  • entity — nom de dossier libre dans le stockage (par exemple product, page, user, editor — exemples, pas un enum fixe)
  • id — ID de l'entité à associer au fichier
  • type — chaîne d'indice de dossier/type libre
  • width / height — dimensions maximales pour les images (le rapport d'aspect est préservé)
  • compress — activer la compression d'image

Réponse de téléchargement​

upload() résout en un tableau de IUploadingReturn. Chaque élément a :

{
  filename: "uploads/abc123-photo.jpg",      // Filename with relative path
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size in bytes
  contentType: "image/png",                  // MIME type
}
  • downloadLink — utilisez cette URL dans les balises <img>, <a>, <video>
  • filename — enregistrez-le pour supprimer le fichier plus tard
  • size — taille du fichier en octets

Optimisation des images​

Pour les images, vous pouvez passer width, height, et compress. Le rapport d'aspect est toujours préservé — l'image est redimensionnée pour s'adapter dans les limites données, jamais étirée.

Suppression de fichiers​

Passez le nom de fichier en premier ; l'entité/id/type vivent dans l'objet de requête optionnel qui résout le dossier de stockage :

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

Récupération d'un fichier​

getFile(id, type, entity, filename, template?) retourne un objet Response brut (non JSON analysé) — appelez .blob(), .arrayBuffer(), etc. selon les besoins.

Création d'un fichier à partir d'une URL​

createFileFromUrl(url, filename, mimeType?) récupère une ressource distante et retourne un File de navigateur, pratique pour re-télécharger une image distante existante.

📊 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()Récupérer le fichier (réponse brute)Télécharger un fichier stocké
delete()Supprimer un fichier du stockageSupprimer des anciens fichiers
createFileFromUrl()Construire un File à partir d'une URL distanteImporter une image distante avant le téléchargement

Toutes les méthodes sont publiques — aucune autorisation utilisateur requise.

❓ Questions fréquentes (FAQ)​

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

Tout type de fichier. Seules les images sont auto-optimisées (redimensionner/comprimer) ; les autres fichiers sont stockés tels quels.

Quelle est la taille maximale des fichiers ?​

Cela dépend des limites de votre plan OneEntry. Optimisez les images avant le téléchargement pour réduire les tailles.

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

Oui — les fichiers restent jusqu'à ce que vous les supprimiez avec FileUploading.delete(). Les fichiers restent dans le stockage même si l'entité associée est supprimée, donc nettoyez-les explicitement.

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

Pas directement via ce SDK. Suivez les valeurs filename que vous obtenez de upload() (par exemple, enregistrez-les dans votre base de données) pour gérer les fichiers plus tard.

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

Non — le rapport d'aspect est toujours préservé. width/height définissent une boîte de délimitation dans laquelle l'image est ajustée, empêchant la distorsion.

🎓 Meilleures pratiques​

  • Validez le type et la taille du fichier avant d'appeler upload().
  • Passez entity / id pour que les fichiers soient organisés par entité dans le stockage.
  • Activez compress pour les images web.
  • Enregistrez le filename retourné afin de pouvoir delete() le fichier plus tard.
  • Nettoyez explicitement les fichiers inutilisés — ils survivent à la suppression de l'entité.
  • Gérez les erreurs de téléchargement avec try/catch et vérifiez la forme de retour IError.

🔗 Documentation connexe​