Upload Library: Feature Details, Direct Cloud Upload, Events and Methods Demo Examples

Last updated: 1 month ago

Category: Examples

The upload module supports batch uploading in multiple formats, with direct cloud transmission to Amazon S3, Cloud Storage, Azure Blob Storage, OSS, COS, Kodo, UPYUN and other cloud services.

File Extensions

The limit parameter can set file restrictions, where limit.suffix specifies allowed file extensions; multiple extensions can be separated by commas (,).

Single File Size

The limit parameter can set file restrictions, where limit.size specifies the maximum size (in bytes) for a single file upload, with unit M.

Server-Side Validation

Before actual file upload, preliminary validation (file type, size, etc.) can be performed via the limit parameter. When files reach the server, it always returns data which may indicate errors or failed server-side validation.

Since server environments vary, we need the success function for server-side validation.

This function accepts one parameter (server response data) and defaults to checking code==200. It must ultimately return true or false, allowing flexible handling of different platforms' response formats.

Manual Upload

By default, files upload automatically upon selection. To queue all files first and upload together later, set manual:true.

Batch Add/Remove

The module only requires a single select button by default. To show bulk upload and clear buttons, use uploadBtn:true and clearBtn:true.

Typically used in manual upload scenarios.

Custom Button Targets

The choose, upload, and clear buttons don't need to be auto-created - they can point to existing elements via chooseBtn.target, uploadBtn.target, and clearBtn.target parameters.

Status Bar Display

The status bar has two parts: file restriction info and upload statistics, controlled by the status parameter:

Getting Values

Two methods to get values:

Direct Cloud Upload

Cloud direct upload requires configuring the cloud parameter (disabled by default - uploads to local server). Properties:

• enable: Enable cloud upload (default false)
• field: Field name for cloud storage (default 'file')
• domain: Domain for concatenating file URLs
• server: Cloud server URL
• append: Function to append FormData with two params:
  • data: FormData (already contains dynamic page data)
  • file: Current file (file.name = filename)
• map: Object mapping component properties to cloud platform response properties (name, url, size, time). For nested responses like {time:'',data:{url:'',size:''}}, use "data.url"

For security, server credentials should be in dynamic files. The module first requests upload authorization (may include policy, authorization, token etc.), which gets appended to FormData.

Cloud Upload Logic

The cloud upload process:

1. Frontend requests token/policy/signature from dynamic page
2. Dynamic page (with SDK) generates token using cloud credentials
3. Frontend sends token + file via FormData to cloud server
4. Cloud server validates and returns response
5. Frontend notifies local server to store file URL if successful
6. Frontend updates final upload status

File Status Flow

File status progression:

1. Selected: File read as Blob - gets size/name/time properties
2. Validation: Generates {file,valid:{passed,msg}} object
3. Render: Adds wrapEl, updateEl, removeEl, stateEl, progEl properties (progress=rendered)
4. Uploading: Status changes to uploading → uploaded when complete
5. Server processing: Status → received
6. Response handling: Adds resp/data={url,code,msg,time} properties, final status (success/error)

            
item = {
    valid:{passed:true,msg:'Validation passed'},
    resp:{code:200,key:'xxx.jpg',hash:'xxx'},
    data:{url,time,size},
    progress:'received',
    file,
    wrapEl,
    fileEl,
    progEl,
    uploadEl,
    removeEl,
    stateEl,
    msgEl,
}
            
        

Initial Display

The value parameter can initialize displayed files, but these initialized files should already exist on the server as real files. Based on the fundamental principle of type=file controls, only manually selected disk files can be uploaded. Therefore, initialized files won't be uploaded - they're only for display.

Another method for initial display is to directly write file addresses in the target node, separated by commas (,).

Using Icons

The module automatically recognizes file types as either Media type or Other type. Media types include: image, audio and video. If the user doesn't specify an icon for Other type, it will display as _icon-file by default.

Removing Items

There are two methods for deleting items: remove() and clear().

Wait Functions

The module provides 4 key wait functions: b4Upload, b4Remove, b4Clear and b4UploadAll. These should return a Promise - execution continues if resolved, stops if rejected.

Event Listeners

This module offers event listeners for the complete upload workflow, covering: changed, dropped, pasted, rendered, uploading, uploaded, and received events.

Destruction and Initialization

Use the destroy() method to destroy the instance. To restore functionality, use init() to reinitialize.