React Async Uploader

Dieses Packet stellt verschiedene React-Komponenten zur Umsetzung eines Asynchronen Clientseitigen Datei-Uplodas bereits. Intern wird hierfür die resumable.js-Komponente genutzt.

Hierfür wird eine Serverseitige API genutzt, die beispielsweise vom BoewaAsyncUploadBundle implementiert wird.

Instalation

$ npm install --save @boewa-software/react-async-uploader

Nutzung

Zur Nutzung, muss ein serverseitiger Endpunkt in form einer URL zum Verschicken der Dateien vorhanden sein.

Alleinstehender Uploader

Um einen grundlegenden Uploader zu erzeugen, wird lediglich der Pfad zum Endpunkt benötigt (im Folgenden über /endpoint-url beschrieben).

Die Uploader-Kompnente kann beispielsweise eine DOM-Node ersetzten (hier exemplarisch über targetElement) beschrieben:

import React from 'react';
import {createRoot} from "react-dom/client";

import {Uploader} from '@boewa-software/react-async-uploader';

// DOM-Node zum Einhängen der React-Komponente
const targetElement = document.getElementById("target-element");

const root = createRoot(targetElement);
root.render(
    <Uploader path={'/endpoint-url'} />
);

Darstellung überschreiben

Die Darstellung des Uploaders kann nach belibeben überschrieben werden, dafür muss eine React-Komponente implementiert werden, die das Layout definiert.

Die Layout-Komponente wird über das component-Property an den Uploader übergeben:

import React from 'react';
import {createRoot} from "react-dom/client";
import {Uploader, DropZone, BrowseButton} from '@boewa-software/react-async-uploader';

const CustomLayoutComponent = ({ uploads, assignDrop, assignBrowse }) =>
    <DropZone assignDrop={assignDrop}>
        Uploads: {uploads.length}
        <BrowseButton assignBrowse={assignBrowse}>
            Select File
        </BrowseButton>
    </DropZone>
;
const targetElement = document.getElementById("target-element");

const root = createRoot(targetElement);
root.render(
    <Uploader
        path={'/endpoint-url'}
        component={CustomLayoutComponent}
    />
);

Dabei können die Bereitstellten Komponenten zur Definition einer Drop-Zone (DropZone) und eines Browse-Buttons (BrowseButton) genutzt werden.

Übergebene Parameter

Die Layout-Komponente erhält vom Uploader die folgenden Parameter (props) zur Nutzung übergeben:

• uploaderState : string

  Aktueller Status des Uploaders mit den WerteN:

  • running: Es werden Dateien hochgeladen.
  • paused: Uploader ist Pausiert, Dateien werden erst nach dem Aufruf von start weiter hochgeladen.
  • complete: Der Uploader ist aktiv, es sind keine Dateien zum Upload in der Warteschlange.

• uploads : uploadObject[]

  Array aller aktuellen Uploads. Jedes dieser Opload-Objekte hat die folgenden Properties:

  • uniqueIdentifier : string

    Eindeutiger Identifier zur Zuordnung der Datei (erzeugt aus dem Dateinamen).

  • name : string

    Dateiname des Uploads

  • size : integer

    Dateigröße in Bytes.

  • progress : float

    Upload-Fortschritt.

  • uploading : bool

    Status, ob die Datei aktuell hochgeladen wird.

  • complete : bool

    Status, ob die Datei vollständig hochgeladen wurde.

  • error : ?mixed

    Im Fehlerfall der vom Server zurückgemeldete Fehler.

  • responseContent : ?object

    Vom Server zurückgemeldete Antwort im Erfolgsfall.

  • abort : func

    Funktion zum Abbrechen des Uplodas der Datei. Die Datei kann über retry erneut hochgleaden werden.

  • cancel : func

    Funktion zum Abbrechen des Uplodas der Datei. Die Datei wird aus der Warteschlange entfernt.

  • retry : func

    Im Fehlerfall oder beim Abbruch kann der Upload wiederholt werden.

• addFile : func(HTML5File file)

  Mauelles Hinzufügen eines HTML5File-Objekts.

• assignDrop : func(DOMNode node)

  Registriert die DOMNode node als Drop-Zone.

