DasReadableStream-Interface derStreams-API repräsentiert einen lesbaren Datenstrom von Bytes. DieFetch-API bietet eine konkrete Instanz einesReadableStream über diebody-Eigenschaft einesResponse-Objekts.

ReadableStream ist einübertragbares Objekt.

Konstruktor

ReadableStream()

Erstellt und gibt ein lesbares Stream-Objekt aus den gegebenen Handlern zurück.

Instanzeigenschaften

ReadableStream.lockedSchreibgeschützt

Gibt einen Boolean-Wert zurück, der angibt, ob der lesbare Stream an einen Leser gebunden ist oder nicht.

Statische Methoden

ReadableStream.from()Experimentell

GibtReadableStream von einem bereitgestellten Iterable oder asynchronen Iterable-Objekt zurück, wie z.B. ein Array, ein Set, ein asynchroner Generator usw.

Instanzmethoden

ReadableStream.cancel()

Gibt einPromise zurück, das aufgelöst wird, wenn der Stream abgebrochen wird. Durch Aufrufen dieser Methode signalisiert ein Konsument das Desinteresse am Stream. Das übergebenereason-Argument wird an die zugrunde liegende Quelle übergeben, die es möglicherweise verwendet oder nicht.

ReadableStream.getReader()

Erstellt einen Leser und bindet den Stream an ihn. Solange der Stream gebunden ist, kann kein anderer Leser erworben werden, bis dieser freigegeben wird.

ReadableStream.pipeThrough()

Bietet eine kaskadierbare Möglichkeit, den aktuellen Stream durch einen Transform-Stream oder ein anderes schreibbares/lesbares Paar zu leiten.

ReadableStream.pipeTo()

Leitet den aktuellen ReadableStream zu einem gegebenenWritableStream und gibt einPromise zurück, das erfüllt wird, wenn der Leitungsprozess erfolgreich abgeschlossen ist, oder abgelehnt wird, wenn Fehler aufgetreten sind.

ReadableStream.tee()

Dietee-Methodetees diesen lesbaren Stream und gibt ein zwei-elementiges Array zurück, das die beiden resultierenden Verzweigungen als neueReadableStream-Instanzen enthält. Jeder dieser Streams erhält die gleichen eingehenden Daten.

Asynchrone Iteration

ReadableStream implementiert dasasynchrone Iterierprotokoll.Dies ermöglicht die asynchrone Iteration über die Chunks in einem Stream unter Verwendung derfor await...of-Syntax:

const stream = new ReadableStream(getSomeSource());for await (const chunk of stream) {  // Do something with each 'chunk'}

Der asynchrone Iterator konsumiert den Stream, bis er keine Daten mehr aufweist oder anderweitig beendet wird.Die Schleife kann aufgrund einesbreak-,throw- oderreturn-Statements auch vorzeitig beendet werden.

Während der Iteration wird der Stream gesperrt, um zu verhindern, dass andere Konsumenten einen Leser erwerben (der Versuch, über einen bereits gesperrten Stream zu iterieren, führt zu einemTypeError).Diese Sperre wird freigegeben, wenn die Schleife endet.

Standardmäßig wird der Stream auch bei Verlassen der Schleife abgebrochen, sodass er nicht mehr verwendet werden kann.Um den Stream nach dem Verlassen der Schleife weiterzuverwenden, übergeben Sie{ preventCancel: true } an dievalues()-Methode des Streams:

for await (const chunk of stream.values({ preventCancel: true })) {  // Do something with 'chunk'  break;}// Acquire a reader for the stream and continue reading ...

Beispiele

Fetch-Stream

Im folgenden Beispiel wird eine künstlicheResponse erstellt, um HTML-Fragmente, die von einer anderen Ressource abgerufen wurden, zum Browser zu streamen.

Es demonstriert die Nutzung einesReadableStream in Kombination mit einerUint8Array.

fetch("https://www.example.org")  .then((response) => response.body)  .then((rb) => {    const reader = rb.getReader();    return new ReadableStream({      start(controller) {        // The following function handles each data chunk        function push() {          // "done" is a Boolean and value a "Uint8Array"          reader.read().then(({ done, value }) => {            // If there is no more data to read            if (done) {              console.log("done", done);              controller.close();              return;            }            // Get the data and send it to the browser via the controller            controller.enqueue(value);            // Check chunks by logging to the console            console.log(done, value);            push();          });        }        push();      },    });  })  .then((stream) =>    // Respond with our stream    new Response(stream, { headers: { "Content-Type": "text/html" } }).text(),  )  .then((result) => {    // Do things with result    console.log(result);  });

Konvertieren eines Iterators oder asynchronen Iterators in einen Stream

Die statische Methodefrom() kann einen Iterator, wie z.B. eineArray oderMap, oder einen(async) iterator in einen lesbaren Stream umwandeln:

const myReadableStream = ReadableStream.from(iteratorOrAsyncIterator);

In Browsern, die diefrom()-Methode nicht unterstützen, können Sie stattdessen Ihren eigenenbenutzerdefinierten lesbaren Stream erstellen, um dasselbe Ergebnis zu erzielen:

function iteratorToStream(iterator) {  return new ReadableStream({    async pull(controller) {      const { value, done } = await iterator.next();      if (value) {        controller.enqueue(value);      }      if (done) {        controller.close();      }    },  });}

Asynchrone Iteration eines Streams mit for await...of

Dieses Beispiel zeigt, wie Sie diefetch()-Antwort mit einerfor await...of-Schleife verarbeiten können, um die eingehenden Chunks zu durchlaufen.

const response = await fetch("https://www.example.org");let total = 0;// Iterate response.body (a ReadableStream) asynchronouslyfor await (const chunk of response.body) {  // Do something with each chunk  // Here we just accumulate the size of the response.  total += chunk.length;}// Do something with the totalconsole.log(total);

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Streams API Konzepte
• Verwendung von lesbaren Streams
• Verwendung von lesbaren Byte-Streams
• Web-streams-polyfill