事件
该插件支持各种事件,并允许高级功能,如返回事件结果来验证和动态操作文件上传。该部分分为文件事件,异常事件和事件处理。
文件事件
可用于文件管理和文件操作的事件。
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
事件。
此事件可用的附加参数有:
data
:这是一个数据对象(关联数组),它发送以下信息,其关键字是:form
:FormData,通过XHR2传递的对象(如果不可用,则为空对象)。files
: 数组,文件栈数组(如果不可用,则为空对象)。filenames
:数组,堆栈数组中每个文件的客户端文件名(如果不可用,则为空对象)。filescount
:int,所选文件的计数包括已经上传的文件(基本上返回getFilesCount
方法的输出)。extra
:该插件的uploadExtraData
设置(如果不可用,则为空对象)。response
:通过ajax响应发送的数据(如果不可用,则为空对象)。reader
:FileReader
实例,如果可用。jqXHR
:用于此事务的jQuery XMLHttpRequest
对象(如果可用)。
msg
:字符串,生成的错误信息。$('#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'); // 获取信息 alert(msg); });
filedeleteerror
当在
initialPreview
内容集中删除每个缩略图文件出现错误时触发此事件。附加参数有:data
:这是一个数据对象(关联数组),它发送以下信息,其关键字是:id
:预览缩略图的标识符(如果不可用,则为空对象)。index
:文件索引或者预览缩略图索引(如果不可用,则为空对象)。extra
:该插件的uploadExtraData
设置(如果不可用,则为空对象)。response
:通过ajax响应发送的数据(如果不可用,则为空对象)。jqXHR
:用于此事务的jQuery XMLHttpRequest
对象(如果可用)。
msg
:字符串,生成的错误信息。$('#input-id').on('filedeleteerror', function(event, data, msg) { console.log('File delete error'); // get message alert(msg); });
filefoldererror
当文件夹或多个文件夹被拖放到文件预览放置区时,会触发此事件。附加参数有:
folders
:整数,拖拽的文件夹数量。msg
:字符串,生成的错误信息。$('#input-id').on('filefoldererror', function(event, folders, msg) { console.log('File folder dropped error'); // 获取信息 alert(msg); });
filecustomerror
通过从源事件返回错误异常对象,用户从其他事件之一手动触发此事件。参考事件操作部分了解详情。附加参数有:
data
:这是一个数据对象(关联数组),它发送以下信息,其关键字是:form
:FormData,通过XHR2传递的对象(如果不可用,则为空对象)。files
: 数组,文件栈数组(如果不可用,则为空对象)。filenames
:数组,堆栈数组中每个文件的客户端文件名(如果不可用,则为空对象)。filescount
:int,所选文件的计数包括已经上传的文件(基本上返回getFilesCount
方法的输出)。extra
:该插件的uploadExtraData
设置(如果不可用,则为空对象)。response
:通过ajax响应发送的数据(如果不可用,则为空对象)。reader
:FileReader
实例,如果可用。jqXHR
:用于此事务的jQuery XMLHttpRequest
对象(如果可用)。
msg
:字符串,生成的错误信息。$("#input").on('filecustomerror', function(event, params, msg) { console.log(params.id); console.log(params.index); console.log(params.data); // 获取信息 alert(msg); });
事件处理
从版本v4.1.8开始,你可以操作事件并通过其他事件添加自定义验证,通过返回大多数事件的数据并将其用于高级处理。除了以下事件之外,事件部分中列出的大多数事件都支持此功能。
fileclear
filecleared
filereset
fileerror
fileuploaderror
filebatchuploaderror
filedeleteerror
filefoldererror
filecustomerror
fileuploaded
filebatchuploadcomplete
filebatchuploadsuccess
对于除上述之外的所有事件,你可以设置自定义验证错误,这将在启动上传之前触发。
这将使你能够添加其他自定义验证来增强文件输入控件适用于更多场景。它允许使用任何fileinput
事件(除上述事件之外)返回关联对象,例如,change
、fileselect
、filepreupload
、filebatchpreupload
等等。
该对象可以返回以下关键字:
message
:字符串,在上传之前显示是的验证错误消息。如果设置了它,插件会在调用时自动中止上传,并将其显示为错误消息。你可以使用此属性来读取文件并执行自己的自定义验证。data
:对象,一个中止时可选的额外数据关联数组,你可以给它传值,稍后使用它。
范例:
- 步骤1: 你可以触发一个从
filepreupload
中止的异常。
上传中断将在AJAX上传或表单提交(非AJAX上传)时触发。$('#input').on('filepreupload', function(event, data, previewId, index, jqXHR) { // 进行自定义验证并返回如下所示的错误 if (customValidationFailed) { return { message: 'You are not allowed to do that', data: {key1: 'Key 1', detail1: 'Detail 1'} }; } });
步骤2:通过捕获
filecustomerror
中止事件来读取额外的数据。
$('#input').on('filecustomerror', function(event, params) { // `params.abortData`包含额外传出的数据 // `params.abortMessage`包含传出的错误中断信息 });
如前所述,在以下事件中不支持使用
filecustomerror
的上述功能:
fileclear
filecleared
filereset
fileerror
fileuploaderror
filebatchuploaderror
filedeleteerror
filecustomerror
fileuploaded
filebatchuploadcomplete
filebatchuploadsuccess