• assignBrowse : func(DOMNode node)

  Registriert die DOMNode node als Browse-Button.

• start : func

  Aktiviert den Uploader.

• pause : func

  Pausiert den Uploader.

• reset : func

  Setzt den Uploader zurück.

Zusätzliche props für die Layout-Komponente können von außen über die componentProps-Option übergeben werden.

Uploder-Optionen

Der Uploader unterstüzt die folgenden Optionen (props):

• path : string

  URL zum Endpunkt des Servers, der die API implementiert.

• component : func|React.Component (optional)

  Layout-Komponente zur Darstellung.

• componentProps : object (optional)

  Zusätzliche props für die Layout-Komponente.

• autoStart : boolean (optional, default: true)

  Deaktiviert den automatischen Start des Uploads nach dem Hinzufügen einer Datei.

• clearFileOnSuccess : boolean (optional, default: false)

  Aktiviert, dass Dateien nach erfolgreichem Upload aus der Warteschlange entfernt werden.

• onUploaderComplete : func (optional)

  Callback, wenn alle Dateien hochgeladen wurden.

• onUploaderProgress : func (optional)

  Callback, wenn sich der Fortschritt ändert.

• onUploaderPause : func (optional)

  Callback, wenn der Uploader pausiert wird.

• onUploaderCancel : func (optional)

  Callback, wenn der Uploader zurückgesetzt wird.

• onFileAdded : func(upload) (optional)

  Callback, wenn eine Datei zur Warteschlange hinzgefügt wird

• onFileProgress : func(upload) (optional)

  Callback, wenn sich der Upload-Fortschirtt einer Datei ändert.

• onFileSuccess : func(upload) (optional)

  Callback, wenn eine Datei erfolgreich hochgeladen wurde

• onFileError : func(upload) (optional)

  Callback, wenn der Upload einer Datei fehlgeschlagen ist.

• simultaneousUploads : number (optional, default: 1)

  Limit für den gleichzeitigen Upload mehrerer Dateien.

• testChunks : boolean (optional, default: true)

  Deaktiviert die Prüfung, ob ein Chunk bereits hochgeladen ist. Verringert die anzahl an Requests, bei großen ggfs. abgebrochenen Uploads wird jedoch dann die gesamte Datei erneut hochgeladen.

Uploader als Formular-Feld

Über die Komponenten UploadInput und MultipleUploadsInput können Formuar-Felder erzeugt werden, die einen erfolgten Upload an den Server vermelden.

Diese können mit den AsyncUploadType bzw. MultipleAsyncUploadsType-FormularTypen aus dem BoewaAsyncUploadBundle verknüpft weden.

Analog zum Uploader kann das Layout dieser Komponenten über das component-Property (ggfs. im Zusammenspiel mit componentProps) überschrieben werden:

import React from 'react';
import {createRoot} from "react-dom/client";
import {UploadInput} from '@boewa-software/react-async-uploader';

const InputComponent = ({ value }) => (
    <>
        {value
            ? `File: ${value}`
            : 'Upload File'
        }
        <input type={'hidden'} name={'upload_field'} value={value ? value.identifier : ''} />
    </>
);

const targetElement = document.getElementById("target-element");

const root = createRoot(targetElement);
root.render(
    <UploadInput
        path={'/endpoint-url'}
        component={InputComponent}
    />
);

Das Property initialValue empfängt den Initialwert mit den folgenden Pflicht-Attributen:

• identifier : string

  Unique Identifier der Datei

• name : string

  Dateiname

• progress : number

  Fortschritt des Uploads

• completed : boolean

  Attribut, ob der Upload erfolgreich war.

Die MultipleUploadsInput-Komponente emfängt für initialValue ein Array von Objekten dieses Typs.

Weitere-Komponenten

DropZone

Diese Komponente ermöglicht die Erzeugung einer Drop-Zone für Uploads. Dafür muss der assignDrop-Callback des Uploaders an die Komponente übergeben werden.

BrowseButton

Diese Komponente ermöglicht die Erzeugung eines Browse-Buttons für Uploads. Dafür muss der assignBrowse-Callback des Uploaders an die Komponente übergeben werden.

Weiterentwicklung und DEMO

Infos hierzu sind in der Entwicklungs-Dokumentation zu finden.