10. 事件

事件

The plugin supports various events and allows advanced features like returning event results for validating and manipulating your file upload dynamically. The section is categorized into file events, error events, and event manipulation.

文件事件
异常事件
操作事件

文件事件

Events available for file management and file manipulation.

change

This event is triggered whenever a single file or multiple files are selected in the file input via the file browse button.

Example:

$('#input-id').on('change', function(event) {
    console.log("change");
});

fileselect

This event is triggered after files are selected in the file input via the file browse button. This is slightly different than the change event in the sense that this will be triggered even if the file browse dialog is cancelled.

Example:

$('#input-id').on('fileselect', function(event, numFiles, label) {
    console.log("fileselect");
});

fileclear

This event is triggered when the file input remove button or preview window close icon is pressed for clearing the file preview.

Example:

$('#input-id').on('fileclear', function(event) {
    console.log("fileclear");
});

filecleared

This event is triggered after the files in the preview are cleared.

Example:

$('#input-id').on('filecleared', function(event) {
    console.log("filecleared");
});

fileloaded

This event is triggered after a file is loaded in the preview. Additional parameters available are:

file: the file object instance
previewId: the identifier for the preview file container
index: the zero-based sequential index of the loaded file in the preview list
reader: the FileReader instance if available.

Example:

$('#input-id').on('fileloaded', function(event, file, previewId, index, reader) {
    console.log("fileloaded");
});

filereset

This event is triggered when the file input is reset to initial value.

Example:

$('#input-id').on('filereset', function(event) {
    console.log("filereset");
});

fileimageloaded

This event is triggered when each file image is fully loaded in the preview window. This is only applicable for image file previews and if showPreview is set to true. Additional parameters available are:

previewId: the identifier for the preview file container.

Example:

$('#input-id').on('fileimageloaded', function(event, previewId) {
    console.log("fileimageloaded");
});

fileimagesloaded This event is triggered when all file images are fully loaded in the preview window. This is only applicable for image file previews and if showPreview is set to true.

Example:

$('#input-id').on('fileimagesloaded', function(event) {
    console.log("fileimagesloaded");
});

fileimageresized

This event is triggered when a file image in preview window is resized based on the resizeImage and maxImageWidth/maxImageHeight settings. This is only applicable for image file previews and if showPreview is set to true. Additional parameters available are:

previewId: the identifier for the preview file container.
index: the zero-based sequential index of the loaded file in the preview list

When all images in the preview have been resized, the above event will fire once more without any of the parameters above (i.e. previewId and index as undefined).

Example:

$('#input-id').on('fileimageresized', function(event, previewId, index) {
    console.log("fileimageresized");
});

fileimageresized

This event is triggered when all file images in preview window are resized based on the resizeImage and maxImageWidth/maxImageHeight settings. This is only applicable for image file previews and if showPreview is set to true.

Example:

$('#input-id').on('fileimagesresized', function(event) {
    console.log("fileimagesresized");
});

filebrowse

This event is triggered when the file browse button is clicked to open the file selection dialog.

Example:

$('#input-id').on('filebrowse', function(event) {
    console.log("File browse triggered.");
});

filebatchselected This event is triggered after a batch of files are selected and displayed in the preview. Additional parameters available are:

files: the file stack array (or empty object if not available).

Example:

$('#input-id').on('filebatchselected', function(event, files) {
    console.log('File batch selected triggered');
});

fileselectnone

This event is triggered when no files are selected by the user for a repeat selection scenario (i.e. on a file input that already contains previously selected files). This event is better applicable for browsers like Google Chrome, which clear the file input when the file selection dialog is cancelled. For other browsers, this event is typically triggered only when one resets the form or clears file input (using the remove button).

Example:

$('#input-id').on('fileselectnone', function(event) {
    console.log("Huh! No files were selected.");
});

filelock This event is triggered when the upload process is launched by clicking a upload button, and the entire widget is locked (disabled) until upload is getting processed. Only the Cancel button will be enabled when the file input is locked. Additional parameters available are:

filestack: the array of selected file objects.
uploadExtraData: the uploadExtraData settings for the plugin (will return an empty object if not set).

$('#input-id').on('filelock', function(event, filestack, extraData) {
    var fstack = filestack.filter(function(n){ return n != undefined });
    console.log('Files selected - ' + fstack.length);
});

fileunlock

This event is triggered when the upload process is completed (successfully or with error). The entire widget is unlocked (enabled) and reverts to initial state. Additional parameters available are:

