流动.js

Flow.js是一个JavaScript库,通过HTML5 File API提供多个同时,稳定并可恢复的上传功能.

该库旨在通过HTTP在上传大型文件时引入过错容忍. 这是通过将每个文件分成小块来实现的. 然后,当一个块的上传失败时,上传会被重审,直到程序完成. 这样可以让上传在网络连接失去本地或服务器后自动恢复上传. 此外,它允许用户暂停,恢复甚至恢复上传而不失去状态,因为只有目前上传的块会被中止,而不是整个上传.

Flow.js除下列数据外,没有任何外部依赖性: HTML5 File API。这可以用来将文件分成小块。 目前,这意味着支持仅限于Firefox 4+,Chrome 11+,Safari 6+和Internet Explorer 10+.

样本和实例载于 samples/ 文件夹。 请按下自己的 Markdown 来帮助记录工程 .

我能看看演示吗?

Flow.js + angular.js 文件上传演示 - ng-flow扩展页 https://github.com/flowjs/ng-flow 页面存档备份,存于互联网档案馆

JQuery和节点.js后端演示 https://github.com/flowjs/flow.js/tree/master/samples/Node.js

我怎么装?

从 https://github.com/flowjs/flow.js/releases (中文(简体) ) 它包含开发与精密化生产文件 dist/ 文件夹.

或使用 npm :

npm install @flowjs/flow.js

或使用弓箭:

bower install flow.js#~2

或使用 git 克隆

git clone https://github.com/flowjs/flow.js

我该怎么用呢?

一个新的 Flow 对象创建时,应提供发布内容和地点的信息:

var flow = new Flow({
  target:'/api/photo/redeem-upload-token', 
  query:{upload_token:'my_token'}
});
// Flow.js isn't supported, fall back on a different method
if(!flow.support) location.href = '/some-old-crappy-uploader';

要让文件被选中并被拖放, 您会指定一个投放目标和一个 DOM 项来浏览 :

flow.assignBrowse(document.getElementById('browseButton'));
flow.assignDrop(document.getElementById('dropTarget'));

之后,与Flow.js的交互是通过聆听事件完成的:

flow.on('fileAdded', function(file, event){
    console.log(file, event);
});
flow.on('fileSuccess', function(file,message){
    console.log(file,message);
});
flow.on('fileError', function(file, message){
    console.log(file, message);
});

我怎么用我的服务器来设置它?

Flow.js的大部分魔法发生在用户的浏览器中,但文件仍需要从服务器侧块重新组装. 这应该是一个相当简单的任务,可以在任何能够接收文件上传的网络框架或语言中实现.

为了处理上传块的状态,会随所有请求一起发送一些额外的参数:

• flowChunkNumber: 当前上传中块的索引。 第一个块是 1 (这里没有0基数).
• flowTotalChunks:块总数.
• flowChunkSize:一般块大小. 使用此值和 flowTotalSize 您可以计算块的总数。 请注意,HTTP收到的数据规模可能低于 flowChunkSize 用于文件的最后一个块.
• flowTotalSize: 文件总大小 .
• flowIdentifier: 请求所包含文件的唯一标识符.
• flowFilename: 原始文件名( 因为 Firefox 中的一个错误导致文件名没有在块多块文章中传输) .
• flowRelativePath: 文件在选择目录时的相对路径(默认在除Chrome外的所有浏览器中文件名称).

您应该允许同一块被多次上传; 这不是标准的行为, 但在一个不稳定的网络环境中,它可能会发生, 而这个案例正是Flow.js的设计目标.

