文件上传插件 -- fileinput

2019-08-13  本文已影响0人  Robot_Lee

1.特性

注意：
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 标准构建。大多数现代浏览器都支持这个标准，但是对于不支持的浏览器，插件将自动降级为基于表单的正常提交。

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 预览文件 √ √
通过表单提交直接读取文件 √
每个预览缩略图有独立的文件删除图标 √1 √2
每个预览缩略图有独立的文件上传图标 √
要求服务器端返回有效的JSON √
要求浏览器支持 HTML FormData/XHR2 √
服务器端代码能处理 ajax 并返回 JSON √
通过拖放区拖放文件 √3 √
能够为已选择的列表追加文件 √
能够为已选择的列表删除文件 √1 √
支持上传进度条 √
支持上传状态 √
支持可恢复的 / 块上传 √
支持读取额外的 FormData 数据 直接通过表单提交 通过设置 uploadExtraData 属性
支持上传前设置图片尺寸 √

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，设置您自己的图标主题。

可选的依赖插件

使用：步骤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版本可用，遵照如下步骤来设置插件语言

6 Ajax 方式上传

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

异步上传

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

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

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

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

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

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

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

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

同步上传

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

// 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)
}
上一篇下一篇

猜你喜欢

热点阅读