文件上传插件 -- fileinput

作者: Robot_Lee | 来源:发表于2019-08-13 18:10 被阅读0次

1.特性

该插件可以将简单的 <input type=file /> 转换为高级的文件选取控件。对于不支持 JQuery 和 Javascript 的浏览器，将会回滚到正常的 HTML <input type="file" />
fileinput 由以下三部分组成，其中包含用于控制显示的选项和模板
- 文件标题部分：显示所选文件的简要信息
- 文件操作按钮部分: 用以浏览、移除、上传文件
- 文件预览部分: 在客户端(浏览器)预览选择的文件（支持图片、文本、flash、视频文件的预览），其他文件类型会显示为正常文件的缩略图
当设置 <input type="file" /> 的 class="file" 后，插件将自动的将该 input 转换为高级的文件选择器，设置在该 input 身上的选项，将会被转换为 data 属性
能够选择和预览多个文件。使用 HTML5 file reader API读取和预览文件。如果选择了许多文件，则显示正在加载到预览区域的文件的进度。
提供预定义的模板和CSS类，可以根据需要更改这些模板和类，以设置 fileinput 显示的样式。
能够配置插件以显示带有初始标题的 图像/文件的初始预览（对于记录更新方案更有用）。请参阅插件选项部分中的InitialPreview、InitialPreviewConfig和InitialCaption属性以配置此项。
能够将内容缩放为详情预览。在预览中查看缩放内容的幻灯片，最大化为无边框或全屏预览。
能够通过拖放对初始预览中的内容进行排序/重新排列。
能够对插件设置主题，并控制样式和布局。
在同一页面支持多语言
显示、隐藏以下任意或全部的选项
- 标题区
- 预览区
- 上传按钮
- 移除按钮
自定义目标容器元素的位置，以显示整个插件、标题容器、标题文本、预览容器、预览图像和预览状态。
对于文本文件预览，将文本自动换行到缩略图宽度，并显示换行指示器链接以在悬停时显示完整文本。您可以自定义换行指示器（默认为…）。
可自定义预览、进度、选择的文件的信息
在表单提交的时候，自动触发文件上传。支持用于自定义基于 Ajax 的上传的上传路由/服务器操作参数。
触发 JQuery 事件以进行高级开发。当前可用的事件有 filereset、fileclear、filecleared、fileloaded 和 fileerror。
支持 readonly 和 disabled 的 input
文件名太长超过容器宽度时，动态设置标题栏的尺寸
在预览容器中完全加载图像后引发新的 fileimageuploaded 事件。
当预览图超过预览容器尺寸的时候，自动缩放预览图
完全模板化和可扩展，允许按照开发人员的需求配置 fileinput。
基于各种文件预览类型的智能预览。内置文件支持类型有图像、文本、HTML、视频、音频、Flash、对象和其他。
allowedPreviewTypes: 通过配置 allowedPreviewTypes 选项，来设置哪些文件类型可被预览，默认为 ['image', 'html', 'text', 'video', 'audio', 'flash', 'object'],因此，默认情况下，所有文件类型都被视为要预览的对象。例如，如果仅仅需要预览 image 和 video 文件，可做如下设置：{allowedPreviewTypes: ['image', 'video']}; , 禁止所有文件类型的预览，将预览区域设置为一个 icon 而不是一个缩略图，可设置 previewIcon 选项，如： {previewIcon: null}, 可将该选项设置为 null, '', false;
allowedPreviewMimeTypes: 除了 allowedPreviewTypes 外，还可以控制可以显示哪些 MIME 类型文件可进行预览。该值默认为 null, 即所有 MIME 类型文件均可预览. 注：使用2.5.0版，您现在可以通过设置 allowedFileTypes 和 allowedFileExtensions 来控制允许上传的文件类型或扩展名。
layoutTemplates: 允许您在一个属性中配置所有布局模板设置。可以配置的布局对象有：main1、main2、preview、caption 和 modal。
previewTemplates: 针对每个预览类型的所有预览模板都被合并进一个属性，键是在 allowedPreviewTypes 中设置的格式，值是用于预览的模板。每个预览文件类型（常规、图像、文本、HTML、视频、音频、Flash、对象和其他）都有默认的预构建模板。通用模板仅用于使用直接标记显示 initialPreview 内容。
previewSettings：允许您为每个预览图像类型配置宽度和高度。插件为每种预定义类型设有默认宽度和高度，即图像、文本、HTML、视频、音频、Flash和对象。
fileTypeSettings: 允许通过回调函数来配置和标识每个预览文件类型，该插件有默认的预定义回调函数来标识每种文件类型。即图像、文本、HTML、视频、音频、Flash和对象。
在模板中替换标签已经得到了增强。使用此版本，它将自动检查模板字符串中要替换的每个标记是否多次出现。
通过返回输出以中止任何其他事件中的上传，可以轻松地操作事件并添加自定义验证消息。