filestack: the array of selected file objects.
uploadExtraData: the uploadExtraData settings for the plugin (will return an empty object if not set).

$('#input-id').on('fileunlock', function(event, filestack, extraData) {
    var fstack = filestack.filter(function(n){ return n != undefined });
    console.log('Files selected - ' + fstack.length);
});

filepredelete

This event is triggered before deletion of each thumbnail file in the initialPreview content set. Additional parameters available are:

key: the key passed within initialPreviewConfig for the selected file for delete.
jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available). data: the output of deleteExtraData object.

$('#input-id').on('filepredelete', function(event, key) {
    console.log('Key = ' + key);
});

filedeleted

This event is triggered after deletion of each thumbnail file in the initialPreview content set. Additional parameters available are:

key: the key passed within initialPreviewConfig for the selected file that will be passed as POST data to the url.
jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available). data: the output of deleteExtraData object.

$('#input-id').on('filedeleted', function(event, key) {
    console.log('Key = ' + key);
});
```JavaScript
### filepreajax
This event is triggered before submission of the upload ajax request. You could use this event to manipulate the uploadExtraData before its submitted via ajax. The following additional parameters are also available specifically and only if the upload is triggered via each thumbnail upload button.

* `previewId`: the identifier of each file's parent thumbnail div element in the preview window.

* `index`: the zero-based index of the file in the file stack.
```JavaScript
$('#input-id').on('filepreajax', function(event, previewId, index) {
    console.log('File pre ajax triggered');
});

filepreupload

This event is triggered only for ajax uploads and before upload of each thumbnail file. This event is triggered after filepreajax and within the ajax beforeSend event. Additional parameters available are:

data: This is a data object (associative array) that sends the following information, whose keys are:
- form: FormData, object which is passed via XHR2 (or empty object if not available).
- files: array, the file stack array (or empty object if not available).
- filenames: array, the client file names for each of the files in the stack array (or empty object if not available).
- filescount: int, the count of files selected including uploaded (will basically return the output of getFilesCount method).
- extra: the uploadExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- reader: the FileReader instance if available.
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).
previewId: the identifier of each file's parent thumbnail div element in the preview window.
index: the zero-based index of the file in the file stack.

$('#input-id').on('filepreupload', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File pre upload triggered');
});

fileuploaded

This event is triggered only for ajax uploads and after upload is completed for each thumbnail file. This event is triggered ONLY for ajax uploads and in the following scenarios:

When the upload icon in each preview thumbnail is clicked and file is uploaded successfully, OR
When you have uploadAsync set to true and you have triggered batch upload. In this case, the fileuploaded event is triggered after every individual selected file is uploaded successfully.

The additional parameters available with this eventare:

data: This is a data object (associative array) that sends the following information, whose keys are:
- form: FormData, object which is passed via XHR2 (or empty object if not available).
- files: array, the file stack array (or empty object if not available).
- filenames: array, the client file names for each of the files in the stack array (or empty object if not available).
- filescount: int, the count of files selected including uploaded (will basically return the output of getFilesCount method).
- extra: the uploadExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- reader: the FileReader instance if available.
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).
previewId: the identifier of each file's parent thumbnail div element in the preview window.
index: the zero-based index of the file in the file stack.

$('#input-id').on('fileuploaded', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File uploaded triggered');
});

filebatchpreupload

This event is triggered only for ajax uploads and before a batch upload (for both synchronous and asynchronous uploads) after the upload button is clicked. Additional parameters available are:

data: This is a data object (associative array) that sends the following information, whose keys are:
- form: FormData, object which is passed via XHR2 (or empty object if not available).
- files: array, the file stack array (or empty object if not available).
- filenames: array, the client file names for each of the files in the stack array (or empty object if not available).
- filescount: int, the count of files selected including uploaded (will basically return the output of getFilesCount method).
- extra: the uploadExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- reader: the FileReader instance if available.
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).

$('#input-id').on('filebatchpreupload', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File batch pre upload');
});

filebatchuploadsuccess

This event is triggered only for ajax uploads and after a successful synchronous batch upload. This event is triggered ONLY for ajax uploads and in the following scenario:

When you have uploadAsync set to false and you have triggered batch upload. In this case, the filebatchuploadsuccess event is triggered after all files have been successfully uploaded.

The additional parameters available with this event are:

