ReadableByteStreamController
注意:此功能在Web Workers中可用。
ReadableByteStreamController
是 Streams API 的一个接口,它表示 可读字节流 的控制器。它允许控制 ReadableStream
的状态和内部队列(该流具有底层字节源),并在流的内部队列为空时,实现从底层源到消费者的有效零复制数据传输。
如果将具有 type="bytes"
属性的 underlyingSource
对象作为参数传递给 ReadableStream()
构造函数,则会创建此控制器类型的实例。underlyingSource
对象还可以定义 start()
和 pull()
回调函数。这些函数会以控制器作为参数被调用,以便设置底层源,并在需要时请求数据。
底层源使用控制器通过其 byobRequest
属性或 enqueue()
方法向流提供数据。 byobRequest
是一个 ReadableStreamBYOBRequest
对象,表示消费者请求将数据直接零复制传输到消费者的挂起请求。如果数据存在,则必须使用 byobRequest
来复制数据(在这种情况下不要使用 enqueue()
)!如果底层源需要将数据传递到流中并且 byobRequest
为 null
,则源可以调用 enqueue()
将数据添加到流的内部队列。
请注意,只有在读者有请求且流的内部队列为空时,“BYOB 模式”下才会创建 byobRequest
。“BYOB 模式”在使用 ReadableStreamBYOBReader
时启用(通常通过使用参数 { mode: 'byob' }
调用 ReadableStream.getReader()
来构建)。当使用默认读取器且 autoAllocateChunkSize
在 ReadableController()
构造函数 中指定时,它也会启用。
底层字节源还可以使用控制器 close()
在发送所有数据后关闭流,并使用 error()
报告底层源的错误。控制器的 desiredSize
属性用于应用“背压”,告知底层源内部队列的大小(较小的值表示队列正在填满,提示底层源最好暂停或限制流入)。
请注意,即使控制器主要由底层字节源使用,也没有理由不能将其存储在系统其他部分中以向流发出信号。
构造函数
无。如果将具有 type="bytes"
属性的 underlyingSource
传递给 ReadableStream()
构造函数,则会自动创建 ReadableByteStreamController
实例。
实例属性
ReadableByteStreamController.byobRequest
只读-
返回当前 BYOB 拉取请求,如果没有任何挂起请求,则返回
null
。 ReadableByteStreamController.desiredSize
只读-
返回填充流的内部队列所需的所需大小。
实例方法
ReadableByteStreamController.close()
-
关闭关联的流。
ReadableByteStreamController.enqueue()
-
将给定的块入队到关联的流中。
ReadableByteStreamController.error()
-
导致与关联流的任何未来交互都出错。
示例
控制器由底层源用于传输或入队数据,以指示流没有更多数据(已关闭)或已出错。它还用于使用 desiredSize
从“上游”向底层源发出所需数据速率的信号。
使用可读字节流中的示例,特别是 创建可读套接字推送字节流,展示了大多数这些情况。
规范
规范 |
---|
Streams 标准 # rbs-controller-class |
浏览器兼容性
BCD 表格仅在启用了 JavaScript 的浏览器中加载。
另请参阅
- Streams API 概念
- 使用可读字节流
ReadableStream
- WHATWG 流可视化工具,用于可读、可写和转换流的基本可视化。
- Web-streams-polyfill 或 sd-streams - polyfills