Streams API

翻译不完整。 请帮助我们翻译这篇文章!

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

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

概念和用法

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

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

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

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

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

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

你还可以使用 WritableStream 将数据写入流中。

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

Stream 接口

Readable streams

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

Writable streams

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

流相关的 API 及操作

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

扩展

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

字节流相关接口

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

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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
ReadableStream
Experimental
Chrome Full support 43Edge Full support 14Firefox Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 30Safari Full support 10.1WebView Android Full support 43Chrome Android Full support 43Firefox Android Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 30Safari iOS Full support 10.3Samsung Internet Android Full support 4.0
ReadableStream() constructor
Experimental
Chrome Full support 43Edge Full support 79Firefox Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 30Safari Full support 10.1WebView Android Full support 43Chrome Android Full support 43Firefox Android Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 30Safari iOS Full support 10.3Samsung Internet Android Full support 4.0
cancel
Experimental
Chrome Full support 43Edge Full support 14Firefox Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 30Safari Full support 10.1WebView Android Full support 43Chrome Android Full support 43Firefox Android Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 30Safari iOS Full support 10.3Samsung Internet Android Full support 4.0
getReader
Experimental
Chrome Full support 43Edge Full support 14Firefox Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 30Safari Full support 10.1WebView Android Full support 43Chrome Android Full support 43Firefox Android Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 30Safari iOS Full support 10.3Samsung Internet Android Full support 4.0
locked
Experimental
Chrome Full support 43Edge Full support 14Firefox Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 30Safari Full support 10.1WebView Android Full support 43Chrome Android Full support 43Firefox Android Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 30Safari iOS Full support 10.3Samsung Internet Android Full support 4.0
pipeThrough
Experimental
Chrome Full support 59Edge Full support 79Firefox No support NoIE No support NoOpera Full support 46Safari Full support 10.1WebView Android Full support 59Chrome Android Full support 59Firefox Android No support NoOpera Android Full support 43Safari iOS Full support 10.3Samsung Internet Android Full support 7.0
pipeTo
Experimental
Chrome Full support 59Edge Full support 79Firefox No support NoIE No support NoOpera Full support 46Safari Full support 10.1WebView Android Full support 59Chrome Android Full support 59Firefox Android No support NoOpera Android Full support 43Safari iOS Full support 10.3Samsung Internet Android Full support 7.0
tee
Experimental
Chrome Full support 43Edge Full support 79Firefox Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 30Safari Full support 10.1WebView Android Full support 43Chrome Android Full support 43Firefox Android Full support 65
Full support 65
Full support 57
Disabled
Disabled From version 57: this feature is behind the dom.streams.enabled preference (needs to be set to true) and the javascript.options.streams preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 30Safari iOS Full support 10.3Samsung Internet Android Full support 4.0

Legend

Full support  
Full support
No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
User must explicitly enable this feature.
User must explicitly enable this feature.

WritableStream

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
WritableStreamChrome Full support 59Edge Full support 16Firefox No support NoIE No support NoOpera Full support 47Safari ? WebView Android Full support 59Chrome Android Full support 59Firefox Android No support NoOpera Android Full support 44Safari iOS ? Samsung Internet Android Full support 7.0
WritableStream() constructorChrome Full support 59Edge Full support 16Firefox No support NoIE No support NoOpera Full support 47Safari ? WebView Android Full support 59Chrome Android Full support 59Firefox Android No support NoOpera Android Full support 44Safari iOS ? Samsung Internet Android Full support 7.0
abortChrome Full support 59Edge Full support 16Firefox No support NoIE No support NoOpera Full support 47Safari ? WebView Android Full support 59Chrome Android Full support 59Firefox Android No support NoOpera Android Full support 44Safari iOS ? Samsung Internet Android Full support 7.0
getWriterChrome Full support 59Edge Full support 16Firefox No support NoIE No support NoOpera Full support 47Safari ? WebView Android Full support 59Chrome Android Full support 59Firefox Android No support NoOpera Android Full support 44Safari iOS ? Samsung Internet Android Full support 7.0
lockedChrome Full support 59Edge Full support 16Firefox No support NoIE No support NoOpera Full support 47Safari ? WebView Android Full support 59Chrome Android Full support 59Firefox Android No support NoOpera Android Full support 44Safari iOS ? Samsung Internet Android Full support 7.0

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown

See also