Home

特性

注意

这个插件的最新版本是v4.4.0（开发中）。 有关详细信息，请参阅更改日志。

文件输入特性

1. 该插件将一个简单的HTML文件输入转换为高级文件选择器的控件。在不支持JQuery或Javascript的浏览器中将帮助回退到普通HTML文件输入。
2. 文件输入由以下三个部分组成，每个部分都包含用于控制显示的选项和模板：
   • 文件标题部分：显示所选文件的简要信息。
   • 文件操作按钮部分：浏览，删除和上传文件。
   • 文件预览部分：在客户端上显示所选文件进行预览（支持预览图像，文本，Flash和视频文件类型）。其他文件类型将显示为默认的缩略图。
3. 如果设置<input>标签的class属性为file，该插件将自动将它转换为type属性为file的高级文件输入选择器。高级文件输入选择器的所有参数都可以通过HTML5的data-*属性传递。
4. 能够选择和预览多个文件。使用HTML5文件阅读器API来读取和预览文件。在选择多个文件的情况下显示正在加载到预览区域的每个文件的进度。
5. 提供预定义的模板和CSS类，可以根据您的需要更改您的文件输入显示风格。
6. 能够配置插件初始化具有初始标题的images/files类型文件预览 （对于记录更新场景很有用）。请参考插件参数部分的initialPreview、initialPreviewConfig和initialCaption属性来配置它。
7. 能够将简要预览内容缩放为详细预览。在预览中查看缩放内容的幻灯片，最大限度地实现无边界或全屏预览。
8. 能够通过拖放操作在初始预览中对内容进行排序/重排。
9. 能够完全主题化控件，并控制样式和布局。
10. 通过语言/翻译支持同一页面上的多语言控件。
11. 显示/隐藏任何或所有以下内容的选项：
    • 标题部分
    • 预览部分
    • 上传按钮
    • 移除按钮
12. 自定义显示整个插件，标题容器，标题文本，预览容器，预览图像和预览状态的目标容器元素的位置。
13. 对于文本文件预览，将文本自动缩隐为缩略图宽度，并显示一个缩略指示器链接，以便在悬停时显示完整的文本。您可以自定义缩略符（默认为...）。
14. 自定义预览，进度和所选文件的消息。
15. 上传操作默认为表单提交。支持用于自定义基于ajax的上传的route/server上传动作参数。U
16. 触发JQuery事件进行高级开发。目前可用的事件有filereset、fileclear、filecleared、fileloaded，和fileerror。
17. 支持输入禁用文件和只读文件。
18. 动态自动调整文件名长度超过容器宽度的文件标题。
19. 当预览容器上完全载入图像后，触发的新的fileimageuploaded事件。
20. 当预览图超过预览容器的大小时自动调整预览图像。
21. 完全模板化和可扩展，允许开发人员以自己想要的方式配置文件输入。
22. 基于各种文件预览类型智能化预览。内置的文件支持类型分类为image、text、html、video、audio、flash、object和other。
23. allowedPreviewTypes:你可以配置哪些文件类型被允许预览显示。默认值为['image', 'html', 'text', 'video', 'audio', 'flash', 'object']。因此，默认情况下，所有文件类型都将被视为要预览的对象。 举个例子，如果只想展示图像和视频的预览，就将这个参数设置为['image', 'video']。如果要禁用所有文件类型的内容预览，并用预览图标代替缩略图，请将其设置为null、empty或false。
24. allowedPreviewMimeTypes:除了参数allowedPreviewTypes，你还可以控制哪些互联网媒体类型可以预览。它的默认值为null，表示支持所有互联网媒体类型。请注意： 使用版本2.5.0，你可以通过设置allowedFileTypes和allowedFileExtensions参数来控制允许上传的文件类型或扩展功能。
25. layoutTemplates:允许你通过一个属性来配置所有布局模板设置。可配置的布局对象有：main1、main2、preview、caption和 modal。
26. previewTemplates:所有用于每个预览类型的预览模板已被组合成一个属性，而不是单独用于图像，文本等内容的模板。表示格式的键为allowedPreviewTypes，值表示预览模板。下面是每个预览文件类型（generic、image、text、html、video、audio、flash, object和other）。generic模板仅用于使用直接的标签来展示initialPreview内容。
27. previewSettings:允许你为每个预览图像类型配置宽度和高度。该插件对每个类型都具有默认的宽度和高度预定义，这些类型有image、text、 html、video、audio、flash和 object。
28. fileTypeSettings:允许你使用回调函数配置和识别每个预览文件类型。该插件有默认的回调函数预定义来识别不同类型，这些类型有image、text、 html、video、audio、flash和 object。
29. 使用模板替换标签已被增强。使用此版本，它将自动检查每个多次出现的标签替换的为模板字符串。
30. 操作事件，并轻松地在任何中止上传的事件返回的输出中添加您自己的自定义验证消息。
31. 支持翻译和语言环境。

注意

Flash预览需要安装Shockwave flash并且客户端浏览器支持它。Flash预览目前只能与webkit浏览器成功运作。支持HTML5 video/audio标签的所有现代浏览器都支持视频和音频格式预览。请注意，浏览器的HTML5视频元素支持的视频/音频格式数量有限（例如mp4，webm，ogg，mp3，wav）。视频文件推荐使用小视频（通过maxFileSize 属性进行控制），这样不会不影响预览效果。你可以从插件库的examples目录下复制几个文件，来测试一些Flash和视频文件的示例。

文件上传特性

