ReadableStreamBYOBReader：read() 方法

注意：此功能在Web Workers中可用。

read() 方法是 ReadableStreamBYOBReader 接口的一部分，用于将数据读取到用户提供的缓冲区上的视图中，该缓冲区来自关联的可读字节流。如果存在任何数据，则将从流的内部队列中满足对数据的请求。如果流队列为空，则可以从底层字节源以零拷贝传输的方式提供请求。

该方法将一个缓冲区视图作为参数，数据将被读取到该视图中，并返回一个Promise。当数据可用或流被取消时，promise 将以包含 value 和 done 属性的对象的形式完成，如果流出错，则 promise 将被拒绝并包含相关的错误对象。

如果提供了数据块，则 value 属性将包含一个新视图。这将是一个与传递给 read() 方法的原始 view 具有相同缓冲区/后备内存（以及相同类型）的视图，现在填充了新的数据块。请注意，一旦 promise 完成，传递给该方法的原始 view 将被分离，并且不再可用。如果流已被取消，则 promise 将以 value: undefined 完成。在这种情况下，view 的后备内存区域将被丢弃，并且不会返回给调用者（视图缓冲区中所有先前读取的数据都将丢失）。

done 属性指示是否期望更多数据。如果流已关闭或取消，则该值设置为 true，否则设置为 false。

语法

read(view)

参数

view: 要将数据读取到的视图。

返回值

一个Promise，它将根据流的状态以结果的形式完成/拒绝。

以下是可能的情况

如果数据块可用并且流仍然处于活动状态，则 promise 将以以下形式的对象完成
js
```
{ value: theChunk, done: false }
```
theChunk 是包含新数据的视图。这与传递给 read() 方法的 view 具有相同的类型和后备内存。原始 view 将被分离，并且不再可用。
如果流已关闭，则 promise 将以以下形式的对象完成（其中 theChunk 与上面具有相同的属性）
js
```
{ value: theChunk, done: true }
```
如果流已被取消，则 promise 将以以下形式的对象完成
js
```
{ value: undefined, done: true }
```
在这种情况下，后备内存将被丢弃。
如果流抛出错误，则 promise 将拒绝并包含相关的错误。

异常

TypeError: 源对象不是 ReadableStreamBYOBReader，流没有所有者，视图不是对象或已被分离，视图的长度为 0，或调用了ReadableStreamBYOBReader.releaseLock()（当有挂起的读取请求时）。

示例

此处的示例代码取自使用可读字节流中的实时示例。

首先，我们使用流上的ReadableStream.getReader()创建读取器，并在选项参数中指定 mode: "byob"。我们还需要创建一个 ArrayBuffer，它是我们将写入的视图的“后备内存”。

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

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

readStream(reader);

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

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

        if (done) {
          // There is no more data in the stream
          return;
        }

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

        // Read some more, and call this function again
        // Note that here we create a new view over the original buffer.
        return reader
          .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
          .then(processBytes);
      });
  }
}

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

规范

规范
流标准 # ref-for-byob-reader-read③

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅

ReadableStreamBYOBReader() 构造函数
使用可读字节流