入门指南


v10.32.0 下载包:http://oss.cndoc.wiki/cndoc/10/code/jQuery-File-Upload-v10.32.0.zip

概述


jQuery FileUpload 插件支持多文件上传、支持拖拽上传、支持上传进度条显示、支持 jQuery 音视频和图像的预览及校验。
译者注:后续 jQuery FileUpload 插件简写为 本插件

支持跨域、分块和文件断点续传功能,以及通过客户端调整图像大小。

适用于所有支持标准 HTML 表单文件上传的服务端平台(包括 PHP、Python、Ruby on Rails、Java、Node.js、Go 等)。

示例


jQuery FileUpload 插件 Demo

特性


  • 多文件上传:
    允许一次选择多个文件并同时上传。
  • 拖拽上传:
    允许将文件从桌面或文件夹中拖放到浏览器窗口来进行文件上传。
  • 上传进度条:
    支持为单个文件显示进度条;支持为同时上传的所有文件显示总进度。
  • 允许中途取消:
    单文件上传的场景允许中途取消并终止本次上传进程。
  • 断点续传:
    在支持 Blob API 的浏览器下已终止的上传允许再次上传实现断点续传。
  • 分块上传:
    在支持 Blob API 的浏览器下,大文件可以切割成多个小块进行分块上传。
  • 客户端图像大小调整:
    通过 JS API 可以在浏览器在图像上传时实现客户端自动调整大小。
  • 图像、音频及视频预览:
    在浏览器对图像、音频或视频进行上传之前,可以通过接口实现预览。
  • 无需浏览器安装任何其他插件(例如 Adob​​e Flash):
    本插件是基于标准 HTML5 和 JavaScript 开发的,并且不需要额外的浏览器插件即可运行。
  • 完美兼容旧版浏览器:
    通过 XMLHttpRequests 和 iframe 网页内嵌框架来上传文件,作为运行于旧版浏览器上的兼容方案。
  • 可结合 HTML 表单的 file input 标签进行上传:
    允许通过标准 HTML 文件上传表单作为插件元素来提交文件。
  • 跨域文件上传:
    支持通过 XMLHttpRequests 或 iframe 重定向对文件进行跨域上传。
  • 支持创建多个实例:
    在同一页面上允许创建多个插件实例。
  • 可定制及扩展性:
    插件提供了一个 API 来设置独立选项,并且所有事件均可以定义回调方法。
  • 二进制类型传输及文件流方式上传:
    支持通过标准二进制类型传输(HTTP multipart/form-data 编码方式)或文件流方式(HTTP PUT 请求方法)实现文件上传。
  • 兼容于任何服务端应用平台:
    适用于任何支持标准 HTML 表单文件上传的服务端平台(PHP、Python、Ruby on Rails、Java、Node.js、Go 等)。

安全须知


请阅读 漏洞列表 以获取已修复的漏洞清单

另请阅读 安全指引 以获取有关如何安全地配置 Web 服务器以进行文件上传的说明。

安装


jQuery File Upload 可以通过 NPM 安装:

$ npm install blueimp-file-upload

然后通过它的扩展模块 node_modules 来加载 jquery.fileupload.js 文件(html):

<script src="node_modules/blueimp-file-upload/js/jquery.fileupload.js"></script>

再使用以下方式初始化插件后便完成安装,可以通过表单进行文件上传(js):

$('#fileupload').fileupload();

请参阅以下指南获取更多信息:

依赖关系


必要依赖项
选择性依赖项
  • JavaScript模板引擎 v3+:用于渲染选择、上传文件的页面标签。
  • JavaScript-Load-Image库 v2+:一个用于加载以 File 或 Blob 对象提供的图像或通过 URL 加载的库。客户端图像预览和调整大小功能需要用到这个库。
  • JavaScript-Canvas-to-Blob 函数 v3+:HTML 将画布元素(Canvas)转换为 Blob 对象的函数。图像大小调整功能需要用到。
  • Bootstrap v3+:示例文件的前端 UI 模板。
  • Bootstrap 内置的 Glyphicons 图标套件。
跨域功能所需要的依赖项

使用 iframe 传输插件进行跨域文件上传后,需要重定向回源服务器来查询上传结果。可参阅示例,其使用 result.html 作为源服务器的静态重定向页面。

JQuery FileUpload 库中还包含了 jQuery XDomainRequest 传输插件,其可以在 Microsoft IE8 和 IE9 中实现跨域 ajax 请求(旧版 IE 浏览器默认不支持跨域 XHR 请求,IE10 及以上则支持)。

库中 XDomainRequest 对象仅支持 GET 和 POST 请求,不支持文件上传。在示例中展示了如何删除已经上传到跨域服务器上的 demo 文件。

浏览器支持


桌面浏览器

jQuery FileUpload 插件定期使用最新的浏览器版本进行测试,并支持以下最低版本:

  • Google Chrome
  • Apple Safari 4.0+
  • Mozilla Firefox 3.0+
  • Opera 11.0+
  • Microsoft Internet Explorer 6.0+
移动端浏览器

jQuery FileUpload 插件已经过测试并支持以下移动端浏览器:

  • Apple Safari on iOS 6.0+
  • Google Chrome on iOS 6.0+
  • Google Chrome on Android 4.0+
  • Default Browser on Android 2.3+
  • Opera Mobile 12.0+
扩展浏览器

有关每个浏览器版本支持的功能和已知操作系统 / 浏览器 bug 的详细概述,请查阅扩展浏览器支持信息

测试


本项目中附带了三组测试:

  1. 代码问题排查使用 ESLint
  2. 单元测试使用 Mocha
  3. 端对端测试则使用 blueimp/wdio

按照下列步骤可运行测试实例:

  1. 启动 Docker
  2. 安装开发依赖项:
    npm install
  3. 运行测试用例:
    npm test

技术支持


该项目在 GitHub 由社区开发人员积极维护、管理,但未获得任何官方渠道进行支持。

如果您遇到任何待解决的问题需要求助其他开发人员,请将其发送到 Stack Overflow 并使用 blueimp jquery file upload 来标记您的问题。