data: This is a data object (associative array) that sends the following information, whose keys are:
- form: FormData, object which is passed via XHR2 (or empty object if not available).
- files: array, the file stack array (or empty object if not available).
- filenames: array, the client file names for each of the files in the stack array (or empty object if not available).
- filescount: int, the count of files selected including uploaded (will basically return the output of getFilesCount method).
- extra: the uploadExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- reader: the FileReader instance if available.
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).

$('#input-id').on('filebatchuploadsuccess', function(event, data, previewId, index) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File batch upload success');
});

filebatchuploadcomplete

This event is triggered only for ajax uploads and after completion of either the synchronous OR asynchronous ajax batch upload. Additional parameters available are:

files: the file stack array (or empty object if not available).
extra: the uploadExtraData settings for the plugin (or empty object if not available).

$('#input-id').on('filebatchuploadcomplete', function(event, files, extra) {
    console.log('File batch upload complete');
});

filesuccessremove

This event is triggered after a successfully uploaded thumbnail is removed using the thumbnail delete button. This is usually applicable when you have showUploadedThumbs set to true. Additional parameters available are:

id: the HTML ID attribute for the thumbnail container element.

$('#input-id').on('filesuccessremove', function(event, id) {
    if (some_processing_function(id)) {
       console.log('Uploaded thumbnail successfully removed');
    } else {
        return false; // abort the thumbnail removal
    }
});

filedisabled

This event is triggered when the file input widget is disabled (prevents any modification) using the disable method.

$('#input-id').on('filedisabled', function(event) {
    console.log('File disabled');
});

fileenabled

This event is triggered when the file input widget is enabled (allows modification) using the enable method.

$('#input-id').on('fileenabled', function(event) {
    console.log('File enabled');
});

filesorted

This event is triggered when the files are sorted / rearranged via drag drop in the initial preview. The following parameters will be additionally sent as a JSON object whose keys are.

previewId: the preview thumbnail container's HTML ID attribute
oldIndex: the old index of the thumbnail in initialPreview
newIndex: the new index of the thumbnail in initialPreview
stack: the modified initialPreviewConfig after the sort.

$('#input-id').on('filesorted', function(event, params) {
    console.log('File sorted ', params.previewId, params.oldIndex, params.newIndex, params.stack);
});

filezoomshow

This event is triggered when the zoom button is clicked to show the content detailed preview in a modal dialog. The following parameters will be additionally sent as a JSON object whose keys are.

sourceEvent: Event, the source modal dialog event that triggered the show.bs.modal.
previewId: string, the preview thumbnail container's HTML ID attribute
modal: jQuery object, the modal dialog object

$('#input-id').on('filezoomshow', function(event, params) {
    console.log('File zoom show ', params.sourceEvent, params.previewId, params.modal);
});

filezoomshown

This event is triggered after the modal has been made visible to the user (will wait for CSS transitions to complete). The following parameters will be additionally sent as a JSON object whose keys are.

sourceEvent: Event, the source modal dialog event that triggered the show.bs.modal.
previewId: string, the preview thumbnail container's HTML ID attribute
modal: jQuery object, the modal dialog object

$('#input-id').on('filezoomshown', function(event, params) {
    console.log('File zoom shown ', params.sourceEvent, params.previewId, params.modal);
});

filezoomhide

This event is triggered after the modal is hidden by closing the dialog. The following parameters will be additionally sent as a JSON object whose keys are.

sourceEvent: Event, the source modal dialog event that triggered the show.bs.modal.
previewId: string, the preview thumbnail container's HTML ID attribute
modal: jQuery object, the modal dialog object

$('#input-id').on('filezoomhide', function(event, params) { console.log('File zoom hide ', params.sourceEvent, params.previewId, params.modal); });

filezoomhidden

This event is triggered after the modal has finished being hidden from the user (will wait for CSS transitions to complete). The following parameters will be additionally sent as a JSON object whose keys are.

sourceEvent: Event, the source modal dialog event that triggered the show.bs.modal.
previewId: string, the preview thumbnail container's HTML ID attribute
modal: jQuery object, the modal dialog object

$('#input-id').on('filezoomhidden', function(event, params) {
    console.log('File zoom hidden ', params.sourceEvent, params.previewId, params.modal);
});

filezoomloaded

This event is triggered after the modal has loaded content using the remote option. The following parameters will be additionally sent as a JSON object whose keys are.

sourceEvent: Event, the source modal dialog event that triggered the show.bs.modal.
previewId: string, the preview thumbnail container's HTML ID attribute
modal: jQuery object, the modal dialog object

