React-Datei-Uploads mit Uppy: fortsetzbare Uploads, Vorschauen, Validierung und Verarbeitung

Vor der Entwicklung der Komponente definieren, was „abgeschlossen“ bedeutet

Ein Browser kann die Übertragung der Bytes abschließen, während die resultierenden Medien noch geprüft, transformiert und exportiert werden. Legen Sie fest, welchen Zustand die Oberfläche als abgeschlossen bezeichnet: Dateiauswahl, Transfer, Erstellung der Assembly, Verarbeitung, dauerhafte Speicherung oder Veröffentlichung in der Anwendung. Die folgenden drei Ebenen fassen Dateiauswahl und Transfer unter Transfererfolg zusammen, die Erstellung und Verarbeitung der Assembly unter Verarbeitungserfolg sowie dauerhafte Speicherung und Veröffentlichung unter Anwendungserfolg. Eine React-Komponente kann mehrere dieser Zustände anzeigen, sollte sie aber nicht in einem einzigen Erfolgsindikator zusammenfassen.

In einem Transloadit-Workflow verwaltet Uppy die browserseitige Warteschlange und den Transferzustand. Das Transloadit-Plugin erstellt eine Assembly und ordnet jede lokale Datei diesem Workflow zu. Ihre Anwendung sollte die Assembly ID speichern, sobald sie verfügbar ist. Wenn die Verarbeitung die Lebensdauer der Seite überschreiten kann, gleichen Sie das endgültige Ergebnis anschließend außerhalb der Komponente ab. Ein vollständig gefüllter Fortschrittsbalken ist kein dauerhaft gespeicherter Asset-Datensatz.

Pro eingebundenem Dateiuploader eine konfigurierte Uppy-Instanz erstellen

Installieren Sie Core, Dashboard, das React-Schnittstellenpaket, das gepflegte Transloadit-Plugin und den Zod-Schemavalidator für die Autorisierungsantwort. Importieren Sie jedes Uppy-Stylesheet einmal von einem stabilen Einstiegspunkt, damit die Ladereihenfolge vorhersehbar bleibt. Das folgende Komponentenbeispiel importiert die Paket-Styles direkt. Verschieben Sie diese Importe zum Einstiegspunkt der Anwendung, wenn Ihr Framework oder Bundler dort die globalen Styles verwaltet.

Erstellen Sie Uppy einmal für die gesamte Lebensdauer des eingebundenen Formulars. Ein verzögert ausgeführter useState-Initialisierer im nächsten Abschnitt gibt jedem eingebundenen Dateiuploader eine eigene Instanz, ohne sie bei erneutem Rendering neu zu erstellen. Erstellen Sie keinen gemeinsam genutzten Singleton auf Modulebene, außer wenn jede Oberfläche ausdrücklich dieselbe Warteschlange verwenden soll. Andernfalls würden unabhängige Formulare die Dateien der jeweils anderen Formulare sehen und entfernen.

Die asynchrone Funktion assemblyOptions fordert unmittelbar vor dem Upload bei einem vertrauenswürdigen Endpunkt eine Autorisierung an. Der Endpunkt muss den aktuellen Nutzer authentifizieren und autorisieren, Schutzmaßnahmen gegen Missbrauch anwenden, ein eingeschränktes Template auswählen und eine kurzlebige signierte Nutzlast zurückgeben. Der Browser validiert die Struktur der Antwort, erhält jedoch niemals das Auth Secret.

yarn add @uppy/core @uppy/dashboard @uppy/react @uppy/transloadit zod

import Uppy from '@uppy/core'
import Transloadit from '@uppy/transloadit'
import { z } from 'zod'

const assemblyOptionsSchema = z.object({
  params: z.string().min(1),
  signature: z.string().regex(/^(sha1|sha256|sha384):[0-9a-f]+$/),
})

