引言:
一个强化的HTML5 文件输入插件,适用于Bootstrap 3.x。本插件对多种类型的文件提供文件预览,并且提供了多选等功能。本插件还提供给你一个简单的方式去安装一个先进的文件选择/上传控制版本去配合Bootstrap CSS3样式。通过对很多种文件提供预览支持,比如图片,文本,html,视频,声音,flash和对象,它大大增强了文件输入的功能。另外,它还包含基于AJAX的上传,拖拽,移除文件的功能,可视化的上传进度条,和可选择的添加或删除文件预览功能。
提示:本插件致力于使用大量在添加jquery下的css3和html5功能,强调:你可能会发现css3或html5或它两个的混合在许多实现中被需要。
本插件最早受一篇博文和Jasny'sFile Input plugin启发。但是本插件现在已经添加的好多功能和强化,为开发者提供了一个成熟并且完整的文件管理工具和解决方案。
伴随着4.0.0版本的发布,本插件现在支持被多种现代化浏览器支持的,基于Ajax,利用html5 Formdata和XHR2协议的上传。而且她也拥有了对在服务器端基于AJAX的文件删除原生内置支持。因此它可以添加更加强大的功能,联机添加、移除文件。本插件也对大多数现代浏览器添加了拖拉,移除支持。它也已经为Ajax上传提供原生支持。万一,浏览器不支持FormData或XHR2,本插件会降级成一个普通表单。
提示:本插件的最新版本:v4.2.7已经放出
文件输入功能:
1. 本插件将会把一个简单的HTML file input转换称一个先进的文件选取控制器。对于没有jquery和javascript支持的浏览器会退回一个普通的HTML file input。
2. File input由一下三个部分以及选项和范例组成,来控制显示
文件标题部分:来显示一个简短的被选文件的信息
文件活动按钮部分:用于浏览,移除,上传文件
文件预览部分:用来在客户端显示这个被选择的文件(支持图片,文本,flash和视频类文件)。其他类型的文件会被按照普通缩略图显示。
3. 本插件自动的转换一个具有 type = file的input成为一个先进的文件选择器 input如果你设置class = file。所有的input选项会被以html5 data 属性传递。
4. 能顾选择和预览多重文件,利用html5 file reader api来读取并且预览文件。万一许多文件被选择
,将会显示文件加载进度在预览区域。
5. 提供定义好的模板和css样式,并且可以按照你的需求来改变;
6. 1.5.0以上版本你可以配置本插件来显示一个图片、文件的初始化预览,并且伴随着初始标题(对记录上传情景更加有用).参考initialPreview和initialCaption属性选项部分来配置本功能;
7. 可以选择显示或隐藏底下的任意一个功能:
标题部分
预览部分
上传按钮
移除按钮
8. 定制目标容器元素的地点来展示整个插件,标题容器,标题文本,预览容器,预览图片,和预览地位。
9. 对于文本预览,自动收缩文本到预览图的宽度,并且展示一个收缩的指示器链接来悬浮展示完整的文本,你可以定制这个收缩指示器。
10. 定制被选择的预览,进度和备选文件的提示信息
11. 上传动作默认是一个表单提交,支持基于自定义Ajax上传上传到远程服务器动作参数。
12. 为更进步的开发提供Jquery事件触发器。现在已经支持Filereset,fileclear,filecleared, fileloaded, and fileerror.事件
13. 支持Disabled和只读文件
14. 超出容器的长文件名可以动态的自动改变文件标题大小。
15. 在图像完整的加载到预览区域之后,建立了新的fileimageuploaded事件
16. 当图片大小查处了预览区域的面积时自动改变预览图像的大小。
17. 为满足开发者的需求配置file-input提供完整的模板和扩展性。
18. 智能预览支持多种文件类型,内置的文件支持种类是:图像,文本,html,视频,音频,flash,对象,压缩文件和其他。
19. allowedPreviewTypes:你能够配置所有的被预览文件类型,默认是['image', 'html', 'text', 'video', 'audio', 'flash','object']。因此所有的文件类型默认被以object来预览。比如如果只预览image
和video
,你把这个属性赋值:
['image', 'video']
.。如果你想对所有文件类型去掉预览功能并且展示previewIcon而不是一个缩略图,设置这个属性为null,空,或者false。
20. allowedPreviewMimeTypes:在添加了allowedPreviewTypes属性后,你也能控制被预览的所有mime类型。这个属性默认是null,意味着支持所有的mime类型。提示:在2.5.0版本释放时候,你能通过设置allowedFileTypes
和 allowedFileExtensions
控制被允许上传的文件类型。
21. layoutTemplates:可你让你用一个属性配置所有的布局模板设置。能够被配置的布局对象为:main1
, main2
, preview
, caption
,和modal
.
22. previewTemplates:对于每个预览类型,所有的预览模板 (generic
, image
, text
, html
, video
, audio
,flash
, object
, and other
).已经被融合进一个属性,而不是分开的,比如为图像或者文本单独一个模板。对所有预览文件类型有默认的建立好的模板,利用直接的标记,一般的模板被仅用来展示initialPreview属性中规定内容。
23. previewSettings:允许你对每个预览图片配置宽度和高度,本插件有默认的宽度和高度,已经被提前定义好,比如图像,文本,html。。。
24. fileTypeSettings:能够让你利用一个回调函数配置并且识别每个预览的文件类型,本插件有默认的回调函数,已经被提前定义好去识别每种类型,比如图片,文本。。。
25. 增强了模板中的替代标签,利用本版本,它将会自动的对每个标签检查多重事件来替换一个模板字符串。
26. 在任意的事件中,操作事件并且轻松的添加你自己的习惯验证消息,利用返回值来终值上传。
27. 支持各种语言翻译和本地化操作。
提示:flash预览需要安装Shockwave flash插件并且被客户端浏览器支持。本flash预览目前这能被webkit浏览器成功的支持。视频或者音频格式被所有支持html5音视频标签的现代浏览器所支持。切记html5只能支持有限周磊的视频和音频标签,比如mp4, webm, ogg, mp3, wav,并且视频文件的大小推荐越小越好(可以通过maxFileSize属性来控制)确保大小不会影响到预览的性能,你可以从examples目录复制一些文件(在这个插件里),来测试一些falsh或视频文件的案例。
在4.0.0版本下,本插件也包含了内置的Ajax上传支持,还有可选的添加或删除文件功能。Ajax上传功能被建立在html5 formdata 和xmlhttprequest 2级之上。多数现代浏览器都支持这个标砖,但是万一浏览器不支持,本插件会自动的降级称普通表单。
1. 添加利用html5 formdata基于ajax上传功能,如果浏览器不支持会降级成普通表单文件提交。
2. 为了使用ajax上传,必须在js中设置uploadUrl属性。
3. 增强了插件可以让文件被添加,粘附,移除(基于FEEDBACK )。因此用户可以粘附文件到预览区域
4. 新的拖拽区域可以拖拉文件到预览区域并且被粘附上。
5. 删除或者上传文件一个一个的或者几个文件一起。
6. 如果showPreview属性被设置成false,或者uploadUrl不支持插件,会自动降级成普通表单格式。
7. 为等待上传中的文件设置了可配置的指示器,比如文件成功上传还有文件上传失败。
8. 基于ajax的上传可以添加额外的表单。
9. 上传进度条和每个文件独立的略缩图上传指示
10. 能共取消甚至终止正在进行的ajax上传。
11. 增进初始预览内容,你能够设置初始预览动作(为初始预览删除提供预建支持)。其他的自定动作按钮也能够被设置初始预览图
12. 尽管本插件上层功能最优的的利用了html5和jquery功能,但仍确保插件大小依靠并且最适性能。
13. 只要ajax上传结束,自动的根据来自服务器的内容尽快刷新预览内容。
本插件能被自动或者手动安装利用这些选项中的一个
经由Bower Package Manager安装非常容易
$ bower install bootstrap-fileinput
你可以安装bootstrap file-input 经由composer
package manager.或者执行
$ php composer.phar requirekartik-v/bootstrap-fileinput "dev-master"
或者添加
"kartik-v/bootstrap-fileinput":"dev-master"
到你的composer.json文件
你也能轻松的手动安装本插件到你的项目离去,仅仅下载这个源文件zip或者tar ball并且抽取插件内容(css和js目录)到你的项目中去。
正如在安装章节展示的那英,翻译现在已经在4.1.8版本之后启用。你能够加载一个本地文件/fileinput_locale_<lang>.js在核心文件fileinput.min.js之后。<lang>就是语言的代码,比如de,fr.如果本地化文件不存在,你可以为新语言提交一个翻译。
1.Bootstrap 3.x.但是,本插件能适用自定义的任何css框架,利用模板。
2.最新版本的jquery
3.最新版的浏览器,支持html5fileinput,还有filereader api 包含css3和jquery。
4.为了文件预览能正常工作,浏览器必须支持html5filereaderApi 否则本插件将会自动降级成一个普通file input。对ie浏览器,开发者必须适用ie10一张版本,ie9及以下版本将会降级成普通fileinput,而且也不会支持多文件选择或者html5 filereader API。
5. 4.0版本之后,ajax上传被支持,ajax上传需要浏览器支持html5formdata 和XHR2 (XMLHttpRequest 2),多数浏览器支持这两个。如果浏览器不支持,本插件会自动降级成普通表单并且不支持ajax上传。
很大程度上来说,本插件能够被配置在下列两个不同的模式来上传注意:不要试着联合下面的两种模式来收取文件,因为你会收到不连续或者错误的结果。
模式一表单提交:
在这种模式中,你不要设置uploadUrl属性。本插件会利用原生的 file input来储存文件并且它能够被独处在一个普通表单提交之后(你必须把这个input放在一个form里面)。这种模式对于单个文件上传非常有效,或者简单情景下的多文件上传。配置是直接的正如你能读出所有的被post从一个原生的表单提交的数据。但是,提示你这个原生file input是制度的并且不能被外部的代码修改或者更新。尤其是对于多文件input选择,一个新文件不能添加到一个已经存在的文件选择列表里面。如果你常识去选择文件从一个已经选好的file input,它将会被重写并且清除之前的选项,简单的来说,在此模式下,在上传之前你不能有选择的移除或者删除已经被添加文件。
模式二 ajax提交:在这个模式下,你必须用一个有效的ajax处理服务器url设置uploadUrl属性。如果uploadUrl被设置好了,然后本插件会自动认为这是个ajax上传情景。本插件为ajax提交提供了许多先进的功能,而且这些功能在表单提交下是没有用的。功能像拖拽文件,在预览区域添加、移除文件,而且进度条功能只能在本模式下使用。
你的浏览器必须支持HTML5FormData/XHR2,而且你的服务器代码处理ajax请求必须返回一个有效的json回复。
提示,在一个先进的模式下,本插件允许你处理ajax上传即使没有文件被选择,但是一个有效的uploadExtraData会被发送伴随着ajax响应。这些事件filebatchpreupload
, filebatchuploadsuccess
, filebatchuploadcomplete
,或filebatchuploaderror
在这种条件下会被触发。它将不会有任何数据从被选择文件里发出,但是会允许额外的数据被发送。
如果你添加一个cssclass文件在这个input上,本插件会自动的转换[inputtype="file"]成一个fileinput control,但是如果你独立的初始化这个插件经由js,然后不要再添加css样式在这个input上(正如它将会调职重复的初始化并且这个js代码可能会被跳过)
1. 第一步:加载下面这些设置到header里去
2. <linkhref="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css"rel="stylesheet">
3. <linkhref="path/to/css/fileinput.min.css"media="all"rel="stylesheet"type="text/css"/>
4. <scriptsrc="//ajax.googleapis.com/ajax/libs/jquery/2.0.0/jquery.min.js"></script>
5. <!--canvas-to-blob.min.js is only needed if you wish to resize images beforeupload.
6. This must be loaded beforefileinput.min.js -->
7. <scriptsrc="path/to/js/plugins/canvas-to-blob.min.js"type="text/javascript"></script>
8. <scriptsrc="path/to/js/fileinput.min.js"type="text/javascript"></script>
9. <!--bootstrap.js below is only needed if you wish to use the feature of viewingdetails
10. of text file preview via modal dialog-->
11. <scriptsrc="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"type="text/javascript"></script>
12. <!--optionally if you need translation for your language then include
13. locale file as mentioned below -->
14. <scriptsrc="path/to/js/fileinput_locale_<lang>.js"></script>
如果你注意到了,你需要额外的加载jquery.min.js和bootstrap.min.css,为了fileinput.min.css和fileinput.min.js。本地文件fileinput_locale_<lang>.js可以有选择的添加如果你需要翻译成你的语言的话。
提示:canvas-to-blob.min.js文件是JavaScript-Canvas-to-Blob plugin by blueimp的源文件,它需要在fileinput.min.js之前被加载,如果你需要使用本插件的图像重新设置大小功能,为了轻松的接入,JavaScript-Canvas-to-Blob这个插件源码已经被包含在这个项目的js/plugins文件夹里。
第二步 a:在你的页面上初始化这个插件,如下
1. // initializewith defaults默认初始化
2.
3. $("#input-id").fileinput();
4.
5. // with pluginoptions带插件选项的初始化
6. $("#input-id").fileinput({'showUpload':false,'previewFileType':'any'});
#input-id是你页面上的input的id属性,比如(type=file,这个会被本插件自动的隐藏)。
第二步 b:可选择的,你能够直接的给任何一个input设置插件的选项,通过html5 data属性在你的input标签里
1. <inputid="input-id"type="file"class="file"data-preview-file-type="text">
你需要设置服务器方法来解析并且返回正确的响应经由ajax,你能设置同步上传或者异步上传模式正如下面所描述的。
异步上传:
这是默认的模式,通过把uploadAsync属性设置为true。当上传多个文件的时候,这个异步模式允许对每个文件触发平行的服务器请求。你能够控制文件上传数量的最大数在同事上传通过设定maxFileCount属性,在异步模式下,在预览框里的每个略缩图的进度条是有效的而且更新的。
收到数据(服务器端)
你的服务器方法应该如uploadUrl里设置的一样
从本插件收到下面的数据
1、 文件数据:这个被发向服务器的数据在一个非常普通的表单file input格式,比如在php中,你可以读取这个数据如:$_FILES['input-name'],input-name是你input标签的name属性。如果你不给你的input标签设置一个name属性,那么它默认是file_data。提示:多个文件上传时需要你设置input标签的multiple属性为true,这样在php里你可以接受文件数据如$_FILES['file_data']。
2、 额外数据:本插件能够想你的服务器发送额外的数据。这个能够通过设置uploadExtraData来完成。如一个键值对的关联数组对象一样。所以如果你有设置uploadExtraData={id:'kv-1'},在php中你可以读取这个数据如$_POST['id']。
提示:在异步模式下,你一定会在你的服务器经由ajax上传收到单个文件。基本的,本插件会为每个被选择上传的文件触发平行ajax请求,你需要根据
这个写你的服务器上传逻辑,这样才能读取并且上传一个文件。相似的,在下面的发送数据章节,你必须仅为单个文件接收返回一个initialPreview来反射数据
你的服务器地址应该如uploadUrl属性里设置的一样,而且必须发回一个json对象数据,在这个条件下,你能够发送这4条信息,标明在异步模式下,你将会受到一个文件记录来自服务器,所以根据这个调整你的代码
·error:字符串,这个是为整个一批上传的错误信息而且将会帮助本插件去确认上传中的错误。举例来说,这个来自服务器的响应该像这样发送{error: 'You are not allowed to upload such a file.'}。提示:这个插件会自动的生效并且显示ajax异常错误。