ReadableStreamBYOBReader

注意：此功能在Web 工作线程中可用。

ReadableStreamBYOBReader 接口是 流 API 的一部分，它定义了一个用于 ReadableStream 的读取器，该读取器支持从底层字节源进行零拷贝读取。它用于从底层源（例如文件）高效地复制数据，其中数据以“匿名”字节序列的形式传递。

此读取器类型的实例通常应通过在流上调用 ReadableStream.getReader() 并指定选项参数中的 mode: "byob" 来获取。可读流必须具有底层字节源。换句话说，它必须已使用 type: "bytes" 指定底层源进行构建。

使用这种读取器，当可读流的内部队列为空时，read() 请求将导致从底层源进行零拷贝传输（绕过流的内部队列）。如果内部队列不为空，则 read() 将从缓冲数据中满足请求。

请注意，方法和属性与默认读取器 (ReadableStreamDefaultReader) 的方法和属性类似。read() 方法的不同之处在于它提供了一个用于写入数据的视图。

构造函数

ReadableStreamBYOBReader()

创建并返回一个 ReadableStreamBYOBReader 对象实例。

实例属性

ReadableStreamBYOBReader.closed 只读

返回一个 Promise，当流关闭时，该 Promise 将 fulfilled，如果流抛出错误或读取器的锁被释放，则该 Promise 将 rejected。此属性使您能够编写响应流处理结束的代码。

实例方法

ReadableStreamBYOBReader.cancel()

返回一个 Promise，该 Promise 在流被取消时解析。调用此方法表示消费者不再对流感兴趣。提供的 reason 参数将传递给底层源，底层源可能会或可能不会使用它。

ReadableStreamBYOBReader.read()

传递一个必须将数据写入其中的视图，并返回一个 Promise，该 Promise 将解析为流中的下一个块，或者拒绝指示流已关闭或发生错误。

ReadableStreamBYOBReader.releaseLock()

释放读取器对流的锁定。

示例

下面的示例取自 使用可读字节流 中的实时示例。

首先使用流上的 ReadableStream.getReader() 创建读取器，并在选项参数中指定 mode: "byob"。由于这是一个“自带缓冲区”读取器，因此我们还需要创建一个 ArrayBuffer 来读取数据。

js
const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(200);

下面显示了一个使用读取器的函数。此函数递归地调用 read() 方法以将数据读取到缓冲区中。该方法采用一个 Uint8Array 类型化数组，该数组是原始数组缓冲区中尚未写入的部分的视图。视图的参数是从先前调用中接收到的数据计算出来的，这些数据定义了原始数组缓冲区中的偏移量。

js
readStream(reader);

function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  // read() returns a promise that resolves when a value has been received
  reader
    .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
    .then(function processText({ done, value }) {
      // Result objects contain two properties:
      // done  - true if the stream has already given all its data.
      // value - some data. Always undefined when done is true.

      if (done) {
        logConsumer(`readStream() complete. Total bytes: ${bytesReceived}`);
        return;
      }

      buffer = value.buffer;
      offset += value.byteLength;
      bytesReceived += value.byteLength;

      logConsumer(
        `Read ${value.byteLength} (${bytesReceived}) bytes: ${value}`,
      );
      result += value;

      // Read some more, and call this function again
      return reader
        .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
        .then(processText);
    });
}

当流中没有更多数据时，read() 方法将解析为一个对象，该对象的 done 属性设置为 true，并且函数返回。

ReadableStreamBYOBReader.closed 属性返回一个 Promise，该 Promise 可用于监视流是否已关闭或发生错误，或者读取器锁是否已释放。

js
reader.closed
  .then(() => {
    // Resolved - code to handle stream closing
  })
  .catch(() => {
    // Rejected - code to handle error
  });

要取消流调用 ReadableStreamBYOBReader.cancel()，可以选择指定一个原因。这将返回一个 Promise，该 Promise 在流被取消后将解析。当流被取消时，控制器将依次在底层源上调用 cancel()，并将可选的原因传递进去。

使用可读字节流 中的示例代码在按下按钮时调用取消方法，如下所示

js
button.addEventListener("click", () => {
  reader.cancel("user choice").then(() => console.log("cancel complete"));
});

消费者还可以调用 releaseLock() 来释放读取器对流的保持，但前提是没有读取挂起

js
reader.releaseLock();

规范

规范
流标准
# byob-reader-class

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