ReadableStream: pipeTo() Methode

Hinweis: Dieses Feature ist verfügbar in Web Workers.

Die pipeTo()-Methode der ReadableStream-Schnittstelle leitet den aktuellen ReadableStream zu einem gegebenen WritableStream und gibt ein Promise zurück, das erfüllt wird, wenn der Piping-Prozess erfolgreich abgeschlossen ist, oder abgelehnt wird, wenn Fehler aufgetreten sind.

Das Piping eines Streams wird diesen normalerweise für die Dauer des Pipe-Vorgangs sperren, wodurch verhindert wird, dass andere Lesevorgänge ihn sperren.

Syntax

js
pipeTo(destination)
pipeTo(destination, options)

Parameter

destination

Ein WritableStream, der als endgültiges Ziel für den ReadableStream dient.

options Optional

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

preventClose

Wenn dies auf true gesetzt ist, wird das Schließen des Quell-ReadableStream nicht mehr dazu führen, dass der Ziel-WritableStream geschlossen wird. Die Methode gibt ein erfülltes Promise zurück, sobald dieser Prozess abgeschlossen ist, es sei denn, es tritt ein Fehler auf, während das Ziel geschlossen wird, in diesem Fall wird es mit diesem Fehler abgelehnt.

preventAbort

Wenn dies auf true gesetzt ist, werden Fehler im Quell-ReadableStream nicht mehr dazu führen, dass der Ziel-WritableStream abgebrochen wird. Die Methode gibt ein Promise zurück, das mit dem Fehler der Quelle abgelehnt wird, oder mit jedem Fehler, der beim Abbrechen des Ziels auftritt.

preventCancel

Wenn dies auf true gesetzt ist, werden Fehler im Ziel-WritableStream nicht mehr dazu führen, dass der Quell-ReadableStream abgebrochen wird. In diesem Fall gibt die Methode ein Promise zurück, das mit dem Fehler der Quelle abgelehnt wird, oder mit jedem Fehler, der während des Abbrechens der Quelle auftritt. Außerdem, wenn der Ziel-WritableStream bereits geschlossen oder dabei ist, sich zu schließen, wird der Quell-ReadableStream nicht mehr abgebrochen. In diesem Fall gibt die Methode ein Promise zurück, das mit einem Fehler abgelehnt wird, der angibt, dass das Piping zu einem geschlossenen Stream fehlgeschlagen ist, oder mit jedem Fehler, der während des Abbrechens der Quelle auftritt.

signal

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

Rückgabewert

Ein Promise, das aufgelöst wird, wenn der Piping-Prozess abgeschlossen ist.

Ausnahmen

TypeError

Die writableStream- und/oder readableStream-Objekte sind kein Writable-Stream/Readable-Stream, oder einer oder beide der Streams sind gesperrt.

Beispiele

js
// Fetch the original image
fetch("png-logo.png")
  // Retrieve its body as ReadableStream
  .then((response) => response.body)
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => rs.pipeTo(new FinalDestinationStream()));

Dasselbe Beispiel, aber unter Verwendung von await:

js
(async () => {
  // Fetch the original image
  const response = await fetch("png-logo.png");
  // Retrieve its body as ReadableStream
  await response.body
    .pipeThrough(new PNGTransformStream())
    .pipeTo(new FinalDestinationStream());
})();

Spezifikationen

Specification
Streams Standard
# ref-for-rs-pipe-to④

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch