Dateiverarbeitung

Dropup bietet eine nahtlose Erfahrung für die Handhabung von Dateien vom Moment der Auswahl bis zum Upload.

Dateiauswahlmethoden

Drag and Drop

Verwenden Sie getDropProps(), um Drag-and-Drop auf jedem Element zu aktivieren:

function DropZone() {
  const { getDropProps, getInputProps, state } = useDropup();

  return (
    <div
      {...getDropProps()}
      style={{
        border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
        backgroundColor: state.isDragging ? '#f0f8ff' : 'transparent',
      }}
    >
      <input {...getInputProps()} />
      <p>Dateien hier ablegen</p>
    </div>
  );
}

Klicken zum Auswählen

Die Ablagezone ist standardmäßig auch klickbar:

<div {...getDropProps()}>
  <input {...getInputProps()} />
  <p>Klicken oder Dateien hierher ziehen</p>
</div>

Programmatische Auswahl

Öffnen Sie den Dateiauswahldialog programmatisch:

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Dateien auswählen
</button>

Programmatisches Hinzufügen von Dateien

Dateien direkt hinzufügen (nützlich für Einfüge-Events oder Integrationen):

const { actions } = useDropup();

// Aus der Zwischenablage
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files?.length) {
    actions.addFiles(files);
  }
});

Dateiobjektstruktur

Jede Datei im files-Array hat diese Struktur:

interface DropupFile {
  // Identifikation
  id: string;              // Eindeutige Kennung (automatisch generiert)
  file: File;              // Ursprüngliches Browser-File-Objekt

  // Metadaten
  name: string;            // Dateiname
  size: number;            // Größe in Bytes
  type: string;            // MIME-Typ (z.B. "image/png")

  // Vorschau (für Bilder)
  preview?: string;        // Object URL für Vorschau

  // Upload-Status
  status: FileStatus;      // 'idle' | 'uploading' | 'complete' | 'error' | 'paused'
  progress: number;        // 0-100

  // Ergebnisse
  uploadedUrl?: string;    // URL nach erfolgreichem Upload
  response?: unknown;      // Server-Antwort
  error?: DropupError;     // Fehlerdetails bei Fehlschlag

  // Benutzerdefinierte Daten
  meta?: Record<string, unknown>;
}

Dateistatuslebenszyklus

idle → uploading → complete
                 ↘ error → (wiederholen) → uploading
                 ↘ paused → (fortsetzen) → uploading

Statuswerte

Status	Beschreibung
idle	Datei hinzugefügt, aber noch kein Upload
uploading	Wird gerade hochgeladen
complete	Upload erfolgreich
error	Upload fehlgeschlagen
paused	Upload pausiert (für wiederaufnehmbare Uploads)

Mit Dateien arbeiten

Dateien abrufen

const { files } = useDropup();

// Alle Dateien
console.log(files);

// Nach Status filtern
const uploading = files.filter(f => f.status === 'uploading');
const completed = files.filter(f => f.status === 'complete');
const failed = files.filter(f => f.status === 'error');

Dateien entfernen

const { files, actions } = useDropup();

// Einzelne Datei entfernen
actions.remove(files[0].id);

// Alle Dateien entfernen
actions.reset();

Datei-Metadaten aktualisieren

const { actions } = useDropup();

// Benutzerdefinierte Metadaten hinzufügen
actions.updateFileMeta(fileId, {
  customField: 'wert',
  category: 'dokumente',
});

Dateivorschauen

Für Bilddateien kann Dropup Vorschau-URLs generieren:

const { files } = useDropup({
  generatePreviews: true, // Standard: true
});

// Vorschau in Ihrer UI verwenden
{files.map(file => (
  file.preview && (
    <img
      src={file.preview}
      alt={file.name}
      style={{ maxWidth: 100, maxHeight: 100 }}
    />
  )
))}

Speicherverwaltung

Vorschau-URLs sind Object URLs, die Speicher verbrauchen. Dropup widerruft sie automatisch, wenn Dateien entfernt werden oder die Komponente ausgehängt wird.

Dateigrößenformatierung

Hilfsfunktion zur Anzeige von Dateigrößen:

function formatFileSize(bytes: number): string {
  if (bytes === 0) return '0 Bytes';
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
}

// Verwendung
{files.map(file => (
  <span>{formatFileSize(file.size)}</span>
))}

Große Dateien behandeln

Für große Dateien sollten Sie Chunked Uploads in Betracht ziehen:

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

const { files } = useDropup({
  upload: createChunkedUploader({
    url: '/api/upload',
    chunkSize: 5 * 1024 * 1024, // 5MB Chunks
  }),
});

Siehe Chunked Uploads für weitere Details.