10. 事件

事件

该插件支持各种事件，并允许高级功能，如返回事件结果来验证和动态操作文件上传。该部分分为文件事件，异常事件和事件处理。

文件事件
异常事件
事件处理

文件事件

可用于文件管理和文件操作的事件。

change

只要通过文件浏览按钮在文件输入控件中选择单个文件或多个文件，就会触发此事件。

范例：

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

fileselect

通过文件浏览按钮在文件输入中选择文件后触发此事件。这与change事件稍有不同，即使文件浏览对话框被取消，它也会被触发。

范例：

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

fileclear

当文件输入删除按钮或预览窗口关闭图标被按下以清除文件预览时触发此事件。

范例：

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

filecleared

在预览中的文件被清除后触发此事件。

范例：

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

fileloaded

在预览中加载文件后触发此事件。附加参数有：

file：文件对象实例
previewId：预览文件容器的标识符（id）
index：预览列表中加载的文件的基于0的顺序索引
reader：:FileReader实例，如果浏览器支持它

范例：

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

filereset

当文件输入被重置为初始值时触发此事件。

范例：

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

fileimageloaded

每个图像文件在预览窗口中完全加载时触发此事件。它只适用于图像文件预览且showPreview设置为true的情况。附加参数有：

previewId：预览文件容器的id。

范例：

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

fileimagesloaded

所有图像文件在预览窗口中完全加载时触发此事件。它只适用于图像文件预览且showPreview设置为true的情况。

范例：

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

fileimageresized

当一个预览的图像文件由于resizeImage或者maxImageWidth/maxImageHeight设置而发生调整时触发这个事件。它只适用于图像文件预览且showPreview设置为true的情况。附加参数如下：

previewId：预览文件容器的标识符（id）
index：预览列表中加载的文件的基于0的顺序索引

当预览中所有图像文件都发生调整后，上述事件将再次触发，无任何上述参数（即，previewId和index 值为 undefined）。

范例：

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

fileimagesresized

当所有预览的图像文件由于resizeImage或者maxImageWidth/maxImageHeight设置都发生调整时触发这个事件。它只适用于图像文件预览且showPreview设置为true的情况。

范例：

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

filebrowse

单击文件浏览按钮以打开文件选择对话框时触发此事件。

范例：

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

filebatchselected

在预览中选择并显示一批文件后触发此事件。附加参数有：

files：文件对象实例（如果FileReader不可用，则为空对象）。

范例：

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

fileselectnone

当用户由于重复选择场景（即，在已经包含先前选择的文件的文件输入）而没有选择任何文件时，触发此事件。此事件更适用于Google Chrome等浏览器，当文件选择对话框被取消时，它清除文件输入。对于其他浏览器，此事件通常仅在复位表单或清除文件输入（使用删除按钮）时才会触发。

范例：

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

filelock

当通过点击上传按钮启动上传过程时触发此事件，并且整个小部件被锁定（禁用），直到上传被处理。当文件输入被锁定时，只有取消按钮被启用。附加参数有：

filestack：已选择的文件对象数组。
uploadExtraData：这个插件的uploadExtraData设置（如果没设置，则返回空对象）。

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

fileunlock

当上传过程完成（成功或有错误）时触发此事件。整个小部件被解锁（启用）并恢复到初始状态。附加参数有：

filestack：已选择的文件对象数组。
uploadExtraData：这个插件的uploadExtraData设置（如果没设置，则返回空对象）。

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

filepredelete

在删除initialPreview内容集中的每个缩略图文件之前触发此事件。附加参数有：

key：要删除的已选文件在initialPreviewConfig中传入的关键字。
jqXHR：用于此事务的jQuery XMLHttpRequest对象（如果可用）。
data：输出deleteExtraData对象。

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

filedeleted

在删除initialPreview内容集中的每个缩略图文件之后触发此事件。附加参数有：

key：要删除的已选文件在initialPreviewConfig中传入的关键字。
jqXHR：用于此事务的jQuery XMLHttpRequest对象（如果可用）。
data：输出deleteExtraData对象。

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

filepreajax

此事件在提交ajax请求上传之前触发。你可以在ajax提交之前使用此事件操纵uploadExtraData。只有通过每个缩略图上传按钮触发上传时，才可以使用以下附加参数：

previewId：预览窗口中每个文件的缩略图div父节点的id。
index：预览列表中加载的文件的基于0的顺序索引

$('#input-id').on('filepreajax', function(event, previewId, index) {
    console.log('File pre ajax triggered');
});

filepreupload

此事件仅在ajax上传且上载每个缩略图文件之前触发。此事件在filepreajax之后伴随ajax的beforeSend事件触发。附加参数有：