$('#input-id').on('filezoomloaded', function(event, params) {
    console.log('File zoom loaded ', params.sourceEvent, params.previewId, params.modal);
});

filezoomprev

This event is triggered in the zoomed preview mode, when the previous navigation button is clicked to view the previous file (also is triggered when the keyboard left arrow is pressed in the zoom mode).

previewId: string, the preview thumbnail container's HTML ID attribute
modal: jQuery object, the modal dialog object

$('#input-id').on('filezoomprev', function(event, params) {
    console.log('File zoom previous ', params.previewId, params.modal);
});

filezoomnext

This event is triggered in the zoomed preview mode, when the next navigation button is clicked to view the next file (also is triggered when the keyboard right arrow is pressed in the zoom mode).

previewId: string, the preview thumbnail container's HTML ID attribute
modal: jQuery object, the modal dialog object

$('#input-id').on('filezoomnext', function(event, params) {
    console.log('File zoom next ', params.previewId, params.modal);
});

异常事件

Events available for file validation errors.

fileerror

This event is triggered when a client validation error is encountered for an uploaded file. This allows access to an object data as a parameter.

data: object/associative array containing the following:
- id: the preview thumbnail identifier (or undefined if not available)
- index: the file index/preview thumbnail index (or undefined if not available)
- file: the file object (or undefined if not available)
- reader: the file reader instance (or undefined if not available)
- files: the file stack array (or empty object if not available).
msg: string, the error message generated

Example:

$('#input-id').on('fileerror', function(event, data, msg) {
   console.log(data.id);
   console.log(data.index);
   console.log(data.file);
   console.log(data.reader);
   console.log(data.files);
   // get message
   alert(msg);
});

fileimageresizeerror

This event is triggered when an error or exception is received while resizing images (see resizeImage property). Additional parameters available are:

data: object/associative array containing the following:
- id: the preview thumbnail identifier (or undefined if not available)
- index: the file index/preview thumbnail index (or undefined if not available)
msg: string, the error message generated

Example:

$('#input-id').on('fileimageresizeerror', function(event, data, msg) {
   console.log(data.id);
   console.log(data.index);
   // get message
   alert(msg);
});

fileuploaderror

This event is triggered only for ajax uploads and when an upload or file input validation error is encountered primarily for ajax uploads. This event is triggered ONLY for ajax uploads and in the following scenarios:

When the upload icon in each preview thumbnail is clicked and file faced a validation error in upload, OR

When you have uploadAsync set to true and you have triggered batch upload. In this case, the fileuploaderror event is triggered after any selected file faces an upload validation error.

The additional parameters available with this event are:

data: This is a data object (associative array) that sends the following information, whose keys are:
- id: the preview thumbnail identifier (or undefined if not available)
- index: the file index/preview thumbnail index (or undefined if not available)
- form: FormData, object which is passed via XHR2 (or empty object if not available).
- files: array, the file stack array (or empty object if not available).
- filenames: array, the client file names for each of the files in the stack array (or empty object if not available).
- filescount: int, the count of files selected including uploaded (will basically return the output of getFilesCount method).
- extra: the uploadExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- reader: the FileReader instance if available.
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).
msg: string, the error message generated

$('#input-id').on('fileuploaderror', function(event, data, msg) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File upload error');
   // get message
   alert(msg);
});

filebatchuploaderror

This event is triggered only for ajax uploads and after an upload validation error is faced for synchronous batch upload. This event is triggered ONLY for ajax uploads and in the following scenario:

When you have uploadAsync set to false and you have triggered batch upload. In this case, the filebatchuploaderror event is triggered after any file faces an upload error OR you return an error via your server action JSON response.

The additional parameters available with this event are:

data: This is a data object (associative array) that sends the following information, whose keys are:
- form: FormData, object which is passed via XHR2 (or empty object if not available).
- files: array, the file stack array (or empty object if not available).
- filenames: array, the client file names for each of the files in the stack array (or empty object if not available).
- filescount: int, the count of files selected including uploaded (will basically return the output of getFilesCount method).
- extra: the uploadExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- reader: the FileReader instance if available.
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).
msg: string, the error message generated

$('#input-id').on('filebatchuploaderror', function(event, data, msg) {
    var form = data.form, files = data.files, extra = data.extra,
        response = data.response, reader = data.reader;
    console.log('File batch upload error');
   // get message
   alert(msg);
});

filedeleteerror

This event is triggered when an error is faced in deletion of each thumbnail file in the initialPreview content set. Additional parameters available are:

