ngx-uploadx
v7.0.0
Published
Angular Resumable Upload Module
Downloads
9,188
Readme
ngx-uploadx
Angular Resumable Upload Module
Key Features
- Pause / Resume / Cancel Uploads
- Retries using exponential back-off strategy
- Chunking
Basic usage
- Add ngx-uploadx module as dependency:
npm install ngx-uploadx
- Import UploadxModule:
//...
import { UploadxModule } from 'ngx-uploadx';
@NgModule({
imports: [
UploadxModule,
// ...
});
- Add
uploadx
directive to the component template and provide the required options:
// Component code
//...
import { UploadxOptions, UploadState } from 'ngx-uploadx';
@Component({
selector: 'app-home',
template: ` <input type="file" [uploadx]="options" (state)="onUpload($event)" /> `
})
export class AppHomeComponent {
options: UploadxOptions = { endpoint: `[URL]` };
onUpload(state: UploadState) {
console.log(state);
//...
}
}
Please navigate to the src/app sub-folder for more detailed examples.
Server-side setup
API
UploadxOptions
allowedTypes
Allowed file types (directive only)authorize
Function used to authorize requests (example)autoUpload
Auto start upload when files added. Default value:true
storeIncompleteHours
Limit upload lifetime. Default value:24
chunkSize
Fixed chunk size. If not specified, the optimal size will be automatically adjusted based on the network speed. If set to0
, normal unloading will be used instead of chunkedmaxChunkSize
Dynamic chunk size limitconcurrency
Set the maximum parallel uploads. Default value:2
endpoint
URL to create new uploads. Default value:'/upload'
responseType
Expected server response typeheaders
Headers to be appended to each HTTP requestmetadata
Custom metadata to be added to the uploaded filesmultiple
Allow selecting multiple files. Default value:true
(directive only)prerequest
Function called before every request (example)retryConfig
Object to configure retry settings:maxAttempts
Maximum number of retry attempts. Default value:8
shouldRestartCodes
Upload not exist and will be restarted. Default value:[404, 410]
authErrorCodes
If one of these codes is received, the request will be repeated with an updated authorization token. Default value:[401]
shouldRetryCodes
Retryable 4xx status codes. Default value:[408, 423, 429, 460]
shouldRetry
Overrides the built-in function that determines whether the operation should be retriedminDelay
Minimum (initial) retry interval. Default value:500
maxDelay
Maximum retry interval. Default value:50_000
onBusyDelay
Delay used between retries for non-error responses with missing range/offset. Default value:1000
timeout
Time interval after which unfinished requests must be retriedkeepPartial
Determines whether partial chunks should be kept
token
Authorization token as astring
or function returning astring
orPromise<string>
uploaderClass
Upload API implementation. Built-in:UploaderX
(default),Tus
. More examples
UploadxModule
Adds directives and provide static method withConfig
for global configuration (example).
:bulb: No need to import
UploadxModule
if you do not use theuploadx
oruploadxDrop
directives in your application.
Directives
<div uploadxDrop>
<label class="file-drop">
<input type="file" [uploadx]="options" [control]="control" (state)="onState($event)" />
</label>
</div>
uploadx
File input directive.
selectors: [uploadx]
, uploadx
Properties:
@Input() uploadx: UploadxOptions
Set directive options@Input() options: UploadxOptions
Alias foruploadx
property@Input() control: UploadxControlEvent
Control the uploads@Output() state: EventEmitter<UploadState>
Event emitted on upload state change
uploadxDrop
File drop directive.
selector: uploadxDrop
:bulb: Activates the
.uploadx-drop-active
class on DnD operations.
UploadxService
init(options?: UploadxOptions): Observable<UploadState>
Initializes service. Returns Observable that emits a new value on progress or status changes.
// @example: uploadxOptions: UploadxOptions = { concurrency: 4, endpoint: `${environment.api}/upload`, uploaderClass: Tus }; ngOnInit() { this.uploadService.init(this.uploadxOptions) .subscribe((state: UploadState) => { console.log(state); // ... } }
connect(options?: UploadxOptions): Observable<Uploader[]>
Initializes service. Returns Observable that emits the current queue.
// @example: @Component({ template: ` <input type="file" uploadx"> <div *ngFor="let item of uploads$ | async">{{item.name}}</div> `, changeDetection: ChangeDetectionStrategy.OnPush }) export class UploadsComponent { uploads$: Observable<Uploader[]>; options: UploadxOptions = { endpoint: `${environment.api}/upload?uploadType=uploadx`, headers: { 'ngsw-bypass': 1 } } constructor(private uploadService: UploadxService) { this.uploads$ = this.uploadService.connect(this.options); }
disconnect(): void
Terminate all uploads and clears the queue.
ngOnDestroy(): void
Called when the service instance is destroyed. Interrupts all uploads and clears the queue and subscriptions.
:bulb: Normally
ngOnDestroy()
is never called becauseUploadxService
is an application-wide service, and uploading will continue even after the upload component is destroyed.handleFiles(files: FileList | File | File[], options = {} as UploadxOptions): void
// @example: onFilesSelected(): void { this.uploadService.handleFiles(this.fileInput.nativeElement.files); }
Creates uploaders for files and adds them to the upload queue.
control(event: UploadxControlEvent): void
Uploads control.
// @example: pause(uploadId?: string) { this.uploadService.control({ action: 'pause', uploadId }); } setToken(token: string) { this.uploadService.control({ token }); }
request<T = string>(config: AjaxRequestConfig): Promise<AjaxResponse<T>>
Make HTTP request with
axios
like interface. (example)state(): UploadState[]
Returns the current state of uploads.
// @example: uploads: UploadState[]; constructor(private uploadService: UploadxService) { // restore background uploads this.uploads = this.uploadService.state(); }
queue: Uploader[]
Uploaders array.
// @example: export class UploadComponent { state: UploadState; options: UploadxOptions = { concurrency: 1, multiple: false, endpoint: `${environment.api}/upload`, } constructor(private uploadService: UploadxService) { this.state = this.uploadService.queue[0] || {}; }
events: Observable<UploadState>
Uploads state events.
DI tokens
UPLOADX_FACTORY_OPTIONS
: override default configurationUPLOADX_OPTIONS
: global optionsUPLOADX_AJAX
: override internal ajax lib
Demo
Checkout the Demo App or run it on your local machine:
- Run script
npm start
- Navigate to
http://localhost:4200/
Build
Run npm run build:pkg
to build the lib.
packaged by ng-packagr
Bugs and Feedback
For bugs, questions and discussions please use the GitHub Issues.
Contributing
Pull requests are welcome!
To contribute, please read contributing instructions.
License
The MIT License (see the LICENSE file for the full text)