data：这是一个数据对象（关联数组），它发送以下信息，其关键字是：
- form：FormData，通过XHR2传递的对象（如果不可用，则为空对象）。
- files: 数组，文件栈数组（如果不可用，则为空对象）。
- filenames：数组，堆栈数组中每个文件的客户端文件名（如果不可用，则为空对象）。
- filescount: int，所选文件的计数包括已经上传的文件（基本上返回getFilesCount方法的输出）。
- extra：该插件的uploadExtraData设置（如果不可用，则为空对象）。
- response：通过ajax响应发送的数据（如果不可用，则为空对象）。
- reader：FileReader实例，如果可用。
- jqXHR：用于此事务的jQuery XMLHttpRequest对象（如果可用）。
previewId：预览窗口中每个文件的缩略图div父节点的id。
index：预览列表中加载的文件的基于0的顺序索引

$('#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

此事件仅在ajax上传且上载每个缩略图文件之后触发。此事件只有是AJAX上传并在以下场景才会触发：

当单击每个预览缩略图中的上传图标并且文件上传成功时，或者
当你将uploadAsync设置为true并且已触发批量上传时。在这种情况下，fileuploaded事件在每个单独的选定文件成功上传之后被触发。

此事件可用的其他参数：

data：这是一个数据对象（关联数组），它发送以下信息，其关键字是：
- form：FormData，通过XHR2传递的对象（如果不可用，则为空对象）。
- files: 数组，文件栈数组（如果不可用，则为空对象）。
- filenames：数组，堆栈数组中每个文件的客户端文件名（如果不可用，则为空对象）。
- filescount: int，所选文件的计数包括已经上传的文件（基本上返回getFilesCount方法的输出）。
- extra：该插件的uploadExtraData设置（如果不可用，则为空对象）。
- response：通过ajax响应发送的数据（如果不可用，则为空对象）。
- reader：FileReader实例，如果可用。
- jqXHR：用于此事务的jQuery XMLHttpRequest对象（如果可用）。
previewId：预览窗口中每个文件的缩略图div父节点的id。
index：预览列表中加载的文件的基于0的顺序索引

$('#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

此事件仅对于ajax上传的上传按钮被单击之后且批量上传开始之前才会触发（同步和异步上传）。附加参数有：

data：这是一个数据对象（关联数组），它发送以下信息，其关键字是：
- form：FormData，通过XHR2传递的对象（如果不可用，则为空对象）。
- files: 数组，文件栈数组（如果不可用，则为空对象）。
- filenames：数组，堆栈数组中每个文件的客户端文件名（如果不可用，则为空对象）。
- filescount: int，所选文件的计数包括已经上传的文件（基本上返回getFilesCount方法的输出）。
- extra：该插件的uploadExtraData设置（如果不可用，则为空对象）。
- response：通过ajax响应发送的数据（如果不可用，则为空对象）。
- reader：FileReader实例，如果可用。
- jqXHR：用于此事务的jQuery XMLHttpRequest对象（如果可用）。

$('#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

此事件仅在ajax上传且文件批量上传成功之后触发。此事件只有是AJAX上传并在以下场景才会触发：

当你将uploadAsync设置为false并且已经触发了批量上传时。在这种情况下，在所以文件成功上传后会触发filebatchuploadsuccess事件。

附加参数有：

data：这是一个数据对象（关联数组），它发送以下信息，其关键字是：
- form：FormData，通过XHR2传递的对象（如果不可用，则为空对象）。
- files：数组，文件栈数组（如果不可用，则为空对象）。
- filenames：数组，堆栈数组中每个文件的客户端文件名（如果不可用，则为空对象）。
- filescount：int，所选文件的计数包括已经上传的文件（基本上返回getFilesCount方法的输出）。
- extra：该插件的uploadExtraData设置（如果不可用，则为空对象）。
- response：通过ajax响应发送的数据（如果不可用，则为空对象）。
- reader：FileReader实例，如果可用。
- jqXHR：用于此事务的jQuery XMLHttpRequest对象（如果可用）。

$('#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

此事件仅对于ajax上传且完成同步或异步ajax批量上传后触发。附加参数有：

files：数组，文件栈数组（如果不可用，则为空对象）。
extra：该插件的uploadExtraData设置（如果不可用，则为空对象）。

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

filesuccessremove

使用缩略图删除按钮删除成功上传的缩略图后，会触发此事件。当showUploadedThumbs设置为true时，这通常是适用的。附加参数有：

id：缩略图HTML容器节点的id属性。

$('#input-id').on('filesuccessremove', function(event, id) {
    if (some_processing_function(id)) {
       console.log('Uploaded thumbnail successfully removed');
    } else {
        return false; // 缩略图删除中断
    }
});

filedisabled

当使用disable方法禁用文件输入小部件（防止任何修改）时触发此事件。

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

fileenabled

当使用·enable·方法启用文件输入小部件（允许修改）时触发此事件。

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

filesorted

当通过初始预览中的拖放来对文件进行排序/重新排列时，会触发此事件。以下参数将作为JSON对象关键字另外发送：

previewId：预览缩略图HTML容器节点的id属性。
oldIndex：initialPreview中缩略图得旧索引
newIndex：initialPreview中缩略图得新索引
stack：排序后修改的initialPreviewConfig

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

filezoomshow

单击缩放按钮（在模态对话框中显示内容详细预览）时触发此事件。以下参数将作为JSON对象关键字另外发送：

sourceEvent：事件，模态对话框源事件show.bs.modal。
previewId：字符串，预览缩略图HTML容器节点的id属性。
modal：jQuery对象，模态框对象

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

filezoomshown

在模态框已被用户看到之后触发此事件（将等待CSS转换完成）。以下参数将作为JSON对象关键字另外发送：

sourceEvent：事件，模态对话框源事件show.bs.modal。
previewId：字符串，预览缩略图HTML容器节点的id属性。
modal：jQuery对象，模态框对象

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

filezoomhide

通过关闭对话框按钮隐藏模态框后触发此事件。以下参数将作为JSON对象关键字另外发送：

sourceEvent：事件，模态对话框源事件show.bs.modal。
previewId：字符串，预览缩略图HTML容器节点的id属性。
modal：jQuery对象，模态框对象

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

filezoomhidden

在模态从用户眼中隐藏完成之后触发此事件（将等待CSS转换完成）。以下参数将作为JSON对象关键字另外发送：

sourceEvent：事件，模态对话框源事件show.bs.modal。
previewId：字符串，预览缩略图HTML容器节点的id属性。
modal：jQuery对象，模态框对象

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

filezoomloaded

在使用remote选项加载模态框内容之后触发此事件。以下参数将作为JSON对象关键字另外发送：

sourceEvent：事件，模态对话框源事件show.bs.modal。
previewId：字符串，预览缩略图HTML容器节点的id属性。
modal：jQuery对象，模态框对象

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

filezoomprev

在缩放预览模式下触发此事件，当单击查看上一个导航按钮时（也是在缩放模式下按下键盘左箭头时触发）。

previewId：字符串，预览缩略图HTML容器节点的id属性。
modal：jQuery对象，模态框对象

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

filezoomnext

在缩放预览模式下触发此事件，当查看下一个导航按钮被点击时（当在缩放模式下按下键盘右箭头时也会触发此事件）。

previewId：字符串，预览缩略图HTML容器节点的id属性。
modal：jQuery对象，模态框对象

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

异常事件

用于文件验证错误的事件。

fileerror

当上传文件客户端验证错误时，会触发此事件。它允许传入对象data作为参数。

data：包含下面关键字的对象/关联数组。
- id：预览缩略图标识符id（如果不可用，则为undefined）
- index：文件索引或者预览缩略图索引（如果不可用，则为undefined）
- file：文件对象（如果不可用，则为undefined）
- reader：文件读取器实例（如果不可用，则为undefined）
- files：文件堆数组（如果不可用，则为undefined）
msg：字符串，生成的错误信息

范例：

$('#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);
   // 获取信息
   alert(msg);
});

fileimageresizeerror

当调整图像大小遇到错误或异常时，会触发此事件（请参见resizeImage属性）。附加参数有：

data：包含下面关键字的对象/关联数组。
- id：预览缩略图标识符id（如果不可用，则为undefined）
- index：文件索引或者预览缩略图索引（如果不可用，则为undefined）
msg：字符串，生成的错误信息

范例：

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

fileuploaderror

此事件仅在ajax上传时触发，并且主要针对ajax上传时遇到上载或文件输入验证错误。此事件仅针对ajax上传并在以下情况下触发：

当每个预览缩略图中的上传图标被点击并且文件面临上传中的验证错误时，或者
当你将uploadAsync设置为true并且已触发批量上传时。在这种情况下，在任何所选文件面临上传验证错误后，会触发fileuploaderror事件。

此事件可用的附加参数有：

data：这是一个数据对象（关联数组），它发送以下信息，其关键字是：
- id：预览缩略图的标识符（如果不可用，则为空对象）。
- index：文件索引或者预览缩略图索引（如果不可用，则为空对象）。
- form：FormData，通过XHR2传递的对象（如果不可用，则为空对象）。
- files：数组，文件栈数组（如果不可用，则为空对象）。
- filenames：数组，堆栈数组中每个文件的客户端文件名（如果不可用，则为空对象）。
- filescount：int，所选文件的计数包括已经上传的文件（基本上返回getFilesCount方法的输出）。
- extra：该插件的uploadExtraData设置（如果不可用，则为空对象）。
- response：通过ajax响应发送的数据（如果不可用，则为空对象）。
- reader：FileReader实例，如果可用。
- jqXHR：用于此事务的jQuery XMLHttpRequest对象（如果可用）。
msg：字符串，生成的错误信息。

$('#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');
   // 获取信息
   alert(msg);
});

filebatchuploaderror

此事件仅在ajax上传时触发，并且同步批量上传面临上传验证错误之后。此事件仅针对ajax上传并在以下情况下触发：

当您将uploadAsync设置为false并且已触发批量上传时。在这种情况下，在任何文件面临上载错误或者你通过服务器操作JSON响应返回错误后触发filebatchuploaderror事件。