注意：
Flash预览需要安装Shockwave Flash并由客户端浏览器支持。Flash预览当前仅在WebKit浏览器中成功工作。然而，所有支持HTML5视频/音频标签的现代浏览器都支持视频和音频格式。请注意，HTML5视频元素（例如MP4、WebM、OGG、MP3、WAV）支持的视频/音频格式数量有限。建议视频文件的大小要小（通过maxfilesize属性控制），这样就不会影响预览性能。您可以从这个插件repo的examples目录复制一些文件，以测试一些flash和video文件的示例。

2. 文件上传特性

在4.0.0版本中，该插件包含对Ajax上传的内置支持，以及选择性地添加或删除文件。Ajax上传功能基于`HTML5 FormData` 和 `XMLHttpRequest 2` 标准构建。大多数现代浏览器都支持这个标准，但是对于不支持的浏览器，插件将自动降级为基于表单的正常提交。

使用 HTML5 的 FormData 添加基于 Ajax 的上传功能（大多数现代浏览器都支持）。如果不支持，将降级为基于表单的正常文件提交。
为了使用 Ajax 文件上传，必须设置 uploadUrl 属性
增强插件现在允许添加、追加、删除文件（基于许多人的反馈）。这样就可以追加文件进行预览。
新的 DRAG & DROP 区域可以通过拖拽来添加和追加文件
可逐个或批量删除、上传文件
若 showPreview 选项被设为 false, 或者不支持 uploadUrl, 插件将自动降级为基于表单的正常上传
可为待上传、成功上传、上传失败的文件配置指示器
能够为基于 Ajax 的上传添加额外的 form data;
上传进度条和独立的上传指示器缩略图
能够取消或退出正在进行的 Ajax 上传
建立初始预览内容（例如保存图像的库）。可以设置初始预览操作（默认预览图只有删除按钮，在预览图右下角）。还可以为初始预览缩略图设置其他自定义操作按钮。
一旦 Ajax 上传完成，自动用从服务器返回的内容刷新预览图

3. 使用模式

模式1: 表单提交

在此模式下，不设置uploadURL属性。该插件将使用原生的 file input 来存储文件，并且可以在正常表单提交后读取（必须将 input 包裹在表单中）。这对于单个文件上载或多个文件上载的更简单场景很有用。配置很简单，您可以从原生表单提交中读取所有 POST 的数据。但是，请注意，原生的 file input 是只读的，不能由外部代码修改或更新。尤其是对于多文件输入选择，不能将文件追加到已选择的文件列表中。如果试图在已选定的 file input上选择文件，它将覆盖并清除以前的选择。同样，在此模式下，上传之前不能选择性地移除/删除已添加的文件。

注意：
自v4.4.8版以来，基于表单的上传支持文件拖放。但是，对于基于表单的上传，它仅限于支持将 FileList 对象分配给 file input 的浏览器，如chrome和mozilla。

模式2：Ajax 提交

此模式下，必须设置 uploadUrl 给一个有效的 ajax 处理服务器。若设置了 uploadUrl, 那么插件将自动设置上传模式为 ajax 上传。该模式提供了一些 表单提交 模式不支持的高级特性。只有在此模式下，才能使用如在预览区追加、移除文件，获取上传进度条，调整图像大小的功能。浏览器必须支持 HTML5 FromData/XHR2 才能正常工作，并且处理Ajax调用的服务器代码必须返回有效的JSON响应。

模式对比

功能/需求	表单提交	ajax 提交
单文件和多文件上传	√	√
使用 HTML5 文件 API 预览文件	√	√
通过表单提交直接读取文件	√
每个预览缩略图有独立的文件删除图标	√¹	√²
每个预览缩略图有独立的文件上传图标		√
要求服务器端返回有效的JSON		√
要求浏览器支持 HTML FormData/XHR2		√
服务器端代码能处理 `ajax` 并返回 JSON		√
通过拖放区拖放文件	√³	√
能够为已选择的列表追加文件		√
能够为已选择的列表删除文件	√¹	√
支持上传进度条		√
支持上传状态		√
支持可恢复的 / 块上传		√
支持读取额外的 FormData 数据	直接通过表单提交	通过设置 `uploadExtraData` 属性
支持上传前设置图片尺寸		√