对于每个请求,您可以在 HTTP 状态代码中确认接收(可以通过 permanentErrors 选项 :

• 200, (中文(简体) ), 201, (中文(简体) ), 202:块被接受并正确. 不用再装了.
• 404, (中文(简体) ), 415。 。 。 . 500, (中文(简体) ), 501: 不支持块上传的文件, 取消整个上传 .
• 还有什么: 出事了, 但尝试重新装入文件 .

处理获取(或 test() 请求)

启用 testChunks 选项将允许在浏览器重启后,甚至浏览器之间恢复上传(理论上,您甚至可以在多个标签或不同的浏览器之间运行相同的文件上传)。 这个 POST 列出的数据请求需要使用Flow.js来接收数据,但您可以通过执行相应的数据请求来扩展支持 GET 使用相同参数的请求:

• 如果此请求返回 a 200, (中文(简体) ), 201 或者说 202 HTTP代码,块被假定已经完成.
• 如果请求返回永久错误状态,则停止上传.
• 如果请求返回其他任何信息, 块将以标准方式上传 .

这件事之后 testChunks 启用后,即使浏览器重启后,上传也可以快速赶超,只需验证已经上传的不需要再上传的块.

完整文档

流动

配置

对象被装入配置选项 :

var r = new Flow({opt1:'val', ...});

可用的配置选项有:

• target 多部分 POST 请求的目标 URL 。 这可以是字符串或函数. 如果有的话 函数,它将被传递一个 FlowFile,一个 FlowChunk 并是 Test 布尔(默认 : /(中文(简体) )
• singleFile 启用单文件上传 。 一旦一个文件被上传,第二个文件将超过现有的一个文件,第一个文件将被取消。 (错误:虚假)
• chunkSize 每个上传数据块的字节大小 。 这可以是数字或函数. 如果一个函数, 它将被传递到一个 FlowFile 。 最后一个上传块将至少是这个大小, 最多有两个大小, 看 第51期 详情和理由。 (默认 : 1*1024*1024页:1
• forceChunkSize 强制所有块小于或等于块大小 。 否则,最后一个块将大于或等于 chunkSize. (默认 : false(中文(简体) )
• simultaneousUploads 同时上传的次数( 默认 ): 3(中文(简体) )
• fileParameterName 用于文件块的多部分 POST 参数的名称( 默认 : file(中文(简体) )
• query 多部分 POST 有数据包含的额外参数。 这可以是物体或物体 函数。 如果一个函数, 它将被传递到一个 FlowFile, 一个 FlowChunk 对象和一个 Test 布尔 (默认 : {}(中文(简体) )
• headers 在多部分 POST 中包含带有数据的额外标题 。 如果一个函数,它将被传递到一个 FlowFile, 一个 FlowChunk 对象和一个是 Test 布尔 (default: {}(中文(简体) )
• withCredentials 标准 CORS 请求默认不发送或设置任何 cookie 。 为了 包含 cookie 作为请求的一部分, 您需要设置 withCredentials 属性改为真实. (默认 : false(中文(简体) )
• method POST 块到服务器时使用的方法( P)multipart 或者说 octet) (过失: multipart(中文(简体) )
• testMethod 测试块时使用的 HTTP 方法 。 如果设置为函数, 将会通过 FlowFile 和 FlowChunk 参数 。 (默认 : GET(中文(简体) )
• uploadMethod 当块被上传时使用的 HTTP 方法 。 如果设置为函数, 将会通过 FlowFile 和 FlowChunk 参数 。 (默认 : POST(中文(简体) )
• allowDuplicateUploads 一旦一个文件被上传,允许重载同一文件. 默认情况下,如果一个文件已经上传,它将被跳过,除非该文件被从现有的Flow对象中移除. (默认 : false(中文(简体) )
• prioritizeFirstAndLastChunk 优先排列所有文件的第一和最后一个块 。 如果您能确定一个文件是否仅从第一个或最后一个块对您的服务有效, 则此功能是有用的 。 例如,相片或视频元数据通常位于文件的第一部分,这样就很容易从第一个块测试支持. (默认 : false(中文(简体) )
• testChunks 向服务器请求每个块是否已经存在 。 如果在服务器侧被执行,即使在浏览器崩溃甚至计算机重启后,也会允许上传恢复. (默认 : true(中文(简体) )
• preprocess 在测试和发送前处理每个块的可选函数 。 对于函数,它将被传送到块作为参数,并且应当调用 preprocessFinished 方法。 (默认 : null(中文(简体) )
• changeRawDataBeforeSend 在 XHR 请求发出之前更改 Raw 数据的可选功能 。 到函数时,它将被作为参数通过块和数据。 将数据退回XHR请求,不再作进一步修改。 (默认 : null) (中文(简体) ). 这在使用 FlowJS 时很有帮助 谷歌云存储。用法实例可见 276号. (关于更多,检查问题) 170号) (中文(简体) ).
• initFileFn 可选功能以初始化文件对象 。 对于函数,它将被传递一个 FlowFile 和 FlowChunk 参数 .
• readFileFn 可选功能将读取操作从原始文件包入. 到函数时, 将会通过 FlowFile 、 startByte 和 endByte、 文件 Type 和 FlowChunk .
• generateUniqueIdentifier 覆盖为每个文件生成唯一标识符的函数。 (默认 : null(中文(简体) )
• maxChunkRetries 上传失败前块的最大重试次数 。 有效值是任何正整数和 undefined 因为没有限制。 (默认 : 0(中文(简体) )
• chunkRetryInterval 在非永久错误上重试块前等待的毫秒数 。 有效值是任何正整数和 undefined 立即重试 (默认 : undefined(中文(简体) )
• progressCallbacksInterval 进度报告之间的时间间隔为毫秒。 准备 到 0 处理每次进度回调。 (默认 : 500(中文(简体) )
• speedSmoothingFactor 用于计算平均上传速度 。 数字从1到0 设置为 1 和平均上传速度等于当前上传速度。 更长的文件上传时间是 将这一数字设为0.02,因为剩余时间的估计将更加准确。 这个 参数必须与 progressCallbacksInterval 参数. (默认值 0.1)
• successStatuses 如果响应状态在此列表中( 默认 : [200,201, 202](中文(简体) )
• permanentErrors 如果响应状态在此列表中, 响应失败( 默认 : [404, 415, 500, 501](中文(简体) )

属性

• .support 当前浏览器是否支持 Flow.js 的布尔值指标 .
• .supportDirectory 一个布尔值,表示浏览器是否支持目录上传.
• .opts Flow.js 实例配置的散列对象 .
• .files 数组 FlowFile 用户添加的文件对象(见下文此对象类型的完整文件).

方法

• .assignBrowse(domNodes, isDirectory, singleFile, attributes) 将浏览动作指定给一个或多个 DOM 节点 .

  • domNodes 数组多姆节点或单一节点.
  • isDirectory 通过进来 true 以允许选择目录(仅选择Chrome,可以检查支持) supportDirectory (b) 财产).
  • singleFile 为了防止多个文件上传, 设置为真实 。 还查看了配置参数 singleFile。 。 。 .
  • attributes 传递按键对象和值以设置输入字段的自定义属性. 例如,你可以设定 accept 属性为 image/*。这意味着用户只能选择图像. 完整的属性列表 : https://www.w3.org/wiki/HTML/Elements/input/file (中文(简体) )

  注:避免使用 a 财务报告和审定财务报表 button 标记为文件上传按钮,使用跨度代替.

• .assignDrop(domNodes) 指定一个或多个DOM节点作为投放目标.

• .unAssignDrop(domNodes) 未指定一个或多个 DOM 节点作为投放目标 .

• .on(event, callback) 聆听 Flow.js 的事件(见下文)

• .off([event, [callback]])数字 :

  • .off() 所有事件都被删除.
  • .off(event) 删除特定事件的所有回调 .
  • .off(event, callback) 删除事件的特定召回 . callback 应该是一个 Function。 。 。 .

• .upload() 开始或恢复上传 .

• .pause() 暂停上传 .

• .resume() 继续上传.

• .cancel() 取消全部上传 FlowFile 对象并把它们从列表中删除.

• .progress() 返回0至1之间的浮点,表示所有文件的当前上传进度.

• .isUploading() 返回布尔, 显示实例是否正在上传 .

• .addFile(file) 在文件列表中添加 HTML5 文件对象 .

• .removeFile(file) 取消特定内容的上传 FlowFile 列表中的对象.

• .getFromUniqueIdentifier(uniqueIdentifier) 抬头看看 FlowFile 对象以其独特的标识符.

• .getSize() 返回上传字节的总大小.

• .sizeUploaded() 返回以字节形式上传的所有文件的总大小 .

• .timeRemaining() 返回剩余时间以秒计上传所有文件 。 准确性基于平均速度. 如果速度为零,剩下的时间将等于正无限 Number.POSITIVE_INFINITY

活动

• .fileSuccess(file, message, chunk) 具体文件已经完成 。 第一个参数 file 实例 FlowFile,第二个参数 message 包含服务器响应。 反应总是一串. 第三个论点 chunk 实例 FlowChunk。您可以通过访问 xhr 获取响应状态 对象 chunk.xhr.status。 。 。 .
• .fileProgress(file, chunk) 特定文件的上传已取得进展 .
• .fileAdded(file, event) 此事件用于文件验证 。 要拒绝此文件返回错误 . 此事件在文件添加到上传队列前也被调用 , 这意味着,呼叫 flow.upload() 函数不会启动当前文件上传. 可以选择使用浏览器 event 从文件时开始的对象 页:1.
• .filesAdded(array, event) 与文件添加相同,但用于多个文件验证.
• .filesSubmitted(array, event) 与已添加的文件相同, 但在文件添加到上传队列后发生 。 可用于开始上传当前添加的文件 .
• .fileRemoved(file) 从上传队列中删除了特定文件 。 与文件合并 下接, 可用于通知 UI 更新状态以匹配上传队列 .
• .fileRetry(file, chunk) 上传特定文件时出错, 上传是 再审.
• .fileError(file, message, chunk) 上传特定文件时发生错误 .
• .uploadStart() Flow 对象上传已经开始 .
• .complete() 上传完成 .
• .progress() 正在上传进度 .
• .error(message, file, chunk) 发生了包括文件错误在内的错误 .
• .catchAll(event, ...) 听上面列出的所有事件,具有相同的回调功能.

流程文件

流程文件构建器可以在 Flow.FlowFile。 。 。 .

属性

• .flowObj 回溯到家长 Flow 对象.
• .file 相关 HTML5 File 对象.
• .name 文件名称.
• .relativePath 文件的相对路径( 如果相对路径不存在则默认为文件名)
• .size 以文件字节表示大小 .
• .uniqueIdentifier 为此文件对象指定的独有标识符 。 此值包含在上传到服务器中以供参考,但在构建您上传的UI时也可以用于CSS类等.
• .averageSpeed 平均上传速度, 字节每秒 .
• .currentSpeed 当前上传速度, 字节每秒 .
• .chunks 数组 FlowChunk 页:1 你不需要去调查这些.
• .paused 显示文件是否被暂停 .
• .error 显示文件是否遇到错误 .

方法

• .progress(relative) 返回 0 到 1 之间的浮点,显示当前文件的上传进度 。 若为 relative 实值 true,该值相对于 Flow.js 实例中的所有文件返回.
• .pause() 暂停上传文件 .
• .resume() 继续上传文件 .
• .cancel() 中止上传文件, 从要上传的文件列表中删除 .
• .retry() 重试上传文件 .
• .bootstrap() 重建状态 FlowFile 对象,包括重新指定块和 XMLHttp 请求实例.
• .isUploading() 返回显示文件块是否正在上传的布尔 .
• .isComplete() 返回布尔表示文件是否已完成上传并收到服务器响应 .
• .sizeUploaded() 返回上传到字节的大小 .
• .timeRemaining() 返回剩余时间以秒计完成上传文件 。 准确性基于平均速度. 如果速度为零,剩下的时间将等于正无限 Number.POSITIVE_INFINITY
• .getExtension() 小写中返回文件扩展名.
• .getType() 返回文件类型 .

捐款

为确保源代码的一致性,请在工作时铭记这些规则:

• 所有特性或bug修正必须经过一个或多个规格的测试.

• 我们遵循载于 Google 的 JavaScript 样式指南 除了我们用100个字符包装所有代码.

安装依赖

1. 要复制您的 Github 仓库, 请运行 :

git clone [email protected]:<github username>/flow.js.git

2. 要访问 Flow.js 目录, 请运行:

cd flow.js

3. 添加节点.js 依赖性

npm install

测试

我们的单位和融合测试 与茉莉一起写 与卡玛一起执行。 运行所有 chrome运行中的测试 :

grunt karma:watch

或者选择其它浏览器

grunt karma:watch --browsers=Firefox,Chrome

浏览器应当分出逗号并区分大小写.

重新运行测试只需改变任何源或测试文件.

自动测试在每次犯罪后进行.

正在对酱油实验室进行测试

1. 连接到酱汁实验室 https://saucelabs.com/docs/连通
2. grunt test --sauce-local=true --sauce-username=**** --sauce-access-key=***

其他浏览器可用 --browsers 旗下,可用的浏览器: sl opera, sl iphone, sl safari, sl ie10, sl chrome, sl firefox

来源

Flow.js的灵感和进化来自 https://github.com/23/resumpable.js (中文(简体) ). 图书馆还配备了测试和功能,如文件夹拖放、上传速度、剩余时间估计、单独文件暂停、恢复和更多.