ReadableStream: pipeThrough() Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since June 2022.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die pipeThrough() Methode der ReadableStream-Schnittstelle bietet eine kaskadierbare Möglichkeit, den aktuellen Stream durch einen Transform-Stream oder ein anderes schreibbares/lesbares Paar zu leiten.

Das Leiten eines Streams sperrt diesen in der Regel für die Dauer der Pipe, was verhindert, dass andere Leser ihn sperren können.

Syntax

js
pipeThrough(transformStream)
pipeThrough(transformStream, options)

Parameter

transformStream

Ein TransformStream (oder ein Objekt mit der Struktur {writable, readable}), bestehend aus einem lesbaren und einem schreibbaren Stream, die zusammenarbeiten, um Daten von einer Form in eine andere zu transformieren. Daten, die in den writable Stream geschrieben werden, können in einem transformierten Zustand vom readable Stream gelesen werden. Beispielsweise werden in einen TextDecoder Bytes geschrieben und Zeichenketten ausgelesen, während ein Videodecoder codierte Bytes geschrieben und unkomprimierte Videoframes ausgelesen werden.

options Optional

Die Optionen, die beim Leiten zum writable Stream verwendet werden sollen. Verfügbare Optionen sind:

preventClose

Wenn dies auf true gesetzt ist, führt das Schließen des Quellen-ReadableStream nicht mehr dazu, dass der Ziel-WritableStream geschlossen wird.

preventAbort

Wenn dies auf true gesetzt ist, führen Fehler im Quellen-ReadableStream nicht mehr dazu, dass der Ziel-WritableStream abgebrochen wird.

preventCancel

Wenn dies auf true gesetzt ist, führen Fehler im Ziel-WritableStream nicht mehr dazu, dass der Quellen-ReadableStream abgebrochen wird.

signal

Wenn auf ein AbortSignal-Objekt gesetzt, können laufende Pipe-Operationen dann über den entsprechenden AbortController abgebrochen werden.

Rückgabewert

Die readable Seite des transformStream.

Ausnahmen

TypeError

Wird ausgelöst, wenn die writable und/oder readable Eigenschaft von transformStream undefiniert sind.

Beispiele

Im folgenden Beispiel (siehe Unpack chunks of a PNG für den vollständigen, live ausgeführten Code und png-transform-stream für den Quellcode) wird ein Bild abgerufen und sein Körper als ReadableStream erfasst.

Als Nächstes protokollieren wir den Inhalt des lesbaren Streams, verwenden pipeThrough(), um ihn an eine neue Funktion zu senden, die eine grau skalierte Version des Streams erstellt, und protokollieren dann auch den neuen Stream-Inhalt.

js
// Fetch the original image
fetch("png-logo.png")
  // Retrieve its body as ReadableStream
  .then((response) => response.body)
  .then((rs) => logReadableStream("Fetch Response Stream", rs))
  // Create a gray-scaled PNG stream out of the original
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => logReadableStream("PNG Chunk Stream", rs));

Spezifikationen

Specification
Streams
# ref-for-rs-pipe-through②

Browser-Kompatibilität

Siehe auch