Aller au contenu principal

Premiers pas avec Dropup

Dropup est une bibliothèque React légère et headless pour le téléchargement de fichiers qui vous donne un contrôle total sur votre interface utilisateur tout en gérant toute la logique de téléchargement complexe.

Pourquoi Dropup ?​

  • 🪶 Léger - Le cœur ne fait qu'environ 10KB compressé
  • 🎨 Headless - Contrôle total sur votre UI avec une API basée sur les hooks
  • 📁 Glisser-déposer - Support intégré du glisser-déposer
  • 📊 Suivi de progression - Progression du téléchargement en temps réel pour chaque fichier
  • 🔄 Téléchargements fragmentés - Divisez les gros fichiers pour des téléchargements fiables
  • ☁️ Prêt pour le cloud - Helpers pré-construits pour S3, GCS et Azure
  • 🖼️ Traitement d'images - Compression et génération d'aperçus intégrées
  • 📱 Multi-plateforme - Fonctionne avec React DOM et React Native
  • 🔒 TypeScript - Support TypeScript complet

Installation​

Installez Dropup avec votre gestionnaire de paquets préféré :

npm install @samithahansaka/dropup

Dépendances de pairs​

Dropup nécessite React 16.8 ou supérieur (pour le support des hooks) :

npm install react

Démarrage rapide​

Voici un exemple simple pour commencer :

import { useDropup } from '@samithahansaka/dropup';

function FileUploader() {
  const {
    files,
    state,
    actions,
    getDropProps,
    getInputProps
  } = useDropup({
    accept: 'image/*',
    maxSize: 10 * 1024 * 1024, // 10MB
    multiple: true,
  });

  return (
    <div>
      {/* Zone de dépôt */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>Glissez-déposez des fichiers ici, ou cliquez pour sélectionner</p>
      </div>

      {/* Liste des fichiers */}
      <ul>
        {files.map((file) => (
          <li key={file.id}>
            {file.name} - {file.status}
            {file.status === 'uploading' && ` (${file.progress}%)`}
            <button onClick={() => actions.remove(file.id)}>Supprimer</button>
          </li>
        ))}
      </ul>

      {/* Bouton de téléchargement */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          Tout télécharger
        </button>
      )}
    </div>
  );
}

Concepts fondamentaux​

1. Le hook useDropup​

Le hook useDropup est le point d'entrée principal. Il retourne tout ce dont vous avez besoin pour construire votre interface de téléchargement de fichiers :

const {
  files,           // Tableau de fichiers avec statut, progression, etc.
  state,           // État global (isDragging, isUploading, progress)
  actions,         // Méthodes pour télécharger, supprimer, annuler, réinitialiser
  getDropProps,    // Props pour votre élément de zone de dépôt
  getInputProps,   // Props pour l'input fichier caché
} = useDropup(options);

2. Objets fichiers​

Chaque fichier dans le tableau files contient :

{
  id: string;          // Identifiant unique
  file: File;          // Objet File original
  name: string;        // Nom du fichier
  size: number;        // Taille du fichier en octets
  type: string;        // Type MIME
  preview?: string;    // URL d'aperçu (pour les images)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // Progression du téléchargement (0-100)
  error?: Error;       // Objet erreur si le téléchargement a échoué
  uploadedUrl?: string; // URL après un téléchargement réussi
}

3. Actions​

L'objet actions fournit des méthodes pour contrôler les téléchargements :

actions.upload(fileIds?)    // Démarrer le téléchargement (tous ou fichiers spécifiques)
actions.cancel(fileId?)     // Annuler le(s) téléchargement(s)
actions.remove(fileId)      // Supprimer un fichier de la liste
actions.reset()             // Effacer tous les fichiers
actions.retry(fileIds?)     // Réessayer les téléchargements échoués

Configuration des téléchargements​

Pour activer les téléchargements réels, fournissez une configuration de téléchargement :

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // Télécharger automatiquement quand des fichiers sont ajoutés
});

Prochaines étapes​