WritableStream
Hinweis: Dieses Feature ist verfügbar in Web Workers.
Die WritableStream
-Schnittstelle der Streams-API bietet eine standardisierte Abstraktion zum Schreiben von Streaming-Daten an ein Ziel, das als Senke bekannt ist. Dieses Objekt bietet integrierten Gegendruck und Warteschlangentechniken.
WritableStream
ist ein übertragbares Objekt.
Konstruktor
WritableStream()
-
Erstellt ein neues
WritableStream
-Objekt.
Instanz-Eigenschaften
WritableStream.locked
Nur lesbar-
Ein boolescher Wert, der anzeigt, ob der
WritableStream
an einen Schreiber gebunden ist.
Instanz-Methoden
WritableStream.abort()
-
Bricht den Stream ab und signalisiert, dass der Produzent nicht mehr erfolgreich in den Stream schreiben kann und er sofort in einen Fehlerzustand versetzt wird, wobei alle anstehenden Schreibvorgänge verworfen werden.
WritableStream.close()
-
Schließt den Stream.
WritableStream.getWriter()
-
Gibt eine neue Instanz von
WritableStreamDefaultWriter
zurück und sperrt den Stream für diese Instanz. Solange der Stream gesperrt ist, kann kein anderer Schreiber erworben werden, bis dieser freigegeben wird.
Beispiele
Das folgende Beispiel veranschaulicht mehrere Funktionen dieser Schnittstelle. Es zeigt die Erstellung des WritableStream
mit einer benutzerdefinierten Senke und einer von der API bereitgestellten Warteschlangenstrategie. Anschließend wird eine Funktion namens sendMessage()
aufgerufen, die den neu erstellten Stream und einen String erhält. Innerhalb dieser Funktion wird die getWriter()
-Methode des Streams aufgerufen, die eine Instanz von WritableStreamDefaultWriter
zurückgibt. Ein forEach()
-Aufruf wird verwendet, um jedes Stück des Strings in den Stream zu schreiben. Schließlich geben write()
und close()
Promises zurück, die verarbeitet werden, um mit Erfolgen oder Fehlern von Stücken und Streams umzugehen.
const list = document.querySelector("ul");
function sendMessage(message, writableStream) {
// defaultWriter is of type WritableStreamDefaultWriter
const defaultWriter = writableStream.getWriter();
const encoder = new TextEncoder();
const encoded = encoder.encode(message);
encoded.forEach((chunk) => {
defaultWriter.ready
.then(() => defaultWriter.write(chunk))
.then(() => {
console.log("Chunk written to sink.");
})
.catch((err) => {
console.log("Chunk error:", err);
});
});
// Call ready again to ensure that all chunks are written
// before closing the writer.
defaultWriter.ready
.then(() => {
defaultWriter.close();
})
.then(() => {
console.log("All chunks written");
})
.catch((err) => {
console.log("Stream error:", err);
});
}
const decoder = new TextDecoder("utf-8");
const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });
let result = "";
const writableStream = new WritableStream(
{
// Implement the sink
write(chunk) {
return new Promise((resolve, reject) => {
const buffer = new ArrayBuffer(1);
const view = new Uint8Array(buffer);
view[0] = chunk;
const decoded = decoder.decode(view, { stream: true });
const listItem = document.createElement("li");
listItem.textContent = `Chunk decoded: ${decoded}`;
list.appendChild(listItem);
result += decoded;
resolve();
});
},
close() {
const listItem = document.createElement("li");
listItem.textContent = `[MESSAGE RECEIVED] ${result}`;
list.appendChild(listItem);
},
abort(err) {
console.log("Sink error:", err);
},
},
queuingStrategy,
);
sendMessage("Hello, world.", writableStream);
Den vollständigen Code finden Sie in unserem einfachen Schreibbeispiel.
Gegendruck
Aufgrund der Unterstützung von Gegendruck in der API ist dessen Implementierung im Code möglicherweise nicht offensichtlich. Um zu sehen, wie Gegendruck implementiert wird, suchen Sie nach drei Dingen:
- Die
highWaterMark
-Eigenschaft, die beim Erstellen der Zählstrategie mitnew CountQueuingStrategy
gesetzt wird, legt die maximale Menge an Daten fest, die dieWritableStream
-Instanz in einem einzigenwrite()
-Vorgang verarbeiten kann. In diesem Beispiel ist es die maximale Datenmenge, die andefaultWriter.write()
in dersendMessage
-Funktion gesendet werden kann. - Die
defaultWriter.ready
-Eigenschaft gibt ein Promise zurück, das aufgelöst wird, wenn die Senke (die erste Eigenschaft desWritableStream
-Konstruktors) mit dem Schreiben der Daten fertig ist. Die Datenquelle kann entweder mehr Daten mitdefaultWriter.write()
schreiben oderdefaultWriter.close()
aufrufen, wie im obigen Beispiel gezeigt. Zu frühes Aufrufen vonclose()
kann verhindern, dass Daten geschrieben werden. Deshalb ruft das BeispieldefaultWriter.ready
zweimal auf. - Das
Promise
, das durch diewrite()
-Methode der Senke zurückgegeben wird, gibt demWritableStream
und seinem Schreiber an, wanndefaultWriter.ready
aufgelöst werden soll.
Spezifikationen
Specification |
---|
Streams Standard # ws-class |
Browser-Kompatibilität
BCD tables only load in the browser
Siehe auch
- WHATWG Stream Visualizer, für eine grundlegende Visualisierung von lesbaren, beschreibbaren und Transform-Streams.