1 - 通过initialPreviewConfig(不适用未上传的客户端选定文件)
2 - 对于服务器上传的文件(通过 initialPreviewConfig ) 和客户端运行时已选择的文件
3 - 自4.4.8版本开始，支持基于表单的拖放，然而，基于表单的上传只支持像 Chrome 和 Mozilla 这样的支持分配文件列表对象 FileList 给原生的 file input 的浏览器

4 使用方法

注意：
如果给该 input 添加一个 file 的类名，插件将自动的转换 <input type="file" /> 为文件选择控制器。但是如果通过 javascript 来初始化插件, 就不要给该input添加 file这个 class（因为这会导致重复的初始化并跳过javascript代码）

使用：步骤1

在 <head></head>之间导入以下资源

<!-- 支持bootstrap 4.x . 也可以使用 bootstrap 3.3.x 版本的 css -->
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" crossorigin="anonymous">
<link href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/css/fileinput.min.css" media="all" rel="stylesheet" type="text/css" />


<!-- 如果文字排版为从右向左，在 fileinput 插件的css后导入 RTL CSS。可解注释以下代码 -->
<!-- link href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/css/fileinput-rtl.min.css" media="all" rel="stylesheet" type="text/css" /-->


<!-- 使用 `fas` 主题(或 Bootstrap 4.x)需导入 font awesome 图标库. 插件中默认使用的图标是仅在 Bootstrap 3.x. 中打包的 glyphicons  -->
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.5.0/css/all.css" crossorigin="anonymous">
<script src="https://code.jquery.com/jquery-3.3.1.min.js" crossorigin="anonymous"></script>


<!-- 当需要图片自动调整方向时，或恢复已调整大小的图像的exif数据时，或需要上传前重置图片尺寸，那么该 piexif.min.js 必须在  fileinput.min.js 之前导入 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/js/plugins/piexif.min.js" type="text/javascript"></script>


<!-- 仅当您希望在初始预览中对文件进行排序/重新排列时，才需要sortable.min.js。必须在fileinput.min.js之前加载 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/js/plugins/sortable.min.js" type="text/javascript"></script>


<!-- purify.min.js 用来净化在预览区的HTML文件 的 HTML 内容的. 必须在fileinput.min.js之前加载 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/js/plugins/purify.min.js" type="text/javascript"></script>


<!-- 如果使用bootstrap 4.x（用于poppover和工具提示），则需要下面的popper.min.js。. 您也可以使用  3.3.x 版本的 bootstrap js ，而不必引入 popper.min.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js"></script>


<!-- 如果想在模态框中缩放和预览文件内容，则要导入下面的 bootstrap.min.js . 支持bootstrap 4.x. 也可导入 3.3.x 版本的 bootstrap js . -->
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.bundle.min.js" crossorigin="anonymous"></script>


<!-- 导入插件的js文件 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/js/fileinput.min.js"></script>


<!-- 使用 Font Awesome 主题 (fas) 时，需要导入以下主题的js文件 -->
< script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/themes/fas/theme.min.js"></script -->


<!-- 如果需要设置插件语言，则可辅助性的导入以下路径的语言文件包，将 LANG.js替换为你想设置的语言 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap-fileinput/5.0.1/js/locales/LANG.js"></script>

如果你注意到，导入 fileinput.min.css 和 fileinput.min.js之外，还需要导入 jquery.min.js 和 bootstrap.min.css. 引入Font Awesome css 文件fas/theme.min.js以导入 Font Awesome主题(注意：默认Bootstrap 4.x 版本不包含 glyphicons 图标，所以你或许想同时使用font awesome Css 和 Font Awesome 主题)。你可以根据需要选择插件语言。当需要从右向左，则需要在fileinput.min.css之后导入fileinput-rtl.min.css

Bootstrap 4.x 的使用
注意，如果在使用该插件的时候，使用的是Bootstrap 4.0 和上面的插件，那么 glyphicons 不再随 Bootstrap 4.x打包。那么当使用 Bootstrap 4.x 时，图标选项如下:
- OPTION 1: 单独载入Glyphicons 的字体和css以保证插件的默认 icons 能被支持，因为插件默认使用的icons为Glyphicons
- OPITON 2: 使用作者提供的 Font Awesome 主题来配置插件并导入 Font Awesome 的 css 字体
- OPTION 3: 更改插件中使用的图标或创建自己的主题以呈现自己喜欢的图标。您可以查阅 krajee 提供的Font Awesome，设置您自己的图标主题。

