Rückgabewerte-Referenz

Alles, was der useDropup Hook zurückgibt.

Übersicht

const {
  files,          // Array von Dateiobjekten
  state,          // Aktueller Zustand
  actions,        // Verfügbare Aktionen
  getDropProps,   // Props für Ablagezone
  getInputProps,  // Props für Input-Element
  openFileDialog, // Dateiauswahl öffnen
} = useDropup();

files

Array von DropupFile-Objekten, die alle hinzugefügten Dateien repräsentieren.

const { files } = useDropup();

files.forEach(file => {
  console.log(file.id);          // "abc123"
  console.log(file.name);        // "foto.jpg"
  console.log(file.size);        // 1234567
  console.log(file.type);        // "image/jpeg"
  console.log(file.status);      // "idle" | "uploading" | "complete" | "error"
  console.log(file.progress);    // 0-100
  console.log(file.preview);     // "blob:http://..." (nur Bilder)
  console.log(file.uploadedUrl); // "https://..." (nach Upload)
  console.log(file.error);       // DropupError (bei Fehler)
});

DropupFile-Eigenschaften

Eigenschaft	Typ	Beschreibung
id	string	Eindeutige Kennung
file	File	Ursprüngliches Browser-File-Objekt
name	string	Dateiname
size	number	Größe in Bytes
type	string	MIME-Typ
status	FileStatus	Aktueller Status
progress	number	Upload-Fortschritt (0-100)
preview	string | undefined	Vorschau-URL für Bilder
uploadedUrl	string | undefined	URL nach erfolgreichem Upload
response	unknown	Server-Antwortdaten
error	DropupError | undefined	Fehler bei Upload-Fehlschlag
meta	Record<string, unknown>	Benutzerdefinierte Metadaten

FileStatus-Werte

Status	Beschreibung
'idle'	Datei hinzugefügt, kein Upload
'uploading'	Upload läuft
'complete'	Upload erfolgreich
'error'	Upload fehlgeschlagen
'paused'	Upload pausiert (wiederaufnehmbare Uploads)

state

Aktueller Zustand der Ablagezone.

const { state } = useDropup();

console.log(state.isDragging);   // true beim Ziehen über Zone
console.log(state.isDragAccept); // true wenn gezogene Dateien gültig
console.log(state.isDragReject); // true wenn gezogene Dateien ungültig
console.log(state.isUploading);  // true wenn eine Datei hochgeladen wird
console.log(state.progress);     // Gesamtfortschritt 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

State-Eigenschaften

Eigenschaft	Typ	Beschreibung
isDragging	boolean	Dateien werden über Ablagezone gezogen
isDragAccept	boolean	Gezogene Dateien bestehen Validierung
isDragReject	boolean	Gezogene Dateien bestehen Validierung nicht
isUploading	boolean	Eine Datei wird gerade hochgeladen
progress	number	Durchschnittlicher Fortschritt aller Dateien (0-100)
status	DropupStatus	Gesamter Upload-Status

DropupStatus-Werte

Status	Beschreibung
'idle'	Keine Uploads in Bearbeitung
'uploading'	Eine oder mehrere Dateien werden hochgeladen
'complete'	Alle Uploads erfolgreich abgeschlossen
'error'	Ein oder mehrere Uploads fehlgeschlagen

actions

Objekt mit allen verfügbaren Aktionen.

const { actions } = useDropup();

// Uploads starten
actions.upload();              // Alle Dateien im idle-Status hochladen
actions.upload(['id1', 'id2']); // Bestimmte Dateien hochladen

// Uploads abbrechen
actions.cancel();              // Alle Uploads abbrechen
actions.cancel('file-id');     // Bestimmte Datei abbrechen

// Dateien entfernen
actions.remove('file-id');     // Bestimmte Datei entfernen
actions.reset();               // Alle Dateien entfernen

// Fehlgeschlagene Uploads wiederholen
actions.retry();               // Alle fehlgeschlagenen wiederholen
actions.retry(['id1']);        // Bestimmte Dateien wiederholen

// Dateien programmatisch hinzufügen
actions.addFiles(fileList);    // File[] oder FileList hinzufügen

// Datei-Metadaten aktualisieren
actions.updateFileMeta('file-id', { tag: 'wichtig' });

Aktionsmethoden

upload(fileIds?)

Uploads starten.

// Alle Dateien im idle-Status hochladen
actions.upload();

// Bestimmte Dateien hochladen
actions.upload(['file-id-1', 'file-id-2']);

Parameter	Typ	Beschreibung
fileIds	string[] (optional)	Bestimmte Datei-IDs zum Hochladen

cancel(fileId?)

Laufende Uploads abbrechen.

// Alle Uploads abbrechen
actions.cancel();

// Bestimmte Datei abbrechen
actions.cancel('file-id');

Parameter	Typ	Beschreibung
fileId	string (optional)	Bestimmte Datei-ID zum Abbrechen