伴随着版本4.0.0，插件现在也包括内置AJAX上传支持和有选择地添加或删除文件。AJAX上传功能基于HTML5 FormData和XMLHttpRequest Level 2标准。大多数现代浏览器都支持此标准，但插件在不支持的浏览器中将自动降级为正常格式提交。

1. 添加AJAX功能，基于HTML5 FormData大多数现代浏览器支持）上传方式。如果不支持，将降级到正常的基于表单的文件提交。
2. 要使用AJAX上传，必须设置uploadUrl属性。
3. 增强插件，现在允许添加，附加，删除文件（基于许多的反馈）。因此，可以附加文件到预览。
4. 可以通过DRAG & DROP区域来拖放和附加文件。New DRAG & DROP zone available in preview to drag and drop files and append.
5. 逐个或批量删除、上传文件。
6. 如果showPreview设置为false，或者未设置uploadUrl，插件将降级到基于正常的form形式上传。
7. 可配置指示灯来同步文件等待上传，文件成功上传，文件上传错误状态。
8. 能够添加额外的表单数据到基于ajax的上传中。
9. 上传进度条和单个缩略图的上传标识。
10. 能够取消和中止正在进行的AJAX上传。
11. 建立初始预览内容（例如保存的图像库）。您可以设置初始预览操作（预定义支持预先预览删除）。也可以设置其他自定义操作按钮初始化预览缩略图。
12. 确保插件仍然尺寸精简，并最佳地利用HTML5和jquery功能优化上述功能的性能。
13. 一旦ajax上传完成，就自动从服务器上刷新预览内容。

安装

可以使用以下方法之一自动或手动安装该插件：

Bower包管理器

通过bower包管理器进行安装，运行下面简单的指令：

$ bower install bootstrap-fileinput

Composer包管理器

通过Composer包管理器进行安装，运行指令：

$ php composer.phar require kartik-v/bootstrap-fileinput "dev-master"

或者添加：

"kartik-v/bootstrap-fileinput": "dev-master"

到你的composer.json文件中。

手动安装

您也可以手动将插件简单安装到你的项目中。只需要下载源码ZIP压缩文件或者TAR文件，并把文件（css和js文件夹）解压到你的工程中就可以。

先决条件

1. Bootstrap 3.X。但是，可以使用模板为任何CSS框架定制插件。
2. 最新的JQuery
3. 大多数支持HTML5文件输入和FileReader API的现代浏览器，包括CSS3和JQuery。
4. 为了使文件预览工作，浏览器必须支持HTML5 FileReaderAPI，否则插件会自动降级到正常的文件输入。对于Internet Explorer，必须使用IE 10及更高版本。IE9及以下版本将作为普通文件输入，并且不支持多个文件选择和HTML5 FileReader API。
5. 版本4.0支持AJAX上传。AJAX上传要求浏览器支持HTML5 FormData和XHR2（XMLHttpRequest 2）。大多数现代浏览器支持FormData和XHR2。该插件在不支持AJAX上传的浏览器中将自动降级到正常表单提交。

浏览器支持

该插件使用HTML5功能来实现各种功能。大多数现代浏览器支持这些功能。但是，要知道你的浏览器是否支持这些功能，你必须在下面运行这些检查。

功能	描述	支持
文件输入多个	允许用户使用本机HTML文件输入选择多个文件。	浏览器
HTML 5文件API	允许使用插件在预览窗格上阅读和预览文件	浏览器
HTML 5 XHR2＆FormData	允许使用ajax上传功能来附加/删除文件并使用进度条进行跟踪。	浏览器
HTML5拖放	能够将文件拖放到一个Dropzone（仅适用于使用HTML5 XHR2的ajax上传）。	浏览器
HTML5画布	用于通过JavaScript管理图像文件。如果您希望在上传之前调整图像文件的大小，则必需。	浏览器

使用模式

大多数情况下，该插件可以配置为以下两种不同的模式之一进行上传。重要信息：不要尝试组合下列模式来接收文件数据，因为您将收到不一致和/或错误的输出。

1. 表单提交：在此模式下，您不设置uploadUrl属性。该插件将使用本地文件输入来存储文件，并且可以在正常的FORM提交后读取（您必须在FORM中包含输入）。这对于单个文件上传或多个文件上传的更简单的场景是有用的。配置非常简单，您可以从本机表单提交中读取POSTED的所有数据。但是，请注意，本地文件输入是只读的，不能被外部代码修改或更新。特别是对于多个文件输入选择，ONE无法将文件附加到已选择的文件列表。如果尝试在已选择的文件输入上选择文件，它将覆盖并清除以前的选择。同样，在此模式下，无法选择删除/删除上传之前添加的文件。

2. Ajax提交：在此模式下，您必须将uploadUrl属性设置为VALID ajax处理服务器操作/ URL。如果uploadUrl设置了，那么该插件会自动为该场景假定ajax上传。该插件为表单提交中提供的ajax提交提供了高级功能。功能如拖放文件，在预览区域中添加/删除文件，获取上传的进度条只有在此模式下才可以。您的浏览器必须支持HTML5 FormData / XHR2才能正常工作，并且处理ajax调用的服务器代码必须返回有效的JSON响应。

注意 作为高级场景，插件允许您处理ajax上传，即使没有选择文件，但是uploadExtraData使用ajax响应发送有效。这些事件filebatchpreupload， filebatchuploadsuccess，filebatchuploadcomplete，或 filebatchuploaderror将在这种情况下触发。它不会为所选文件提供任何数据，但将允许发送额外的数据。