1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
---
title: Streams API
slug: Web/API/Streams_API
tags:
- API
- Experimental
- Landing
- NeedsTranslation
- Reference
- Streams
- TopicStub
translation_of: Web/API/Streams_API
---
<div>{{SeeCompatTable}}{{APIRef("Streams")}}</div>
<div>A API Streams permite que o JavaScript acesse programaticamente fluxos de dados recebidos pela rede e os processe conforme desejado pelo desenvolvedor.</div>
<p class="summary"></p>
<h2 id="Conceitos_e_Uso">Conceitos e Uso</h2>
<p>O streaming envolve a divisão de um recurso que você deseja receber pela rede em pequenos blocos e, em seguida, processa esses blocos aos poucos. Isso é algo que os navegadores fazem de qualquer maneira ao receber recursos para serem exibidos em páginas da web — o buffer de vídeos e mais está gradualmente disponível para reprodução, e às vezes você verá imagens sendo exibidas gradualmente conforme mais é carregado.</p>
<p>Mas isto nunca esteve disponível para JavaScript antes. Anteriormente, se quiséssemos processar um recurso de algum tipo (seja ele um vídeo, ou um arquivo de texto, etc.), Teríamos que baixar o arquivo inteiro, espera até que seja desserializado em um formato adequado, então processa todo o lote após ser totalmente recebido.</p>
<p>Com o Streams disponível para JavaScript, tudo isso muda - agora você pode começar a processar dados brutos com JavaScript bit a bit assim que estiverem disponíveis no lado do cliente, sem a necessidade de gerar um buffer, string ou blob.</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/15817/Concept.png" style="display: block; height: 382px; margin: 0px auto; width: 1000px;"></p>
<p>Também há mais vantagens - você pode detectar quando os fluxos começam ou terminam, encadeia os fluxos juntos, trata os erros e cancela os fluxos quando necessário e reage à velocidade em que o fluxo está sendo lido.</p>
<p>O uso básico de Streams gira em torno de tornar as respostas disponíveis como streams. Por exemplo, a resposta {{domxref("Body")}} retornada com sucesso de uma <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">fetch request</a> pode ser exposta como um {{domxref("ReadableStream")}}, e você pode lê-lo usando um leitor criado com {{domxref("ReadableStream.getReader()")}}, cancela-lo com {{domxref("ReadableStream.cancel()")}}, etc.</p>
<p>Usos mais complicados envolvem a criação de seu próprio fluxo usando o contrutor {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}}, por exemplo para processar dados dentro de um <a href="/en-US/docs/Web/API/Service_Worker_API">service worker</a>.</p>
<p>Você também pode gravar dados em streams usando {{domxref("WritableStream")}}.</p>
<div class="note">
<p><strong>Note</strong>: Você pode encontrar muito mais detalhes sobre a teoria e prática de streams em nossos artigos — <a href="/en-US/docs/Web/API/Streams_API/Concepts">Streams API concepts</a>, <a href="/en-US/docs/Web/API/Streams_API/Using_readable_streams">Using readable streams</a>, e <a href="/en-US/docs/Web/API/Streams_API/Using_writable_streams">Using writable streams</a>.</p>
</div>
<h2 id="Stream_interfaces">Stream interfaces</h2>
<h3 id="Readable_streams">Readable streams</h3>
<dl>
<dt>{{domxref("ReadableStream")}}</dt>
<dd>Represents a readable stream of data. It can be used to handle response streams of the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>, or developer-defined streams (e.g. a custom {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} constructor).</dd>
<dt>{{domxref("ReadableStreamDefaultReader")}}</dt>
<dd>Represents a default reader that can be used to read stream data supplied from a network (e.g. a fetch request).</dd>
<dt>{{domxref("ReadableStreamDefaultController")}}</dt>
<dd>Represents a controller allowing control of a {{domxref("ReadableStream")}}'s state and internal queue. Default controllers are for streams that are not byte streams.</dd>
</dl>
<h3 id="Writable_streams">Writable streams</h3>
<dl>
<dt>{{domxref("WritableStream")}}</dt>
<dd>Provides a standard abstraction for writing streaming data to a destination, known as a sink. This object comes with built-in backpressure and queuing.</dd>
<dt>{{domxref("WritableStreamDefaultWriter")}}</dt>
<dd>Represents a default writable stream writer that can be used to write chunks of data to a writable stream.</dd>
<dt>{{domxref("WritableStreamDefaultController")}}</dt>
<dd>Represents a controller allowing control of a {{domxref("WritableStream")}}'s state. When constructing a <code>WritableStream</code>, the underlying sink is given a corresponding <code>WritableStreamDefaultController</code> instance to manipulate.</dd>
</dl>
<h3 id="Related_stream_APIs_and_operations">Related stream APIs and operations</h3>
<dl>
<dt>{{domxref("ByteLengthQueuingStrategy")}}</dt>
<dd>Provides a built-in byte length queuing strategy that can be used when constructing streams.</dd>
<dt>{{domxref("CountQueuingStrategy")}}</dt>
<dd>Provides a built-in chunk counting queuing strategy that can be used when constructing streams.</dd>
</dl>
<h3 id="Extensions_to_other_APIs">Extensions to other APIs</h3>
<dl>
<dt>{{domxref("Request")}}</dt>
<dd>When a new <code>Request</code> object is constructed, you can pass it a {{domxref("ReadableStream")}} in the <code>body</code> property of its <code>RequestInit</code> dictionary. This <code>Request</code> could then be passed to a {{domxref("WindowOrWorkerGlobalScope.fetch()")}} to commence fetching the stream.</dd>
<dt>{{domxref("Body")}}</dt>
<dd>The response {{domxref("Body")}} returned by a successful <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">fetch request</a> is exposed by default as a {{domxref("ReadableStream")}}, and can have a reader attached to it, etc.</dd>
</dl>
<h3 id="ByteStream-related_interfaces">ByteStream-related interfaces</h3>
<div class="warning">
<p><strong>Important</strong>: these are not implemented anywhere as yet, and questions have been raised as to whether the spec details are in a finished enough state for them to be implemented. This may change over time.</p>
</div>
<dl>
<dt>{{domxref("ReadableStreamBYOBReader")}}</dt>
<dd>Represents a BYOB ("bring your own buffer") reader that can be used to read stream data supplied by the developer (e.g. a custom {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} constructor).</dd>
<dt>{{domxref("ReadableByteStreamController")}}</dt>
<dd>Represents a controller allowing control of a {{domxref("ReadableStream")}}'s state and internal queue. Byte stream controllers are for byte streams.</dd>
<dt>{{domxref("ReadableStreamBYOBRequest")}}</dt>
<dd>Represents a pull into request in a {{domxref("ReadableByteStreamController")}}.</dd>
</dl>
<h2 id="Examples">Examples</h2>
<p>We have created a directory of examples to go along with the Streams API documentation — see <a href="https://github.com/mdn/dom-examples/tree/master/streams">mdn/dom-examples/streams</a>. The examples are as follows:</p>
<ul>
<li><a href="http://mdn.github.io/dom-examples/streams/simple-pump/">Simple stream pump</a>: This example shows how to consume a ReadableStream and pass its data to another.</li>
<li><a href="http://mdn.github.io/dom-examples/streams/grayscale-png/">Grayscale a PNG</a>: This example shows how a ReadableStream of a PNG can be turned into grayscale.</li>
<li><a href="http://mdn.github.io/dom-examples/streams/simple-random-stream/">Simple random stream</a>: This example shows how to use a custom stream to generate random strings, enqueue them as chunks, and then read them back out again.</li>
<li><a href="http://mdn.github.io/dom-examples/streams/simple-tee-example/">Simple tee example</a>: This example extends the Simple random stream example, showing how a stream can be teed and both resulting streams can be read independently.</li>
<li><a href="http://mdn.github.io/dom-examples/streams/simple-writer/">Simple writer</a>: This example shows how to to write to a writable stream, then decode the stream and write the contents to the UI.</li>
<li><a href="http://mdn.github.io/dom-examples/streams/png-transform-stream/">Unpack chunks of a PNG</a>: This example shows how <a href="https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/pipeThrough"><code>pipeThrough()</code></a> can be used to transform a ReadableStream into a stream of other data types by transforming a data of a PNG file into a stream of PNG chunks.</li>
</ul>
<p>Examples from other developers:</p>
<ul>
<li><a href="https://fetch-progress.anthum.com/">Progress Indicators with Streams, Service Workers, & Fetch</a>.</li>
</ul>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('Streams')}}</td>
<td>{{Spec2('Streams')}}</td>
<td>Initial definition.</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div class="hidden">
<p>The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p>
</div>
<h3 id="WritableStream">WritableStream</h3>
<p>{{Compat("api.WritableStream")}}</p>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/API/Streams_API/Concepts">Streams API concepts</a></li>
<li><a href="/en-US/docs/Web/API/Streams_API/Using_readable_streams">Using readable streams</a></li>
<li><a href="/en-US/docs/Web/API/Streams_API/Using_writable_streams">Using writable streams</a></li>
</ul>
|