remove(fileId)

Eine Datei aus der Liste entfernen.

actions.remove('file-id');

Parameter	Typ	Beschreibung
fileId	string	Zu entfernende Datei-ID

reset()

Alle Dateien entfernen und Zustand zurücksetzen.

actions.reset();

retry(fileIds?)

Fehlgeschlagene Uploads wiederholen.

// Alle fehlgeschlagenen Uploads wiederholen
actions.retry();

// Bestimmte Dateien wiederholen
actions.retry(['file-id-1']);

Parameter	Typ	Beschreibung
fileIds	string[] (optional)	Bestimmte Datei-IDs zum Wiederholen

addFiles(files)

Dateien programmatisch hinzufügen.

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

// Aus anderer Quelle
actions.addFiles([file1, file2]);

Parameter	Typ	Beschreibung
files	File[] | FileList	Hinzuzufügende Dateien

updateFileMeta(fileId, meta)

Datei-Metadaten aktualisieren.

actions.updateFileMeta('file-id', {
  description: 'Mein Foto',
  tags: ['urlaub', '2024'],
});

Parameter	Typ	Beschreibung
fileId	string	Zu aktualisierende Datei-ID
meta	Record<string, unknown>	Zu mergende Metadaten

getDropProps

Gibt Props zurück, die auf dem Ablagezonen-Element gespreizt werden.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  Dateien hier ablegen
</div>

Mit benutzerdefinierten Props

<div
  {...getDropProps({
    className: 'meine-dropzone',
    onClick: (e) => {
      // Ihr benutzerdefinierter Klick-Handler
      console.log('Geklickt!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Zurückgegebene Props

Eigenschaft	Typ	Beschreibung
onDragEnter	function	Drag-Enter-Handler
onDragOver	function	Drag-Over-Handler
onDragLeave	function	Drag-Leave-Handler
onDrop	function	Drop-Handler
onClick	function	Klick-Handler (öffnet Dialog)
role	string	Barrierefreiheits-Rolle
tabIndex	number	Tab-Index für Fokus

getInputProps

Gibt Props zurück, die auf dem versteckten Datei-Input gespreizt werden.

const { getInputProps } = useDropup();

<input {...getInputProps()} />

Mit benutzerdefinierten Props

<input
  {...getInputProps({
    id: 'file-input',
    name: 'files',
  })}
/>

Zurückgegebene Props

Eigenschaft	Typ	Beschreibung
type	'file'	Input-Typ
accept	string	Akzeptierte Dateitypen
multiple	boolean	Mehrere Dateien erlauben
onChange	function	Änderungs-Handler
style	object	Versteckte Styles

openFileDialog

Funktion zum programmatischen Öffnen der Dateiauswahl.

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Dateien durchsuchen
</button>

Verwendungsbeispiele

Vollständige Dateiliste

function Dateiliste() {
  const { files, actions, state } = useDropup({
    upload: { url: '/api/upload' },
  });

  return (
    <div>
      <h3>Dateien ({files.length})</h3>

      {files.map(file => (
        <div key={file.id}>
          {file.preview && (
            <img src={file.preview} alt="" width={50} />
          )}
          <span>{file.name}</span>
          <span>{(file.size / 1024).toFixed(1)} KB</span>
          <span>{file.status}</span>

          {file.status === 'uploading' && (
            <progress value={file.progress} max={100} />
          )}

          {file.status === 'error' && (
            <>
              <span style={{ color: 'red' }}>{file.error?.message}</span>
              <button onClick={() => actions.retry([file.id])}>Wiederholen</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>Entfernen</button>
        </div>
      ))}

      {state.isUploading && (
        <p>Wird hochgeladen... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        Alle hochladen
      </button>

      <button onClick={() => actions.reset()}>
        Alle löschen
      </button>
    </div>
  );
}

Drag-Status-Styling

function StilisierteDropzone() {
  const { state, getDropProps, getInputProps } = useDropup({
    accept: 'image/*',
  });

  const getStyle = () => {
    if (state.isDragAccept) return { borderColor: 'green', backgroundColor: '#e8f5e9' };
    if (state.isDragReject) return { borderColor: 'red', backgroundColor: '#ffebee' };
    if (state.isDragging) return { borderColor: 'blue', backgroundColor: '#e3f2fd' };
    return { borderColor: 'gray', backgroundColor: 'white' };
  };

  return (
    <div
      {...getDropProps()}
      style={{
        border: '2px dashed',
        borderRadius: 8,
        padding: 40,
        textAlign: 'center',
        transition: 'all 0.2s',
        ...getStyle(),
      }}
    >
      <input {...getInputProps()} />
      {state.isDragReject ? (
        <p>Nur Bilder sind erlaubt!</p>
      ) : (
        <p>Bilder hier ablegen</p>
      )}
    </div>
  );
}