async function fetchAssemblyOptions(): Promise<z.infer<typeof assemblyOptionsSchema>> {
  const response = await fetch('/api/transloadit-params', {
    method: 'POST',
    headers: { Accept: 'application/json' },
  })

  if (!response.ok) {
    throw new Error('Could not authorize this upload')
  }

  const responseBody: unknown = await response.json().catch(() => null)
  const parsedOptions = assemblyOptionsSchema.safeParse(responseBody)
  if (!parsedOptions.success) {
    throw new Error('Could not authorize this upload')
  }

  return parsedOptions.data
}

export function createImageUploader(): Uppy {
  return new Uppy({
    autoProceed: false,
    restrictions: {
      allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxFileSize: 50 * 1024 * 1024,
      maxNumberOfFiles: 5,
    },
  }).use(Transloadit, {
    assemblyOptions: fetchAssemblyOptions,
    retryDelays: [0, 1_000, 3_000, 5_000],
    waitForEncoding: false,
  })
}

Fortschritt, Abbruch und Assembly-Zustand aus Uppy darstellen

Uppy ist ein externer Zustandsspeicher. useUppyState abonniert ausgewählte Werte für React, ohne eine zweite Warteschlange im Komponentenzustand zu verwalten. useUppyEvent stellt dagegen Ereignisse bereit, die keine dauerhaften Speicherfelder sind. Die Komponente liest die Dateianzahl, den Gesamtfortschritt, den aktiven Upload-Status, den unverarbeiteten Fehlerzustand und das Ereignis zur Erstellung der Assembly. Sie ordnet den Fehler einer stabilen nutzerfreundlichen Meldung zu, statt den unverarbeiteten Wert anzuzeigen, und spiegelt einzelne Dateien nicht in einem separaten useState-Wert.

Dashboard bietet Dateiauswahl, Drag-and-drop, Vorschauen für unterstützte lokale Dateien, einen Status pro Datei und Upload-Steuerelemente. Die separate Live-Region stellt der umgebenden Anwendung eine knappe Statusmeldung bereit, während die native deaktivierte Schaltfläche erkennen lässt, ob ein Abbruch möglich ist. Lokalisieren Sie auch die Dashboard-eigenen Bezeichnungen, wenn das Produkt mehrere Sprachen unterstützt. Für die umgebende Überschrift, den Status und die Fehlermeldungen gilt dasselbe.

Zerstören Sie die Uppy-Instanz, wenn die zugehörige Komponente ausgehängt wird. Dadurch werden laufende Vorgänge abgebrochen, installierte Plugins entfernt und Listener freigegeben. Ein Routenwechsel sollte daher nicht die einzige Stelle sein, an der wichtige Fortschrittsdaten vorliegen. Speichern Sie die Assembly ID und gegebenenfalls den Aufgaben-Datensatz der Anwendung, bevor Sie sich auf Vorgänge verlassen, die andernorts fortgesetzt werden können.

import type { ReactNode } from 'react'

import Dashboard from '@uppy/react/dashboard'
import { useUppyEvent, useUppyState } from '@uppy/react'
import { useEffect, useState } from 'react'

import { createImageUploader } from './createImageUploader.ts'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

export function ReactFileUploader(): ReactNode {
  const [uppy] = useState(createImageUploader)
  const error = useUppyState(uppy, (state) => state.error)
  const fileCount = useUppyState(uppy, (state) => Object.keys(state.files).length)
  const isUploading = useUppyState(
    uppy,
    (state) => Object.keys(state.currentUploads).length > 0,
  )
  const progress = useUppyState(uppy, (state) => state.totalProgress)
  const [assemblyCreatedArgs, clearAssemblyCreated] = useUppyEvent(
    uppy,
    'transloadit:assembly-created',
  )
  useUppyEvent(uppy, 'cancel-all', clearAssemblyCreated)
  const [assembly] = assemblyCreatedArgs
  const assemblyId = assembly?.assembly_id

  useEffect(() => {
    return () => uppy.destroy()
  }, [uppy])

  let status = 'Choose up to five JPEG, PNG, or WebP images.'
  if (fileCount > 0) status = 'Ready to upload.'
  if (isUploading) status = `Upload ${progress}% complete.`
  if (!isUploading && progress === 100) status = 'Files transferred. Processing may continue.'
  if (error != null) status = 'Upload failed. Check the selected files and try again.'

  return (
    <section aria-labelledby="file-upload-heading">
      <h2 id="file-upload-heading">Upload images</h2>
      <Dashboard height={420} uppy={uppy} />
      <p aria-live="polite" role="status">
        {status}
      </p>
      {assemblyId != null ? (
        <p>
          Processing reference: <code>{assemblyId}</code>
        </p>
      ) : null}
      <button disabled={fileCount === 0} onClick={() => uppy.cancelAll()} type="button">
        Cancel and remove files
      </button>
    </section>
  )
}

