ReadableStreamBYOBReader

Konstruktor

ReadableStreamBYOBReader()

Erstellt eine ReadableStreamBYOBReader-Objektinstanz und gibt sie zurück.

Instanzeigenschaften

ReadableStreamBYOBReader.closed Schreibgeschützt

Gibt ein Promise zurück, das erfüllt wird, wenn der Stream geschlossen wird, oder zurückgewiesen wird, wenn im Stream ein Fehler auftritt oder die Sperre des Readers aufgehoben wird. Mit dieser Eigenschaft können Sie Code schreiben, der auf das Ende des Streaming-Vorgangs reagiert.

Instanzmethoden

ReadableStreamBYOBReader.cancel()

Gibt ein Promise zurück, das erfüllt wird, wenn der Stream abgebrochen wurde. Ein Aufruf dieser Methode signalisiert, dass ein Consumer kein Interesse mehr am Stream hat. Das übergebene Argument reason wird an die zugrunde liegende Quelle weitergegeben, die es verwenden kann, aber nicht muss.

ReadableStreamBYOBReader.read()

Übergibt eine Ansicht, in die Daten geschrieben werden müssen, und gibt ein Promise zurück, das mit dem nächsten Datenabschnitt des Streams erfüllt oder mit einem Hinweis darauf zurückgewiesen wird, dass der Stream geschlossen wurde oder ein Fehler aufgetreten ist.

ReadableStreamBYOBReader.releaseLock()

Hebt die Sperre des Readers für den Stream auf.

Beispiele

Das folgende Beispiel stammt aus den interaktiven Beispielen unter Lesbare Byte-Streams verwenden.

Erstellen Sie zunächst den Reader, indem Sie ReadableStream.getReader() für den Stream aufrufen und im Optionsparameter mode: "byob" angeben. Da es sich um einen „Bring Your Own Buffer“-Reader handelt, müssen wir außerdem einen ArrayBuffer erstellen, in den die Daten gelesen werden.

const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(200);

Im Folgenden ist eine Funktion dargestellt, die den Reader verwendet. Sie ruft die Methode read() rekursiv auf, um Daten in den Puffer zu lesen. Der Methode wird ein Uint8Array übergeben, ein Typed Array, das eine Ansicht auf den noch nicht beschriebenen Teil des ursprünglichen Array-Puffers bietet. Die Parameter der Ansicht werden anhand der Daten berechnet, die bei vorherigen Aufrufen empfangen wurden und einen Versatz innerhalb des ursprünglichen Array-Puffers bestimmen.

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);
    });
}

Wenn im Stream keine weiteren Daten vorhanden sind, wird das von der Methode read() zurückgegebene Promise mit einem Objekt erfüllt, dessen Eigenschaft done auf true gesetzt ist. Die Funktion kehrt dann zurück.

Die Eigenschaft ReadableStreamBYOBReader.closed gibt ein Promise zurück. Damit können Sie überwachen, ob der Stream geschlossen wurde, ein Fehler aufgetreten ist oder die Sperre des Readers aufgehoben wurde.

reader.closed
  .then(() => {
    // Resolved - code to handle stream closing
  })
  .catch(() => {
    // Rejected - code to handle error
  });

Um den Stream abzubrechen, rufen Sie ReadableStreamBYOBReader.cancel() auf und geben Sie optional einen Grund an. Die Methode gibt ein Promise zurück, das erfüllt wird, sobald der Stream abgebrochen wurde. Wird der Stream abgebrochen, ruft der Controller seinerseits cancel() für die zugrunde liegende Quelle auf und übergibt dabei den optionalen Grund.

Der Beispielcode unter Lesbare Byte-Streams verwenden ruft die Abbruchmethode beim Drücken einer Schaltfläche auf:

button.addEventListener("click", () => {
  reader.cancel("user choice").then(() => console.log("cancel complete"));
});

Der Consumer kann auch releaseLock() aufrufen, um die Sperre des Readers für den Stream aufzuheben, allerdings nur, wenn kein Lesevorgang aussteht:

reader.releaseLock();

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Konzepte der Streams API
• Lesbare Byte-Streams verwenden
• ReadableStream
• Web-streams-polyfill