Skip to content

Home

Jump to bottom Edit New page
Kai edited this page Apr 24, 2017 · 15 revisions

特性

注意

这个插件的最新版本是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属性。该插件将使用本地文件输入来存储文件，并且可以在正常的from提交后读取文件（您必须在form中包含类型为file的input标签）。这对于单个文件上传或简单的场景多个文件上传是有用的。配置非常简单，你可以从本机表单提交中读取POSTED的所有数据。但是，请注意，本地文件输入是只读的，不能被外部代码修改或更新。特别是对于多个文件输入选择，无法将单个文件增加到已选择的文件列表。如果尝试在已选择的文件输入按钮上再选择文件，它将覆盖并清除之前选择的文件。同样，在此模式下，无法选择移去/删除上传之前添加的文件。
  2. Ajax提交：在此模式下，你必须将uploadUrl属性设置为有效的ajax处理服务器action/URL。如果uploadUrl设置了，那么该插件会自动为该场景使用ajax上传。该插件提供了ajax提交的高级功能，这是表单提交提供不了的。如拖放文件，在预览区域中添加/删除文件，获取上传的进度条等功能只有在此模式下才可以实现。您的浏览器必须支持HTML5 FormData/XHR2才能正常工作，并且处理ajax调用的服务器代码必须返回有效的JSON响应。

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

模式比较

模式比较
功能/要求 表格提交 Ajax提交
支持单个和多个文件上传 支持 支持
使用HTML 5 FileAPI预览文件 支持 支持
通过表单提交直接读取文件 支持 不支持
每个预览缩略图的单个文件删除图标 支持 1 支持2
每个预览缩略图的个人文件上传图标 不支持 支持
需要从服务器返回有效的JSON响应 不支持 支持
需要浏览器支持HTML5 FormData / XHR2 不支持 支持
服务器代码来处理ajax并发送JSON Response 不支持 支持
使用放置区拖放文件 不支持 支持
能够将文件附加到已选择的列表 不支持 支持
能够将文件删除到已选择的列表 支持 1 支持
上传进度栏 不支持 支持
阅读其他表单数据 直接通过表单提交
通过 uploadExtraData
  • 1 -通过initialPreviewConfig（仅适用于服务器上传的文件）。
  • 2 - 在运行环境中对服务器上传的文件（通过initialPreviewConfig）和客户端选择的文件。

用法

** 注意 ** 如果你将一个css class='file'属性赋予input标签，插件将自动把字段[input type="file"]转换为文件输入控件。但是，如果你想通过javascript单独初始化插件，那么请勿将css class='file'属性附加到'input'上（因为这将导致重复的初始化，并且JavaScript代码可能会被跳过不执行）。 步骤1：在网页头部加入链接。

<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet">
<link href="path/to/css/fileinput.min.css" media="all" rel="stylesheet" type="text/css" />
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<!-- 如果你想在上传之前修改图片大小需要加入canvas-to-blob.min.js  它必须在fileinput.min.js之前引入 -->
<script src="path/to/js/plugins/canvas-to-blob.min.js" type="text/javascript"></script>
<!-- 如果你想在最初的预览中排序/重新排列需要引入sortable.min.js  它必须在fileinput.min.js之前引入 -->
<script src="path/to/js/plugins/sortable.min.js" type="text/javascript"></script>
<!-- 如果你想在HTML文件预览中净化HTML内容则要引入purify.min.js is   它必须在fileinput.min.js之前引入 -->
<script src="path/to/js/plugins/purify.min.js" type="text/javascript"></script>
<!-- 主要的 fileinput 插件库 -->
<script src="path/to/js/fileinput.min.js"></script>
<!-- 如果你想在放大的模态页面中查看文件详细信息需要引入bootstrap.js -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js" type="text/javascript"></script>
<!-- 可选，如果你需要像font awesome 这样的主题，就像下面的代码一样引入它 -->
<script src="path/to/js/fa.js"></script>
<!-- 可选，如果你需要转换语言或翻译，就包含这个库 -->
<script src="path/to/js/<lang>.js"></script>

你可能注意到了，除了fileinput.min.css和fileinput.min.js外，你必须要加载jquery.min.js和bootstrap.min.css。可选择加入fa.js主题文件来使用 font awesome 图标样式。可选择加入 语言.js，可以把插件翻译成你的语言。

Add a custom footer
Add a custom sidebar
Clone this wiki locally