Vorschauen und Beschränkungen als Oberflächenfunktionen statt als Vertrauensgrenzen verwenden

Eine lokale Vorschau hilft Nutzern, eine falsche Auswahl zu erkennen, bevor Kosten für den Upload anfallen. Sie ist nicht das verarbeitete Ergebnis und beweist weder, dass die Datei sicher und decodierbar ist, noch dass sie korrekt ausgerichtet oder wahrheitsgemäß gekennzeichnet wurde. Begrenzen Sie die Vorschauverarbeitung, da das Decodieren vieler großer Bilder Browserspeicher beansprucht. Zeigen Sie bei Formaten, für die der Browser keine Vorschau erstellen kann, den Dateinamen, den deklarierten Typ und die Größe an, ohne ein Thumbnail zu erfinden.

Uppy-Beschränkungen weisen offensichtliche Fehler frühzeitig zurück: zulässige Typen, Größe einzelner Dateien, Gesamtgröße und Dateianzahl. Wenden Sie dieselben Grenzwerte auch bei einem vertrauenswürdigen Empfänger oder im gespeicherten Template an, da ein Aufrufer React umgehen und Dateimetadaten ändern kann. Verwenden Sie gegebenenfalls erkannte Inhalte und einen Verarbeitungsversuch und speichern Sie anschließend nur akzeptierte Ergebnisse. Lassen Sie allow_steps_override deaktiviert, wenn der Browser den genehmigten Workflow nicht ersetzen darf. Wenn eine Vorschau oder Beschränkung eine Auswahl zurückweist, zeigen Sie eine gleichbleibende, nutzerfreundliche Meldung an. Unverarbeitete Antworten des Anbieters, Stacktraces, Zugangsdaten und Speicherdiagnosen dürfen nicht auf der Seite erscheinen.

Fortsetzbare Uploads auf die zu überstehende Unterbrechung ausrichten

Das Transloadit-Plugin lädt lokale Dateien über tus hoch. Solange die Upload-Ressource gültig bleibt, kann tus eine fehlgeschlagene Übertragung ab einem vom Server bestätigten Offset fortsetzen. retryDelays behandelt während der aktuellen Lebensdauer von Uppy eine begrenzte Anzahl vorübergehender Fehler. Ein Abbruch ist etwas anderes: cancelAll() bricht laufende Vorgänge ausdrücklich ab, entfernt die Dateien und setzt den Upload-Status zurück. Die Benutzeroberfläche sollte daher darauf hinweisen, dass die Auswahl entfernt wird.

Beim Neuladen einer Seite gehen die im Arbeitsspeicher gehaltenen Zustände von React und Uppy verloren. Die Wiederherstellung nach dem Neuladen erfordert einen persistierten Client-Zustand und kompatible Upload-Ressourcen auf dem Server, etwa einen bewusst konfigurierten Workflow mit dem Golden-Retriever-Plugin. Testen Sie dieses Verhalten mit der tatsächlichen Transloadit-Integration, bevor Sie es zusichern. Persistierte lokale Metadaten können veraltet oder vertraulich werden oder nicht mehr mit einer abgelaufenen Autorisierung übereinstimmen. Legen Sie daher eine Aufbewahrungsdauer und eine Möglichkeit fest, nicht wiederherstellbare Einträge zu verwerfen.

