Zum Hauptinhalt springen

Erste Schritte mit Dropup

Dropup ist eine leichtgewichtige, headless React-Bibliothek für Datei-Uploads, die Ihnen die volle Kontrolle über Ihre Benutzeroberfläche gibt, während sie die gesamte komplexe Upload-Logik übernimmt.

Warum Dropup?​

  • 🪶 Leichtgewichtig - Der Kern ist nur ~10KB gzipped
  • 🎨 Headless - Volle Kontrolle über Ihre UI mit Hooks-basierter API
  • 📁 Drag & Drop - Eingebaute Drag-and-Drop-Unterstützung
  • 📊 Fortschrittsverfolgung - Echtzeit-Upload-Fortschritt für jede Datei
  • 🔄 Chunked Uploads - Große Dateien für zuverlässige Uploads aufteilen
  • ☁️ Cloud-Ready - Vorgefertigte Helfer für S3, GCS und Azure
  • 🖼️ Bildverarbeitung - Eingebaute Komprimierung und Vorschau-Generierung
  • 📱 Plattformübergreifend - Funktioniert mit React DOM und React Native
  • 🔒 TypeScript - Volle TypeScript-Unterstützung

Installation​

Installieren Sie Dropup mit Ihrem bevorzugten Paketmanager:

npm install @samithahansaka/dropup

Peer-Abhängigkeiten​

Dropup erfordert React 16.8 oder höher (für Hooks-Unterstützung):

npm install react

Schnellstart​

Hier ist ein einfaches Beispiel für den Einstieg:

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>
      {/* Ablagezone */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>Dateien hierher ziehen oder klicken zum Auswählen</p>
      </div>

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

      {/* Upload-Button */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          Alle hochladen
        </button>
      )}
    </div>
  );
}

Kernkonzepte​

1. Der useDropup Hook​

Der useDropup Hook ist der Haupteinstiegspunkt. Er gibt alles zurück, was Sie zum Erstellen Ihrer Datei-Upload-Oberfläche benötigen:

const {
  files,           // Array von Dateien mit Status, Fortschritt usw.
  state,           // Gesamtstatus (isDragging, isUploading, progress)
  actions,         // Methoden zum Hochladen, Entfernen, Abbrechen, Zurücksetzen
  getDropProps,    // Props für Ihr Ablagezonen-Element
  getInputProps,   // Props für das versteckte Datei-Input
} = useDropup(options);

2. Datei-Objekte​

Jede Datei im files-Array enthält:

{
  id: string;          // Eindeutige Kennung
  file: File;          // Ursprüngliches File-Objekt
  name: string;        // Dateiname
  size: number;        // Dateigröße in Bytes
  type: string;        // MIME-Typ
  preview?: string;    // Vorschau-URL (für Bilder)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // Upload-Fortschritt (0-100)
  error?: Error;       // Fehlerobjekt bei fehlgeschlagenem Upload
  uploadedUrl?: string; // URL nach erfolgreichem Upload
}

3. Aktionen​

Das actions-Objekt bietet Methoden zur Steuerung von Uploads:

actions.upload(fileIds?)    // Upload starten (alle oder bestimmte Dateien)
actions.cancel(fileId?)     // Upload(s) abbrechen
actions.remove(fileId)      // Eine Datei aus der Liste entfernen
actions.reset()             // Alle Dateien löschen
actions.retry(fileIds?)     // Fehlgeschlagene Uploads wiederholen

Uploads konfigurieren​

Um tatsächliche Uploads zu aktivieren, geben Sie eine Upload-Konfiguration an:

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // Automatisch hochladen, wenn Dateien hinzugefügt werden
});

Nächste Schritte​