# @flowjs/flow\.js 中文文档

规范地址：https://npmcn.com/package/%40flowjs/flow.js/

版本：2\.14\.1
npm 元数据更新时间：2022-06-12T18:01:50.544Z
中文译文更新时间：2026-11-15T00:32:08.046Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flowjs/flow.js
原文对照：https://npmcn.com/package/%40flowjs/flow.js/?lang=original
项目主页：https://github.com/flowjs/flow.js#readme
源码仓库：https://github.com/flowjs/flow.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：274 kB，53 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2015-12-16T15:13:00.498Z
- 最新版本发布：2020-06-05T10:54:02.890Z
- 近 30 天下载量：150935（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

Flow.js库执行html5文件上传功能,并提供多个同时,稳定,容错和可重复上传功能.

## 安装

```sh
npm install @flowjs/flow.js
```

也可以使用：`pnpm add @flowjs/flow.js`、`yarn add @flowjs/flow.js`、`bun add @flowjs/flow.js`

## README

# 流动.js [![Build Status](https://travis-ci.org/flowjs/flow.js.svg)](https://travis-ci.org/flowjs/flow.js) [![Test Coverage](https://codeclimate.com/github/flowjs/flow.js/badges/coverage.svg)](https://codeclimate.com/github/flowjs/flow.js/coverage)

[![Saucelabs Test Status](https://saucelabs.com/browser-matrix/flowjs.svg)](https://saucelabs.com/u/flowjs)

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 文件上传演示](http://flowjs.github.io/ng-flow/) - ng-flow扩展页 [https://github.com/flowjs/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/tree/master/samples/Node.js)

## 我怎么装?

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

或使用 npm :

```console
npm install @flowjs/flow.js
```

或使用弓箭:

```console
bower install flow.js#~2
```

或使用 git 克隆

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

## 我该怎么用呢?

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

```javascript
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 项来浏览 :

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

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

```javascript
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` 启用后,即使浏览器重启后,上传也可以快速赶超,只需验证已经上传的不需要再上传的块.

## 完整文档

### 流动

#### 配置

对象被装入配置选项 :

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

可用的配置选项有:

-   `target` 多部分 POST 请求的目标 URL 。 这可以是字符串或函数. 如果有的话 函数,它将被传递一个 FlowFile,一个 FlowChunk 并是 Test 布尔(默认 : `/`(中文(简体) )
-   `singleFile` 启用单文件上传 。 一旦一个文件被上传,第二个文件将超过现有的一个文件,第一个文件将被取消。 (错误:虚假)
-   `chunkSize` 每个上传数据块的字节大小 。 这可以是数字或函数. 如果一个函数, 它将被传递到一个 FlowFile 。 最后一个上传块将至少是这个大小, 最多有两个大小, 看 [第51期](https://github.com/23/resumable.js/issues/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 时很有帮助 [谷歌云存储](https://cloud.google.com/storage/docs/json_api/v1/how-tos/multipart-upload)。用法实例可见 [276号](https://github.com/flowjs/flow.js/pull/276). (关于更多,检查问题) [170号](https://github.com/flowjs/flow.js/issues/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 (中文(简体) )](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 样式指南](https://google.github.io/styleguide/jsguide.html) 除了我们用100个字符包装所有代码.
    

## 安装依赖

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

```console
git clone git@github.com:<github username>/flow.js.git
```

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

```console
cd flow.js
```

3.  添加节点.js 依赖性

```console
npm install
```

## 测试

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

```console
grunt karma:watch
```

或者选择其它浏览器

```console
grunt karma:watch --browsers=Firefox,Chrome
```

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

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

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

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

1.  连接到酱汁实验室 [https://saucelabs.com/docs/连通](https://saucelabs.com/docs/connect)
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 (中文(简体) )](https://github.com/23/resumable.js). 图书馆还配备了测试和功能,如文件夹拖放、上传速度、剩余时间估计、单独文件暂停、恢复和更多.

## 常见问题

### @flowjs/flow\.js 是什么？

Flow\.js库执行html5文件上传功能,并提供多个同时,稳定,容错和可重复上传功能\.

### 如何安装 @flowjs/flow\.js？

在项目目录运行 npm install @flowjs/flow\.js，或使用 pnpm add / yarn add / bun add。

### @flowjs/flow\.js 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flowjs\_\_flow\.js 是否存在。

### @flowjs/flow\.js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @flowjs/flow\.js 可以商用吗？

@flowjs/flow\.js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flowjs/flow\.js 的下载量有多少？

根据 npm 官方下载统计，@flowjs/flow\.js 在 2026/10/15 – 2026/11/13 这 30 天内被下载 150,935 次，日均约 5,031 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flowjs/flow\.js 还在维护吗？

最新版本 2\.14\.1 发布于 2020/06/05（6 年前）；至今共发布 8 个版本，其中过去 12 个月发布了 0 个；首次发布于 2015/12/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。