data: This is a data object (associative array) that sends the following information, whose keys are:
- id: the preview thumbnail identifier (or undefined if not available)
- index: the file index/preview thumbnail index (or undefined if not available)
- extra: the deleteExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).
msg: string, the error message generated

$('#input-id').on('filedeleteerror', function(event, data, msg) {
    console.log('File delete error');
   // get message
   alert(msg);
});

filefoldererror

This event is triggered when a folder or multiple folders have been dragged & dropped to the file preview drop zone. Additional parameters available are:

folders: int, The count of folders dropped.
msg: string, the error message generated

$('#input-id').on('filefoldererror', function(event, folders, msg) {
    console.log('File folder dropped error');
   // get message
   alert(msg);
});

filecustomerror

This event is triggered manually by the user from one of the other events by returning an error object from the source event. Refer Event Manipulation section for details. Additional parameters available are:

data: This is a data object (associative array) that sends the following information, whose keys are:
- form: FormData, object which is passed via XHR2 (or empty object if not available).
- files: array, the file stack array (or empty object if not available).
- filenames: array, the client file names for each of the files in the stack array (or empty object if not available).
- filescount: int, the count of files selected including uploaded (will basically return the output of getFilesCount method).
- extra: the uploadExtraData settings for the plugin (or empty object if not available).
- response: the data sent via ajax response (or empty object if not available).
- reader: the FileReader instance if available.
- jqXHR: the jQuery XMLHttpRequest object used for this transaction (if available).
msg: string, the error message generated

$("#input").on('filecustomerror', function(event, params, msg) {
   console.log(params.id);
   console.log(params.index);
   console.log(params.data);
   // get message
   alert(msg);
});

操作事件

With release v4.1.8, you can manipulate events and add your custom validation through other events, by returning data for most of the events and use it for advanced processing. This functionality is supported for most events listed in the events section, except for the following events.

fileclear
filecleared
filereset
fileerror
fileuploaderror
filebatchuploaderror
filedeleteerror
filefoldererror
filecustomerror
fileuploaded
filebatchuploadcomplete
filebatchuploadsuccess

For all the events other than ones mentioned above, you can set a custom validation error which will be triggered just before upload is initiated.

This will enable you to add your additional custom validations to enhance the fileinput to be used for innumerous scenarios. It will allow an ability to return an associative object with any of the fileinput events (except the except the events above) e.g. change, fileselect, filepreupload, filebatchpreupload etc.

The object can return the following keys:

message: string, the validation error message to be displayed before upload. If this is set the plugin will automatically abort the upload whenever called and display this as an error message. You can use this property for example to read a file and perform your own custom validation.
data: object, an optional associative array of additional data at abort, that you can pass for usage later.

Example

STEP 1: You can trigger for example an error to abort from filepreupload

$('#input').on('filepreupload', function(event, data, previewId, index, jqXHR) {
    // do your validation and return an error like below
    if (customValidationFailed) {
       return {
           message: 'You are not allowed to do that',
           data: {key1: 'Key 1', detail1: 'Detail 1'}
       };
   }
});

The above abort will be triggered at time of upload for (ajax uploads) OR at form submission (for non-ajax uploads).

STEP 2: Reading additional data at abort by trapping the filecustomerror event

$('#input').on('filecustomerror', function(event, params) {
   // params.abortData will contain the additional abort data passed
   // params.abortMessage will contain the aborted error message passed
});

As mentioned before, the above functionality of raising a filecustomerror is not supported in the following events:

fileclear
filecleared
filereset
fileerror
fileuploaderror
filebatchuploaderror
filedeleteerror
filecustomerror
fileuploaded
filebatchuploadcomplete
filebatchuploadsuccess

10. 事件

事件

文件事件

change

fileselect

fileclear

filecleared

fileloaded

filereset

fileimageloaded

fileimageresized

fileimageresized

filebrowse

fileselectnone

fileunlock

filepredelete

filedeleted

filepreupload

fileuploaded

filebatchpreupload

filebatchuploadsuccess

filebatchuploadcomplete

filesuccessremove

filedisabled

fileenabled

filesorted

filezoomshow

filezoomshown

filezoomhide

filezoomhidden

filezoomloaded

filezoomprev

filezoomnext

异常事件

fileerror

fileimageresizeerror

fileuploaderror

filebatchuploaderror

filedeleteerror

filefoldererror

filecustomerror

操作事件

Clone this wiki locally