Fortsetzbare Uploads haben auch eine zeitliche Grenze im Betrieb. Eine Assembly kann nicht unbegrenzt für Uploads verfügbar bleiben, und kurzlebige signierte Parameter können ablaufen, bevor ein verzögerter erneuter Versuch beginnt. Unterscheiden Sie zwischen automatischen erneuten Versuchen, Pausieren und Fortsetzen, Wiederherstellung nach dem Neuladen und dem Starten einer neuen Assembly. Diese Verfahren beheben unterschiedliche Fehler und verwenden möglicherweise unterschiedliche Identifikatoren erneut.

Übertragene Dateien an einen asynchronen Medienworkflow übergeben

Ein gespeichertes Template sollte den zulässigen Verarbeitungsgraphen beschreiben: /upload/handle empfängt die Browserdateien, /file/filter kann nicht unterstützte erkannte Eingaben ablehnen, Transformations-Robots erzeugen begrenzte Derivate und Robots für die Speicherung exportieren freigegebene Ergebnisse, wenn dauerhafte Speicherung Teil des Workflows ist. Die signierte Anfrage wählt dieses Template aus. React erstellt weder beliebige Steps noch überträgt es dauerhafte Zugangsdaten für den Speicher.

Wählen Sie waitForEncoding entsprechend dem Schnittstellenvertrag. Mit dem Wert false kann der Browser den Vorgang nach der Übertragung abschließen. Das eignet sich, wenn die Anwendung die Assembly ID speichert, einen separaten Verarbeitungsstatus anzeigt und das endgültige Ergebnis entweder über eine verifizierte Assembly Notification erfährt oder später den Assembly Status abruft. Das Warten auf das Encoding kann die Benutzeroberfläche bei kurzen Verarbeitungszeiten synchron halten, ersetzt jedoch keinen dauerhaften Abgleich, falls der Tab geschlossen wird.

Speichern Sie Kontext auf Anwendungsebene zusammen mit der Assembly ID: den authentifizierten Nutzer oder Mandanten, den vorgesehenen Asset-Slot, die Template ID, den Erstellungszeitpunkt und den Anwendungsvorgang, der die Assembly ausgelöst hat. Wenn eine Notification eintrifft, prüfen Sie deren Signatur, behandeln Sie eine doppelte Zustellung idempotent, bestätigen Sie die Zugehörigkeit der Assembly zum erwarteten Datensatz und speichern Sie nur die Ergebnisfelder, die das Produkt benötigt.

Lebenszyklus und Fehlerverhalten statt nur den Erfolgsfall testen

Testen Sie die Komponente mit einer zulässigen kleinen Datei, einer zu großen Datei, einer irreführenden Dateiendung, einem nicht unterstützten Typ, mehreren Dateien an der Anzahlgrenze, einer Null-Byte-Eingabe, einer langsamen Verbindung, einer Offlinephase, einer Ablehnung durch den Server, abgelaufener Autorisierung, einem Abbruch durch den Nutzer, dem Unmounten der Komponente und dem Neuladen der Seite. Prüfen Sie, welcher Zustand erhalten bleibt, welche Vorgänge abgebrochen werden und welche Meldung Nutzer erhalten, die eine Tastatur oder einen Screenreader verwenden.

Testen Sie neben dem isolierten React-Verhalten auch den tatsächlichen Pfad für Signatur und Verarbeitung. Ein Mock kann belegen, dass die Schaltfläche deaktiviert wird oder sich ein Status ändert. Nur integrierte Testdaten belegen jedoch, dass die signierten Parameter übereinstimmen, tus den Upload am erwarteten Offset fortsetzt, das Template ungültige Inhalte ablehnt, die Assembly ID gespeichert wird und der Abschluss einmal abgeglichen wird. Verwenden Sie kleine Testdateien und entfernen Sie temporäre Produktionsdaten nach dem Durchlauf.