ReadableStream: cancel() 方法

Baseline 已廣泛支援

此功能已成熟,並可在多種裝置和瀏覽器版本上使用。自 ⁨2019 年 1 月⁩起,它已在所有瀏覽器中可用。

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

ReadableStream 介面的 cancel() 方法返回一個 Promise,該 Promise 在流被取消時解析。

當您已完全完成流的處理,不再需要從中讀取任何資料時,可以使用 cancel。即使有等待讀取的已入隊塊(chunks),這些資料在呼叫 cancel 後也會丟失,流也不再可讀。要仍然讀取這些塊而不完全丟棄流,您應該使用 ReadableStreamDefaultController.close()

語法

js
cancel()
cancel(reason)

引數

reason 可選

用於取消的可讀的理由。這會被傳遞給底層源(underlying source),底層源可能會也可能不會使用它。

返回值

一個 Promise,它會以 undefined 值 fulfilled。

異常

TypeError

您嘗試取消的流不是 ReadableStream,或者它已被鎖定。

示例

在下面的示例中,一個流被用來逐塊獲取 WHATWG HTML 規範;每個塊都會被搜尋字串 "service workers"。當找到搜尋詞時,會使用 cancel() 方法取消流——任務已完成,因此不再需要它。

html
<pre id="output"></pre>
js
const searchTerm = "service workers";
// Chars to show either side of the result in the match
const contextBefore = 30;
const contextAfter = 30;
const caseInsensitive = true;
const url = "https://html.spec.whatwg.org/";

log(`Searching '${url}' for '${searchTerm}'`);

fetch(url)
  .then((response) => {
    log("Received headers");

    const decoder = new TextDecoder();
    const reader = response.body.getReader();
    const toMatch = caseInsensitive ? searchTerm.toLowerCase() : searchTerm;
    const bufferSize = Math.max(toMatch.length - 1, contextBefore);

    let bytesReceived = 0;
    let buffer = "";
    let matchFoundAt = -1;

    return reader.read().then(function process(result) {
      if (result.done) {
        log("Failed to find match");
        return;
      }

      bytesReceived += result.value.length;
      log(`Received ${bytesReceived} bytes of data so far`);

      buffer += decoder.decode(result.value, { stream: true });

      // already found match & just context-gathering?
      if (matchFoundAt === -1) {
        matchFoundAt = (
          caseInsensitive ? buffer.toLowerCase() : buffer
        ).indexOf(toMatch);
      }

      if (matchFoundAt === -1) {
        buffer = buffer.slice(-bufferSize);
      } else if (
        buffer.slice(matchFoundAt + toMatch.length).length >= contextAfter
      ) {
        log("Here's the match:");
        log(
          buffer.slice(
            Math.max(0, matchFoundAt - contextBefore),
            matchFoundAt + toMatch.length + contextAfter,
          ),
        );
        log("Cancelling fetch");
        reader.cancel();
        return;
      } else {
        log("Found match, but need more context…");
      }

      // keep reading
      return reader.read().then(process);
    });
  })
  .catch((err) => {
    log(
      "Something went wrong. See devtools for details. Does the response lack CORS headers?",
    );
    throw err;
  });

規範

規範
Streams
# ref-for-rs-cancel③

瀏覽器相容性

另見