Streams API

Experimental: 这是一个实验中的功能
此功能某些浏览器尚在开发中,请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订,所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

Streams API允许JavaScript以编程的方式访问通过网络接收的数据流,并根据开发人员的需要处理它们。

概念和用法

流将你希望通过网络接收的资源拆分成小块,然后按位处理它。这正是浏览器在接收用于显示web页面的资源时做的事情——视频缓冲区和更多的内容可以逐渐播放,有时候随着内容的加载,你可以看到图像逐渐地显示。

但曾经这些对于JavaScript是不可用的。以前,如果我们想要处理某种资源(如视频、文本文件等),我们必须下载完整的文件,等待它反序列化成适当的格式,然后在完整地接收到所有的内容后再进行处理。

随着流在JavaScript中的使用,一切发生了改变——只要原始数据在客户端可用,你就可以使用JavaScript 按位处理它,而不再需要缓冲区、字符串或blob。

还有更多的优点——你可以检测流何时开始或结束,将流链接在一起,根据需要处理错误和取消流,并对流的读取速度做出反应。

流的基础应用围绕着使响应可以被流处理展开。例如,一个成功的 fetch request 响应 Body 会暴露为 ReadableStream,之后你就可以使用 ReadableStream.getReader() 建立的 reader 读取它,使用 ReadableStream.cancel() (en-US) 取消它等等。

更复杂的应用包括使用 ReadableStream() 创建你自己的流,比如在 service worker 中处理数据。

你还可以使用 WritableStream (en-US) 将数据写入流中。

注意:你可以在这些文章中找到关于流理论的更多细节和实践 — Streams API concepts, Using readable streams,以及 Using writable streams

Stream 接口

Readable streams

ReadableStream
表示数据的可读流。用于处理 Fetch API 返回的响应,或者开发者自定义的流(例如通过 ReadableStream() 构造的流)。
ReadableStreamDefaultReader
表示默认阅读器,用于阅读来自网络的数据流(例如 fetch 请求)。
ReadableStreamDefaultController (en-US)
表示控制器,用于控制 ReadableStream 的状态及内部队列。默认的控制器用于处理非字节流。

Writable streams

WritableStream (en-US)
提供了将流写入目标这个过程的标准抽象表示,称为 sink。内置了背压和队列机制。
WritableStreamDefaultWriter (en-US)
表示默认写入器,用于将小块的数据写入可写流中。
WritableStreamDefaultController (en-US)
表示控制器,用于控制 WritableStream (en-US) 的状态。当创建一个 WritableStream 时,对应的 WritableStreamDefaultController 实例会被提供给底层的 sink 供其操作。

流相关的 API 及操作

ByteLengthQueuingStrategy (en-US)
提供建立流时所需的内置字节队列策略。
CountQueuingStrategy (en-US)
提供建立流时所需的块计数队列策略。

扩展

Request
当构造一个新的 Request 对象后,你可以给它的 RequestInit 中的 body 属性传入一个 ReadableStream。这个 Request 对象就可以被传入 WindowOrWorkerGlobalScope.fetch() 中,开始接收流。
Body
一个成功的 fetch request 响应 Body 会默认暴露为 ReadableStream,从而可以采用相应的阅读器来处理等。

字节流相关接口

重要:下面的 API 并没有在所有浏览器中都实现,关于规范细节是否处于完成状态可供实现还存在疑问。它们可能随时会改变。

ReadableStreamBYOBReader (en-US)
表示 BYOB("bring your own buffer")阅读器,用于阅读开发者提供的流数据(如自定义的 ReadableStream())。
ReadableByteStreamController (en-US)
表示控制器,用于控制 ReadableStream 的状态及内部队列。字节控制器用于处理字节流。
ReadableStreamBYOBRequest (en-US)
表示 ReadableByteStreamController (en-US) 中的 BYOB pull request。

Examples

We have created a directory of examples to go along with the Streams API documentation — see mdn/dom-examples/streams. The examples are as follows:

  • Simple stream pump: This example shows how to consume a ReadableStream and pass its data to another.
  • Grayscale a PNG: This example shows how a ReadableStream of a PNG can be turned into grayscale.
  • Simple random stream: This example shows how to use a custom stream to generate random strings, enqueue them as chunks, and then read them back out again.
  • Simple tee example: This example extends the Simple random stream example, showing how a stream can be teed and both resulting streams can be read independently.
  • Simple writer: This example shows how to to write to a writable stream, then decode the stream and write the contents to the UI.
  • Unpack chunks of a PNG: This example shows how pipeThrough() can be used to transform a ReadableStream into a stream of other data types by transforming a data of a PNG file into a stream of PNG chunks.

Examples from other developers:

Specifications

Specification Status Comment
Streams Living Standard Initial definition.

Browser compatibility

ReadableStream

BCD tables only load in the browser

WritableStream

BCD tables only load in the browser

See also