ReadableStream.ReadableStream()
草案
本页尚未完工.
Experimental
这是一个实验中的功能
此功能某些浏览器尚在开发中,请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订,所以在未来版本的浏览器中该功能的语法和行为可能随之改变。
ReadableStream()
构造器创建并返回包含处理函数的可读流实例.
语法
var readableStream = new ReadableStream(underlyingSource[, queueingStrategy]);
参数
- underlyingSource
- 一个包含定义了构造流行为方法和属性的对象.
underlyingSource
包括:- start(controller)
- 这是一个当对象被构造时立刻调用的方法.此方法的内容由开发人员定义,并应着眼于访问流,并执行其他任何必需的设置流功能.如果这个过程是异步完成的,它可以返回一个promise,表明成功或失败.传递给这个方法的
controller
是一个ReadableStreamDefaultController
(en-US)或ReadableByteStreamController
(en-US),具体取决于type
属性的值。开发人员可以使用此方法在设立期间控制流. - pull(controller) 可选
- 这个方法,也是由开发人员定义的,当流的内部队列不满时,会重复调用这个方法,直到队列补满。如果
pull()
返回一个promise,那么它将不会再被调用,直到promise完成;如果promise失败,该流将会出现错误.传递给此方法的controller
参数是ReadableStreamDefaultController
(en-US)或ReadableByteStreamController
(en-US),具体取决于type
属性的值。由于更多的块被获取,这个方法可以被开发人员用来控制流. - cancel(reason) 可选
- 如果应用程序表示该流将被取消(例如,调用了
ReadableStream.cancel()
(en-US),则将调用此方法,该方法也由开发人员定义。 该方法应该做任何必要的事情来释放对流的访问。 如果这个过程是异步的,它可以返回一个promise,表明成功或失败.原因参数包含一个DOMString
,它描述了流被取消的原因. - type 可选
- 该属性控制正在处理的可读类型的流。如果它包含一个设置为
bytes
的值,则传递的控制器对象将是一个ReadableByteStreamController
(en-US),能够处理BYOB(带您自己的缓冲区)/字节流。如果未包含,则传递的控制器将为ReadableStreamDefaultController
(en-US)。 - autoAllocateChunkSize 可选
- 对于字节流,开发人员可以使用正整数值设置
autoAllocateChunkSize
以打开流的自动分配功能。启用此功能后,流实现将自动分配一个具有给定整数大小的ArrayBuffer
,并调用底层源代码,就好像消费者正在使用BYOB阅读器一样。
- queueingStrategy 可选
- 一个可选择定义流的排队策略的对象。这需要两个参数:
- highWaterMark
- 非负整数 - 这定义了在应用背压之前可以包含在内部队列中的块的总数。
- size(chunk)
- 包含参数
chunk
的方法 - 这表示每个块使用的大小(以字节为单位).
Note: You could define your own custom
queueingStrategy
, or use an instance ofByteLengthQueueingStrategy
(en-US) orCountQueueingStrategy
(en-US) for this object value. If noqueueingStrategy
is supplied, the default used is the same as aCountQueuingStrategy
with a high water mark of 1.
返回值
ReadableStream
对象的实例.
错误
- RangeError
- 提供的值既不是
bytes
也不是undefined
.
例子
In the following simple example, a custom ReadableStream
is created using a constructor (see our Simple random stream example for the full code). The start()
function generates a random string of text every second and enqueues it into the stream. A cancel()
fuction is also provided to stop the generation if ReadableStream.cancel()
(en-US) is called for any reason.
When a button is pressed, the generation is stopped, the stream is closed using ReadableStreamDefaultController.close()
(en-US), and another function is run, which reads the data back out of the stream.
const stream = new ReadableStream({
start(controller) {
interval = setInterval(() => {
let string = randomChars();
// Add the string to the stream
controller.enqueue(string);
// show it on the screen
let listItem = document.createElement('li');
listItem.textContent = string;
list1.appendChild(listItem);
}, 1000);
button.addEventListener('click', function() {
clearInterval(interval);
fetchStream();
controller.close();
})
},
pull(controller) {
// We don't really need a pull in this example
},
cancel() {
// This is called if the reader cancels,
// so we should stop generating strings
clearInterval(interval);
}
});
Specifications
Specification | Status | Comment |
---|---|---|
Streams ReadableStream() |
Living Standard | Initial definition. |
Browser compatibility
BCD tables only load in the browser