ReadableStreamBYOBReader
注意：此功能在 Web Workers 中可用。
ReadableStreamBYOBReader 介面是 Streams API 的一部分，它定義了一個用於 ReadableStream 的讀取器，該讀取器支援從底層位元組源進行零複製讀取。它可用於從資料以“匿名”位元組序列形式提供的底層源（例如檔案）進行高效複製。
通常應該透過在流上呼叫 ReadableStream.getReader() 來獲取此讀取器型別的例項，並在選項引數中指定 mode: "byob"。可讀流必須具有底層位元組源。換句話說，它必須在 構造 時使用 type: "bytes" 指定了底層源。
使用此類讀取器時，當可讀流的內部佇列為空時發起的 read() 請求將導致從底層源進行零複製傳輸（繞過流的內部佇列）。如果內部佇列不為空，read() 將從緩衝的資料中滿足請求。
請注意，此讀取器的方法和屬性與預設讀取器（ReadableStreamDefaultReader）的方法和屬性類似。read() 方法的區別在於它提供了寫入資料的檢視。
建構函式
ReadableStreamBYOBReader()-
建立並返回一個
ReadableStreamBYOBReader物件例項。
例項屬性
ReadableStreamBYOBReader.closed只讀-
返回一個
Promise，當流關閉時該 Promise 將 fulfilled，或者在流丟擲錯誤或讀取器的鎖被釋放時 reject。此屬性使您能夠編寫響應流結束的程式碼。
例項方法
ReadableStreamBYOBReader.cancel()-
返回一個
Promise，當流被取消時解析。呼叫此方法表示消費者對該流不再感興趣。提供的reason引數將傳遞給底層源，源可能會也可能不會使用它。 ReadableStreamBYOBReader.read()-
傳遞一個必須寫入資料的檢視，並返回一個
Promise，該 Promise 將解析為流中的下一個塊，或 reject 並指示流已關閉或出錯。 ReadableStreamBYOBReader.releaseLock()-
釋放讀取器對流的鎖定。
示例
下面的示例摘自 使用可讀位元組流 中的即時示例。
首先，透過在流上呼叫 ReadableStream.getReader() 並指定選項引數中的 mode: "byob" 來建立讀取器。由於這是一個“自帶緩衝區”讀取器，我們還需要建立一個 ArrayBuffer 來讀取資料。
const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(200);
下面是一個使用該讀取器的函式。它遞迴呼叫 read() 方法將資料讀取到緩衝區中。該方法接受一個 Uint8Array 型別化陣列，該陣列是原始陣列緩衝區中尚未寫入部分的視覺化檢視。檢視的引數是根據先前呼叫中接收到的資料計算的，這些資料定義了原始陣列緩衝區的偏移量。
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，可用於監視流的關閉或錯誤，或者讀取器鎖的釋放。
reader.closed
.then(() => {
// Resolved - code to handle stream closing
})
.catch(() => {
// Rejected - code to handle error
});
要取消流，請呼叫 ReadableStreamBYOBReader.cancel()，可以選擇指定一個原因。這將返回一個 Promise，當流被取消時該 Promise 將解析。當流被取消時，控制器將依次呼叫底層源上的 cancel()，並將可選原因傳遞進去。
在 使用可讀位元組流 中的示例程式碼會在按鈕被按下時呼叫 cancel 方法，如下所示。
button.addEventListener("click", () => {
reader.cancel("user choice").then(() => console.log("cancel complete"));
});
消費者還可以呼叫 releaseLock() 來釋放讀取器對流的持有，但前提是沒有待處理的讀取。
reader.releaseLock();
規範
| 規範 |
|---|
| Streams # byob-reader-class |
瀏覽器相容性
載入中…