@boewa-software/react-async-uploader NPM

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.

React Uploader Async Form Component

resumablejs

@infinitebrahmanuniverse/nolb-_boe @everything-registry/sub-chunk-135 @zalastax/nolb-_boe

2 years ago

2 years ago

6 years ago

6 years ago