可选的依赖插件

piexif.min.js 是 [Piexifjs plugin by hMatoba](https://github.com/hMatoba/piexifjs) 的源文件。当我们想让JPEG图片文件基于朝向标签自动调整方向时，它需要在 fileinput.min.js之前加载。当使用 fileinput 插件的图像尺寸调整特性来恢复 exif 数据给图像时，也需要载入此库
sortable.min.js文件是rubaxa可排序插件的源文件。如果希望在初始预览中对缩略图进行排序，则需要在fileinput.min.js之前加载它。
purify.min.js文件是cure53的dompurify插件的源文件。如果您希望为HTML内容预览净化HTML，则需要在fileinput.min.js之前加载它。

使用：步骤2a

在页面中初始化该插件。例如使用 javascript 进行初始化 - 下面的代码可以放在 document.ready 或者任意你想放置的地方

// initialize with defaults
$("#input-id").fileinput();
 
// with plugin options
$("#input-id").fileinput({'showUpload':false, 'previewFileType':'any'});

使用：步骤2b

或者，您可以直接通过input的HTML5 data 属性将插件选项设置给任何input。注意，对于这种情况，您需要给 input 设置一个 file 的类名。
如前所述，当通过javascript初始化插件时（步骤2a），不能给 input 设置名为 file 的类。

<input id="input-id" type="file" class="file" data-preview-file-type="text">

5 翻译（语言设置）

如上使用方法版块所述，翻译在4.1.8版本可用，遵照如下步骤来设置插件语言

从如下路径 /js/locales/<lang>.js. 载入语言脚本文件,该脚本必须在fileinput.js文件之后载入。<lang>意为语言代码<如 de, fr...>.如果你想要的语言文件不存在，你可以提交一个pull请求，来创建新的翻译文件。查看示例语言文件，为您自己的语言复制并创建翻译配置文件
配置插件的语言属性language为能被识别的语言代码

6 Ajax 方式上传

您需要设置服务器方法来解析并通过Ajax返回正确的响应。可遵照如下描述来配置异步或同步上传。

异步上传

这是默认模式.其中 uploadAsync 选项设置为 true.当上传多个文件时，异步模式允许为每个文件上传触发并行服务器调用。通过设置 maxFileCount 属性，可以控制一次允许上传的最多文件数。异步模式下，将验证并更新每个缩略图的进度

服务器端接收数据
在uploadURL 中设置的服务器方法从插件接收以下数据
- 文件数据: 此数据以非常类似于表单 file input 的格式发送到服务器,例如在PHP中，你可以通过 $_FILES['input-name']读取该数据，input-name 是 input 标签的 name 属性。如果你没有给 input 设置 name 属性，默认的 name 是 file_data. 注意，多文件上传需要设置 input 的 multiple 属性。那么在 PHP 中，你会通过 $_FILES['file_data'] 来读取文件数据
- 额外数据: 插件能发送额外数据给服务器的上传接口。可通过设置 uploadExtraData 属性为键值对形式的关联数组对象，因此，如果设置了 uploadExtraData=id:'kv-1',那么 PHP 中，可通过 $_post['id']来读取 id 值

注意
在异步模式下，您将始终在处理 Ajax 上传的服务器上接受一个单个文件。基本上，每个选中要上传的文件均会触发并行的 Ajax 调用，您需要相应的编写服务器上传逻辑，来始终读取和上传一个文件。同样，在下面的发送数据部分，必须返回仅反映接收到的单个文件的数据的初始预览

服务器端发送数据
服务端在 uploadUrl 接口中，必须返回一个json对象，如下

// example JSON response from server
{
    error: 'An error exception message if applicable',
    initialPreview: [
        // 如果希望在上传后立即显示服务器上传文件的初始预览缩略图，则需要初始化该属性
    ],
    initialPreviewConfig: [
        // 在初始预览中的每一项的配置
    ],
    initialPreviewThumbTags: [
        // 初始预览缩略图标记配置，渲染时将动态替换该配置
    ],
    append: true // 是否在初始预览中追加内容，也可将该属性设置为 `false` 来覆盖初始预览
}

如果服务器没有数据返回，至少应返回一个空对象 {}. 该对象由五部分组成。在异步模式下，你始终会接受到一个文件记录，因此请相应的调整代码。

error: 字符串类型。该属性是批量上传的报错信息，它有助于插件对上传错误的识别。例如，服务器端可能会发送{error: 'You are not allowed to upload such a file.'}.注意，插件将自动验证和展示 ajax 异常错误
initialPreview: 数组。指向上传文件的图片列表或任何 HTML 标记的列表。您将始终在此数组中发送发送一行-因为您将始终以异步上传的模式接收到一个文件。如果设置了该属性，插件会自动动态替换预览内容中的文件。它的配置和 InitialPreview 选项设置类似。如：

initialPreview: [
    '<img src='/images/desert.jpg' class='file-preview-image' alt='Desert' title='Desert'>'
]

initialPreviewConfig: 数组。用于标识 InitialPreview 项（作为 InitialPreview的一部分设置）中每个文件标记的属性的配置。您将始终在此数组中发送一行，因为在异步模式下上传时，您将始终收到一个文件。如果设置了此属性，则在上传成功后，插件将自动动态替换预览内容中的文件。此配置与InitialPreviewConfig选项设置类似。例如：

initialPreviewConfig: [
    {
        caption: 'desert.jpg', 
        width: '120px', 
        url: 'http://localhost/avatar/delete', // server delete action 
        key: 100, 
        extra: {id: 100}
    }
]

initialPreviewThumbTags: 数组。对应于在每个初始预览缩略图中替换标记的对象数组。通过InitialPreview设置的初始预览缩略图将读取此配置以替换标记。

// change thumbnail footer template
// set initial preview template tags
initialPreviewThumbTags:[
    {
        '{CUSTOM_TAG_NEW}': ' ',
        '{CUSTOM_TAG_INIT}': '<span class=\'custom-css\'>CUSTOM MARKUP</span>'
    }
]

append: 布尔值。
如果在初始化的时候已经设置了 initialPreview,是否将内容追加到 initialPreview.若不设置，默认为 true, 如果设置为 false.插件将覆盖 initialPreview 中的内容

$\color{#09f}{特别重要的}$

服务器必须返回一个 JSON，否则上传将会失败。即使你没有遇到任何错误，也应该从服务端返回一个空对象
要捕获并显示验证错误信息，返回的json数据中必须包含 error 属性。其值是要展示的HTML 标记。可以按照上面的提示设置
在服务器返回的JSON中，可以发送额外的 key 或数据，以便使用 fileuploaded 等事件处理高级情况下的键或者数据

同步上传

这种模式下，uploadAsync 被设置为 false.这会把数据以数据对象的形式触发一次从客户端到服务器的批量上传。即时在这种模式下，依然可以通过设置 maxFileCount 属性来控制一次上传的最大文件数。但是，在同步模式的时候，上传进度是总体进度。预览区中每个缩略图的进度没有完全验证和更新。但是，该插件为您提供了一种识别每个文件面临的上传错误的方法。

服务器端接收数据
在 uploadUrl 中设置的服务器方法接受从插件传入的如下数据
- 文件数据：数据以非常类似于表单 input="file"的形式传给服务器，例如在PHP中，你可以通过 $_FILES['input-name']来读取数据, input-name 是 input 标签的 name 属性值。类似于前面异步模式，如果不设置 name 属性， name 值默认为 file_data. 除了设置 multiple 为 true之外，你必须设置像此网站建议的数组格式设置你的 input 的 name.如果没有将 input 的 name 设为数组格式，你只会接收到服务器返回的第一个文件。在PHP中，可通过$_FILES['input-name']接收到文件数据，该文件数据是一个文件对象的数组。
- 额外数据：插件可发送额外数据给服务器方法。可通过设置 uploadExtraData 为一个键值对形式的关联数组对象。所以，如果你设置了 uploadExtraData={id:'kv-1'}, 那么在 PHP 中，可通过 \$_POST['id'] 读取到额外数据中的 id.
服务器端发送数据
在同步模式下，uploadUrl 必须以JSON编码的对象的形式发送数据。例如，服务器可以返回如下JSON对象：

// example JSON response from server
{
    error: 'An error exception message if applicable',
    errorkeys: [], // array of thumbnail keys/identifiers that have errored out (set via key property in initialPreviewConfig
    initialPreview: [
    ], // initial preview configuration 
    initialPreviewConfig: [
        // initial preview configuration if you directly want initial preview to be displayed with server upload data
    ],
    initialPreviewThumbTags: [
        // initial preview thumbnail tags configuration that will be replaced dynamically while rendering
    ],
    append: true // whether to append content to the initial preview (or set false to overwrite)
}