diff options
Diffstat (limited to 'files/ja/web/api/streams_api')
| -rw-r--r-- | files/ja/web/api/streams_api/concepts/index.html | 119 | ||||
| -rw-r--r-- | files/ja/web/api/streams_api/index.html | 154 | ||||
| -rw-r--r-- | files/ja/web/api/streams_api/using_readable_streams/index.html | 317 | ||||
| -rw-r--r-- | files/ja/web/api/streams_api/using_writable_streams/index.html | 170 |
4 files changed, 760 insertions, 0 deletions
diff --git a/files/ja/web/api/streams_api/concepts/index.html b/files/ja/web/api/streams_api/concepts/index.html new file mode 100644 index 0000000000..719c2f21a8 --- /dev/null +++ b/files/ja/web/api/streams_api/concepts/index.html @@ -0,0 +1,119 @@ +--- +title: Streams API の概念 +slug: Web/API/Streams_API/Concepts +tags: + - API + - Streams + - concepts +translation_of: Web/API/Streams_API/Concepts +--- +<div>{{apiref("Streams")}}</div> + +<p class="summary"><span class="seoSummary"><a href="/ja/docs/Web/API/Streams_API">Streams API</a> は、非常に便利なツールセットを Web プラットフォームに追加し、JavaScript がネットワーク経由で受信したデータのストリームにプログラムでアクセスし、開発者の希望どおりに処理できるようにするオブジェクトを提供します。 ストリームに関連する概念と用語の一部は、初めての場合もあります。 この記事では、それら知っておく必要のあるすべてを説明します。</span></p> + +<h2 id="Readable_streams" name="Readable_streams">読み取り可能なストリーム</h2> + +<p>読み取り可能なストリームは、<strong>基になるソース</strong>（underlying source）から流れる {{domxref("ReadableStream")}} オブジェクトによって JavaScript で表されるデータソースです。 基になるソースは、ネットワーク上のどこか、またはデータを取得するドメインのどこかにあるリソースです。</p> + +<p>基になるソースには、次の2つのタイプがあります。</p> + +<ul> + <li><strong>プッシュソース</strong>（Push sources）は、アクセスしたときに常にデータをプッシュします。 ストリームへのアクセスを開始、一時停止、またはキャンセルするのはユーザー次第です。 例には、動画ストリームや TCP/<a href="/ja/docs/Web/API/WebSockets_API">Web ソケット</a>が含まれます。</li> + <li><strong>プルソース</strong>（Pull sources）では、接続後、明示的にデータを要求する必要があります。 例には、<a href="/ja/docs/Web/API/Fetch_API">Fetch</a> や <a href="/ja/docs/Web/API/XMLHttpRequest/XMLHttpRequest">XHR</a> の呼び出しを介したファイルアクセス操作が含まれます。</li> +</ul> + +<p>データは、<strong>チャンク</strong>（chunks）と呼ばれる小さな断片で順番に読み取られます。 チャンクは1バイトにすることも、特定のサイズの<a href="/ja/docs/Web/JavaScript/Typed_arrays">型付き配列</a>など、より大きなものにすることもできます。 単一のストリームには、さまざまなサイズとタイプのチャンクを含めることができます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15819/Readable%20streams.png" style="height: 452px; width: 1000px;"></p> + +<p>ストリームに置かれたチャンクは、<strong>キューに入れられた</strong>（enqueued）と言われます。 これは、読み取りの準備ができているキューで待機していることを意味します。 <strong>内部キュー</strong>（internal queue）は、まだ読み取られていないチャンクを追跡します（下の内部キューとキューイング戦略のセクションを参照）。</p> + +<p>ストリーム内のチャンクは<strong>リーダー</strong>（reader）によって読み取られます。 これにより、一度に1つのチャンクでデータが処理されるため、ユーザーは任意の種類の操作を実行できます。 リーダーとそれに付随する他の処理コードは、<strong>コンシューマー</strong>（consumer）と呼ばれます。</p> + +<p>また、<strong>コントローラー</strong>（controller）と呼ばれる構造も使用します。 各リーダーには、ストリームを制御する（例えば、必要に応じてキャンセルする）ことができるコントローラーが関連付けられています 。</p> + +<p>一度にストリームを読み取ることができるのは1つのリーダーのみです。 リーダーが作成され、ストリームの読み取りを開始すると、ストリームは<strong>アクティブなリーダー</strong>（active reader）に<strong>ロックされている</strong>（locked）と言います。 別のリーダーにストリームの読み取りを開始させる場合は、通常、最初のリーダーをキャンセルしてから他の操作を行う必要があります（ですが、ストリームを <strong>tee</strong> することができます。下のティーイングのセクションを参照）。</p> + +<p>読み取り可能なストリームには2つの異なるタイプがあることに注意してください。 従来の読み取り可能なストリームに加えて、バイトストリームと呼ばれるタイプがあります。 これは、基になるバイトソース（BYOB または bring your own buffer（独自のバッファーを持ち込む）とも呼ばれる）のソースを読み取るための従来のストリームの拡張バージョンです。 これにより、開発者が提供するバッファにストリームを直接読み込むことができ、必要なコピーが最小限に抑えられます。 コードが使用する基になるストリーム（そして拡張により、リーダーとコントローラー）は、最初にストリームがどのように作成されたかによって異なります（{{domxref("ReadableStream.ReadableStream","ReadableStream()")}} コンストラクターのページを参照）。</p> + +<div class="warning"> +<p><strong>重要</strong>: バイトストリームは、まだどこにも実装されていません。 仕様の詳細が実装に十分な完成状態にあるかどうかについて疑問が提起されています。 これは時間とともに変化する可能性があります。</p> +</div> + +<p>フェッチ要求からの {{domxref("Response.body")}} などのメカニズムを介して既製の読み取り可能なストリームを使用するか、{{domxref("ReadableStream.ReadableStream","ReadableStream()")}} コンストラクターを使用して独自のストリームを使用できます。</p> + +<h2 id="Teeing" name="Teeing">ティーイング</h2> + +<p>一度にストリームを読み取ることができるのは1つのリーダーだけですが、ストリームを2つの同一のコピーに分割し、2つの別々のリーダーで読み取ることができます。 これを<strong>ティーイング</strong>（teeing）と呼びます。</p> + +<p>JavaScript では、これを {{domxref("ReadableStream.tee()")}} メソッドを介して実現します — 元の読み取り可能なストリームの2つの同一コピーを含む配列を出力し、2つの別々のリーダーで個別に読み取ることができます。</p> + +<p>例えば、サーバーから応答を取得してブラウザーにストリームしたいが、<a href="/ja/docs/Web/API/Service_Worker_API">ServiceWorker</a> キャッシュにもストリームしたい場合に、ServiceWorker でこれを行うことができます。 応答のボディを複数回使用することはできず、ストリームを一度に複数のリーダーで読み取ることはできないため、これを行うには2つのコピーが必要です。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15820/tee.png" style="height: 527px; width: 1000px;"></p> + +<h2 id="Writable_streams" name="Writable_streams">書き込み可能なストリーム</h2> + +<p><strong>書き込み可能なストリーム</strong>（writable stream）は、{{domxref("WritableStream")}} オブジェクトによって JavaScript で表されるデータの書き込み先です。 これは、<strong>基になるシンク</strong>（underlying sink、生データが書き込まれる下位レベルの I/O シンク）の上部の抽象化として機能します。</p> + +<p>データは、<strong>ライター</strong>（writer）を介して一度に1つのチャンクでストリームに書き込まれます。 チャンクは、リーダーのチャンクと同様に、多数の形式をとることができます。 任意のコードを使用して、書き込み可能なチャンクを生成できます。 ライターとそれに関連するコードを<strong>プロデューサー</strong>（producer）と呼びます。</p> + +<p>ライターが作成され、ストリームへの書き込みを開始すると、ストリームは<strong>アクティブなライター</strong>（active writer）に<strong>ロックされている</strong>（locked）と言われます。 一度に書き込み可能なストリームに書き込むことができるのは、1つのライターのみです。 別のライターにストリームへの書き込みを開始させたい場合は、通常、別のライターを取りつける前にそれを中止する必要があります。</p> + +<p><strong>内部キュー</strong>（internal queue）は、ストリームに書き込まれたが、基になるシンクによってまだ処理されていないチャンクを追跡します。</p> + +<p>また、コントローラーと呼ばれる構造も使用します。 各ライターには、ストリームを制御する（例えば、必要に応じてストリームを中止する）ことができるコントローラーが関連付けられています 。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15821/writable%20streams.png" style="height: 452px; width: 1000px;"></p> + +<p>{{domxref("WritableStream.WritableStream","WritableStream()")}} コンストラクターを使用して、書き込み可能なストリームを利用できます。 現在、これらのブラウザーでの可用性は非常に限られています。</p> + +<h2 id="Pipe_chains" name="Pipe_chains">パイプチェーン</h2> + +<p>Streams API を使用すると、<strong>パイプチェーン</strong>（pipe chain）と呼ばれる構造を使用して、ストリームを相互にパイプすることができます（または、少なくともブラウザーが関連機能を実装する場合はそうなります）。 これを容易にするために、仕様には次の2つのメソッドがあります。</p> + +<ul> + <li>{{domxref("ReadableStream.pipeThrough()")}} — <strong>変換ストリーム</strong>（transform stream）を介してストリームをパイプします。 変換ストリームは、データが書き込まれる書き込み可能なストリームと、データが読み取られる読み取り可能なストリームで構成されるペアです。 これは、データを常に取り込み、新しい状態に変換する一種のトレッドミルとして機能します。 事実上、同じストリームに書き込まれ、同じ値が読み取られます。 簡単な例は、生のバイトが書き込まれ、次に文字列が読み取られるテキストデコーダーです。 仕様には、より有用なアイデアと例があります。 アイデアについては、<a href="https://streams.spec.whatwg.org/#ts-model">ストリームの変換</a>（英語）と、<a href="https://streams.spec.whatwg.org/#example-both">この Web ソケットの例</a>（英語）を参照してください。</li> + <li>{{domxref("ReadableStream.pipeTo()")}} — パイプチェーンの終点として機能する書き込み可能なストリームにパイプします。</li> +</ul> + +<p>パイプチェーンの始まりは<strong>元のソース</strong>（original source）と呼ばれ、終わりは<strong>最終的なシンク</strong>（ultimate sink）と呼ばれます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15818/PipeChain.png" style="height: 382px; width: 1000px;"></p> + +<div class="note"> +<p><strong>注</strong>: この機能はまだ十分に検討されておらず、多くのブラウザーでは利用できません。 ある時点で、仕様作成者は、<code>TransformStream</code> クラスのようなものを追加して、変換ストリームの作成を容易にすることを望んでいます。</p> +</div> + +<h2 id="Backpressure" name="Backpressure">バックプレッシャー</h2> + +<p>ストリームの重要な概念は<strong>バックプレッシャー</strong>（backpressure）です。 これは、単一のストリームまたはパイプチェーンが読み取り/書き込みの速度を調整するプロセスです。 チェーンの後半のストリームがまだビジーで、さらに多くのチャンクを受け入れる準備ができていない場合、チェーンを介して信号を逆方向に送信して、より前の変換ストリーム（または元のソース）に必要に応じて配信速度を落とすよう指示し、どこもボトルネックにならないようにします。</p> + +<p><code>ReadableStream</code> でバックプレッシャーを使用するには、コントローラーの {{domxref("ReadableStreamDefaultController.desiredSize")}} プロパティを照会することで、コンシューマーが希望するチャンクサイズをコントローラーに問い合わせます。 それが低すぎる場合、<code>ReadableStream</code> は、基になるソースにデータの送信を停止するように指示でき、ストリームチェーンに沿ってバックプレッシャーをかけます。</p> + +<p>後でコンシューマが再びデータを受信したい場合は、ストリームの作成で <code>pull</code> メソッドを使用して、データをストリームに与えるよう基になるソースに指示できます。</p> + +<h2 id="Internal_queues_and_queuing_strategies" name="Internal_queues_and_queuing_strategies">内部キューとキューイング戦略</h2> + +<p>前に述べたように、まだ処理されて終了していないストリーム内のチャンクは、内部キューによって追跡されます。</p> + +<ul> + <li>読み取り可能なストリームの場合、これらはキューに入れられたがまだ読み取られていないチャンクです。</li> + <li>書き込み可能なストリームの場合、これらは書き込まれたが、基になるシンクによってまだ処理されていないチャンクです。</li> +</ul> + +<p>内部キューは、<strong>内部キューの状態</strong>（internal queue state）に基づいてバックプレッシャーを通知する方法を決定する<strong>キューイング戦略</strong>（queuing strategy）を採用しています。</p> + +<p>一般に、この戦略では、キュー内のチャンクのサイズを<strong>最高水準点</strong>（high water mark）と呼ばれる値と比較します。これは、キューが現実的に管理できる最大の合計チャンクサイズです。</p> + +<p>実行される計算は次です。</p> + +<pre>最高水準点 - キュー内のチャンクの合計サイズ = 希望サイズ</pre> + +<p><strong>希望サイズ</strong>（desired size）は、ストリームの流れを維持するためにストリームが受け入れることができるチャンクのサイズですが、サイズは最高水準点未満です。 計算が実行された後、希望サイズをゼロより大きく保ちながら、ストリームの流れを可能な限り高速に保つために、必要に応じてチャンク生成が減速/高速化されます。 値がゼロ（書き込み可能なストリームの場合はそれ以下）になった場合、ストリームが処理できるよりも速くチャンクが生成されていることを意味し、問題が発生します。</p> + +<div class="note"> +<p><strong>注</strong>: ゼロまたは負の希望サイズの場合に何が起こるかは、これまで仕様で実際に定義されていません。 忍耐は美徳なり。</p> +</div> + +<p>例として、1のチャンクサイズと3の最高水準点を考えてみましょう。 これは、最高水準点に到達してバックプレッシャーが適用される前に、最大3つのチャンクをキューに入れることができることを意味します。</p> diff --git a/files/ja/web/api/streams_api/index.html b/files/ja/web/api/streams_api/index.html new file mode 100644 index 0000000000..8813eb96b1 --- /dev/null +++ b/files/ja/web/api/streams_api/index.html @@ -0,0 +1,154 @@ +--- +title: Streams API +slug: Web/API/Streams_API +tags: + - API + - Experimental + - JavaScript + - Landing + - Reference + - Streams +translation_of: Web/API/Streams_API +--- +<p>{{SeeCompatTable}}{{DefaultAPISidebar("Streams")}}</p> + +<div> +<p><span class="seoSummary">Streams API を使用すると、JavaScript がネットワーク経由で受信したデータのストリームにプログラムでアクセスし、開発者の希望どおりに処理できます。</span></p> +</div> + +<h2 id="Concepts_and_usage" name="Concepts_and_usage">概念と使用方法</h2> + +<p>ストリーミングでは、ネットワーク経由で受信するリソースを小さなチャンクに分割し、少しずつ処理します。 これは、ブラウザーがウェブページに表示されるアセットを受信するときにとにかく行うことです — 動画がバッファされて徐々に再生可能になり、画像が読み込まれるにつれて徐々に表示されることもあります。</p> + +<p>しかし、これはこれまで JavaScript で利用できたことはありません。 以前は、何らかの種類のリソース（動画、テキストファイルなど）を処理したい場合は、ファイル全体をダウンロードし、適切な形式にデシリアライズされるのを待ってから、完全に受信した後に全部まとめて処理する必要がありました。</p> + +<p>Streams が JavaScript で利用できるようになったことで、これがすべて変わりました — クライアント側で利用可能になると、バッファ、文字列、または blob を生成せずに、JavaScript で少しずつ生データの処理を開始できます。</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>さらに利点もあります。 ストリームの開始または終了の検出、ストリームの連鎖、エラー処理と必要に応じたストリームのキャンセル、ストリームの読み取り速度への対応が可能です。</p> + +<p>Streams の基本的な使用法は、応答をストリームとして利用可能にすることにかかっています。 例えば、成功した<a href="/ja/docs/Web/API/WindowOrWorkerGlobalScope/fetch">フェッチ要求</a>によって返された応答の {{domxref("Body")}} は、{{domxref("ReadableStream")}} として公開できます。 その後、{{domxref("ReadableStream.getReader()")}} で作成したリーダーを使用して読み取り、{{domxref("ReadableStream.cancel()")}} でキャンセルできます。</p> + +<p>より複雑な用途では、例えば<a href="/ja/docs/Web/API/Service_Worker_API">サービスワーカー</a>内でデータを処理するために、{{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} コンストラクターを使用して独自のストリームを作成します。</p> + +<p>{{domxref("WritableStream")}} を使用してストリームにデータを書き込むこともできます。</p> + +<div class="note"> +<p><strong>注</strong>: ストリームの理論と実践の詳細については、<a href="/ja/docs/Web/API/Streams_API/Concepts">Streams API の概念</a>、<a href="/ja/docs/Web/API/Streams_API/Using_readable_streams">読み取り可能なストリームの使用</a>、<a href="/ja/docs/Web/API/Streams_API/Using_writable_streams">書き込み可能なストリームの使用</a>の記事をご覧ください。</p> +</div> + +<h2 id="Stream_interfaces" name="Stream_interfaces">ストリームのインターフェイス</h2> + +<h3 id="Readable_streams" name="Readable_streams">読み取り可能なストリーム</h3> + +<dl> + <dt>{{domxref("ReadableStream")}}</dt> + <dd>読み取り可能なデータのストリームを表します。 <a href="/ja/docs/Web/API/Fetch_API">Fetch API</a> の応答ストリーム、または開発者定義のストリーム（カスタムの {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} コンストラクターなど）を処理するために使用できます。</dd> + <dt>{{domxref("ReadableStreamDefaultReader")}}</dt> + <dd>ネットワークから提供されたストリームデータ（フェッチ要求など）を読み取るために使用できるデフォルトのリーダーを表します。</dd> + <dt>{{domxref("ReadableStreamDefaultController")}}</dt> + <dd>{{domxref("ReadableStream")}} の状態と内部キューの制御を許可するコントローラーを表します。 デフォルトのコントローラーは、バイトストリームではないストリーム用です。</dd> +</dl> + +<h3 id="Writable_streams" name="Writable_streams">書き込み可能なストリーム</h3> + +<dl> + <dt>{{domxref("WritableStream")}}</dt> + <dd>シンク（sink）と呼ばれる宛先にストリーミングデータを書き込むための標準的な抽象化を提供します。 このオブジェクトには、組み込みのバックプレッシャー（受信側のバッファあふれの予防）とキューイングが付属しています。</dd> + <dt>{{domxref("WritableStreamDefaultWriter")}}</dt> + <dd>データのチャンクを書き込み可能なストリームに書き込むために使用できるデフォルトの書き込み可能なストリームのライターを表します。</dd> + <dt>{{domxref("WritableStreamDefaultController")}}</dt> + <dd>{{domxref("WritableStream")}} の状態の制御を許可するコントローラーを表します。 <code>WritableStream</code> を構築するとき、基になるシンクには、対応する <code>WritableStreamDefaultController</code> インスタンスが与えられて操作します。</dd> +</dl> + +<h3 id="Related_stream_APIs_and_operations" name="Related_stream_APIs_and_operations">関連するストリームの API と操作</h3> + +<dl> + <dt>{{domxref("ByteLengthQueuingStrategy")}}</dt> + <dd>ストリームを構築するときに使用できる組み込みのバイト長キューイング戦略（byte length queuing strategy）を提供します。</dd> + <dt>{{domxref("CountQueuingStrategy")}}</dt> + <dd>ストリームを構築するときに使用できる組み込みのチャンクカウントキューイング戦略（chunk counting queuing strategy）を提供します。</dd> +</dl> + +<h3 id="Extensions_to_other_APIs" name="Extensions_to_other_APIs">他の API の拡張</h3> + +<dl> + <dt>{{domxref("Request")}}</dt> + <dd>新しい <code>Request</code> オブジェクトが構築されると、その <code>RequestInit</code> ディクショナリの <code>body</code> プロパティで {{domxref("ReadableStream")}} を渡すことができます。 次に、この <code>Request</code> を {{domxref("WindowOrWorkerGlobalScope.fetch()")}} に渡して、ストリームのフェッチを開始できます。</dd> + <dt>{{domxref("Body")}}</dt> + <dd>成功した<a href="/ja/docs/Web/API/WindowOrWorkerGlobalScope/fetch">フェッチ要求</a>によって返された応答の {{domxref("Body")}} は、デフォルトで {{domxref("ReadableStream")}} として公開され、リーダーを取りつけることができます。</dd> +</dl> + +<h3 id="ByteStream-related_interfaces" name="ByteStream-related_interfaces">ByteStream 関連のインターフェイス</h3> + +<div class="warning"> +<p><strong>重要</strong>: これらはまだどこにも実装されておらず、仕様の詳細が実装に十分な完成状態にあるかどうかについて疑問が提起されています。 これは時間とともに変化する可能性があります。</p> +</div> + +<dl> + <dt>{{domxref("ReadableStreamBYOBReader")}}</dt> + <dd>開発者が提供するストリームデータの読み取りに使用できる BYOB（bring your own buffer、独自のバッファを持ち込む）リーダーを表します（カスタムの {{domxref("ReadableStream.ReadableStream", "ReadableStream()")}} コンストラクターなど）。</dd> + <dt>{{domxref("ReadableByteStreamController")}}</dt> + <dd>{{domxref("ReadableStream")}} の状態と内部キューの制御を許可するコントローラーを表します。 バイトストリームコントローラーは、バイトストリーム用です。</dd> + <dt>{{domxref("ReadableStreamBYOBRequest")}}</dt> + <dd>{{domxref("ReadableByteStreamController")}} 内のプルインリクエストを表します。</dd> +</dl> + +<h2 id="Examples" name="Examples">例</h2> + +<p>Streams API のドキュメントに合わせてサンプルのディレクトリを作成しました。 <a href="https://github.com/mdn/dom-examples/tree/master/streams">mdn/dom-examples/streams</a> を参照してください。 例は次のとおりです。</p> + +<ul> + <li><a href="http://mdn.github.io/dom-examples/streams/simple-pump/">Simple stream pump</a>（単純なストリームポンプ）: この例は、<code>ReadableStream</code> を使用してそのデータを別のストリームに渡す方法を示しています。</li> + <li><a href="http://mdn.github.io/dom-examples/streams/grayscale-png/">Grayscale a PNG</a>（PNG のグレースケール化）: この例は、PNG の <code>ReadableStream</code> をグレースケールに変換する方法を示しています。</li> + <li><a href="http://mdn.github.io/dom-examples/streams/simple-random-stream/">Simple random stream</a>（単純なランダムストリーム）: この例は、カスタムストリームを使用してランダムな文字列を生成し、それらをチャンクとしてキューに入れてから、再度読み取る方法を示しています。</li> + <li><a href="http://mdn.github.io/dom-examples/streams/simple-tee-example/">Simple tee example</a>（単純な tee の例）: この例は、単純なランダムストリームの例を拡張したもので、ストリームを tee 化して、両方の結果のストリームの独立して読み取る方法を示しています。</li> + <li><a href="http://mdn.github.io/dom-examples/streams/simple-writer/">Simple writer</a>（単純なライター）: この例では、書き込み可能なストリームに書き込み、ストリームをデコードして、コンテンツを UI に書き込む方法を示します。</li> + <li><a href="http://mdn.github.io/dom-examples/streams/png-transform-stream/">Unpack chunks of a PNG</a>（PNG のチャンクをアンパックする）: この例は、PNG ファイルのデータを PNG チャンクのストリームに変換することにより、{{domxref("ReadableStream.pipeThrough","pipeThrough()")}} を使用して <code>ReadableStream</code> を他のデータ型のストリームに変換する方法を示します。</li> +</ul> + +<p>他の開発者による例</p> + +<ul> + <li><a href="https://fetch-progress.anthum.com/">Streams、Service Worker、および Fetch を含む進行状況インジケーター</a>（英語）。</li> +</ul> + +<h2 id="Specifications" name="Specifications">仕様書</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">仕様書</th> + <th scope="col">状態</th> + <th scope="col">備考</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName('Streams')}}</td> + <td>{{Spec2('Streams')}}</td> + <td>初回定義</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h2> + +<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、 <a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div> + +<h3 id="ReadableStream" name="ReadableStream">ReadableStream</h3> + +<p>{{Compat("api.ReadableStream")}}</p> + +<h3 id="WritableStream" name="WritableStream">WritableStream</h3> + +<p>{{Compat("api.WritableStream")}}</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="/ja/docs/Web/API/Streams_API/Concepts">Streams API の概念</a></li> + <li><a href="/ja/docs/Web/API/Streams_API/Using_readable_streams">読み取り可能なストリームの使用</a></li> + <li><a href="/ja/docs/Web/API/Streams_API/Using_writable_streams">書き込み可能なストリームの使用</a></li> +</ul> diff --git a/files/ja/web/api/streams_api/using_readable_streams/index.html b/files/ja/web/api/streams_api/using_readable_streams/index.html new file mode 100644 index 0000000000..fb991e50b6 --- /dev/null +++ b/files/ja/web/api/streams_api/using_readable_streams/index.html @@ -0,0 +1,317 @@ +--- +title: 読み取り可能なストリームの使用 +slug: Web/API/Streams_API/Using_readable_streams +tags: + - API + - Controller + - Fetch + - Guide + - ReadableStreams + - Streams + - pipe chains + - readable streams + - reader + - tee +translation_of: Web/API/Streams_API/Using_readable_streams +--- +<div>{{apiref("Streams")}}</div> + +<p class="summary"><span class="seoSummary">JavaScript 開発者として、ネットワークを介して受信したデータのストリームをチャンクごとにプログラムで読み取り、操作することは非常に便利です！ しかし、Streams API の読み取り可能なストリームの機能はどのように使用するのでしょうか？ この記事では、その基本について説明します。</span></p> + +<div class="note"> +<p><strong>注</strong>: この記事は、読者が読み取り可能なストリームのユースケースを理解し、高レベルの概念を理解していることを前提としています。 そうでない場合は、まず <a href="/ja/docs/Web/API/Streams_API#Concepts_and_usage">Streams の概念と使用方法の概要</a>と専用の <a href="/ja/docs/Web/API/Streams_API/Concepts">Streams API の概念</a>の記事を読んでから、戻ってくることをお勧めします。</p> +</div> + +<div class="note"> +<p><strong>注</strong>: 書き込み可能なストリームに関する情報を探している場合は、代わりに<a href="/ja/docs/Web/API/Streams_API/Using_writable_streams">書き込み可能なストリームの使用</a>を試してください。</p> +</div> + +<h2 id="Browser_support" name="Browser_support">ブラウザーのサポート</h2> + +<p>Firefox 65 以降および Chrome 42 以降（および同等の Chromium ベースのブラウザー）で、Fetch の {{domxref("Body")}} オブジェクトをストリームとして消費し、独自のカスタムの読み取り可能なストリームを作成できます。 <a href="/ja/docs/Web/API/Streams_API/Concepts#Pipe_chains">パイプチェーン</a>は現在 Chrome でのみサポートされており、その機能は変更される可能性があります。</p> + +<h2 id="Finding_some_examples" name="Finding_some_examples">いくつかの例を見つける</h2> + +<p>この記事では、<a href="https://github.com/mdn/dom-examples/tree/master/streams">dom-examples/streams</a> リポジトリから取得したさまざまな例を見ていきます。 そこには完全なソースコードと例へのリンクがあります。</p> + +<h2 id="Consuming_a_fetch_as_a_stream" name="Consuming_a_fetch_as_a_stream">フェッチをストリームとして消費する</h2> + +<p><a href="/ja/docs/Web/API/Fetch_API">Fetch API</a> を使用すると、ネットワーク経由でリソースをフェッチでき、<a href="/ja/docs/Web/API/XMLHttpRequest">XHR</a> の最新の代替手段が提供されます。 これには多くの利点がありますが、本当に素晴らしいのは、ブラウザーがフェッチの応答を読み取り可能なストリームとして消費する機能を最近追加したことです。</p> + +<p>{{domxref("Body")}} ミックスインには {{domxref("Body.body","body")}} プロパティが含まれるようになりました。 これは、ボディの内容を読み取り可能なストリームとして公開する単純なゲッターです。 このミックスインは、{{domxref("Request")}}（要求）インターフェイスと {{domxref("Response")}}（応答）インターフェイスの両方で実装されているため、両方で使用できますが、応答のボディのストリームを消費するであろうことはちょっとだけ明白です。</p> + +<p>単純なストリームポンプ（<a href="https://github.com/mdn/dom-examples/tree/master/streams/simple-pump">Simple stream pump</a>）の例が示しているように（<a href="https://mdn.github.io/dom-examples/streams/simple-pump/">ライブも参照</a>）、それを公開することは、次のように応答の <code>body</code> プロパティにアクセスするだけのことです。</p> + +<pre class="brush: js">// 元の画像をフェッチ +fetch('./tortoise.png') +// その body を ReadableStream として取得 +.then(response => response.body)</pre> + +<p>これにより、{{domxref("ReadableStream")}} オブジェクトが提供されます。</p> + +<h3 id="Attaching_a_reader" name="Attaching_a_reader">リーダーの取り付け</h3> + +<p>ストリームするボディができました。 ストリームを読むには、リーダーを取り付ける必要があります。 これは、{{domxref("ReadableStream.getReader()")}} メソッドを使用して行われます。</p> + +<pre class="brush: js">// 元の画像をフェッチ +fetch('./tortoise.png') +// その body を ReadableStream として取得 +.then(response => response.body) +.then(body => { + const reader = body.getReader();</pre> + +<p>このメソッドを呼び出すと、リーダーが作成され、ストリームにロックされます — このリーダーが開放されるまで、他のリーダーはこのストリームを読み取ることができません。 開放するには、例えば {{domxref("ReadableStreamDefaultReader.releaseLock()")}} を呼び出します。</p> + +<p>また、<code>response.body</code> は同期的であり、promise を必要としないため、前の例を1ステップ減らすことができることに注意してください。</p> + +<pre class="brush: js">// 元の画像をフェッチ + fetch('./tortoise.png') + // その body を ReadableStream として取得 + .then(response => { + const reader = response.body.getReader();</pre> + +<h3 id="Reading_the_stream" name="Reading_the_stream">ストリームを読む</h3> + +<p>リーダーを取り付けたら、{{domxref("ReadableStreamDefaultReader.read()")}} メソッドを使用してストリームからデータチャンクを読み取ることができます。 これにより、ストリームから1つチャンクを読み取って、好きなことを実行できます。 例えば、単純なストリームポンプの例では、新しいカスタム <code>ReadableStream</code> で各チャンクをキューに入れ（これについては次のセクションで詳しく説明します）、そこから新しい {{domxref("Response")}} を作成し、{{domxref("Blob")}} として使用し、 {{domxref("URL.createObjectURL()")}} を使用してその blob からオブジェクト URL を取得し、それを {{htmlelement("img")}} 要素で画面に表示して、元のフェッチした画像のコピーを効果的に作成します。</p> + +<pre class="brush: js"> return new ReadableStream({ + start(controller) { + return pump(); + function pump() { + return reader.read().then(({ done, value }) => { + // データを消費する必要がなくなったら、ストリームを閉じます + if (done) { + controller.close(); + return; + } + // 次のデータチャンクを対象のストリームのキューに入れます + controller.enqueue(value); + return pump(); + }); + } + } + }) +}) +.then(stream => new Response(stream)) +.then(response => response.blob()) +.then(blob => URL.createObjectURL(blob)) +.then(url => console.log(image.src = url)) +.catch(err => console.error(err));</pre> + +<p><code>read()</code> の使用方法を詳しく見てみましょう。 上記の <code>pump()</code> 関数では、最初に結果オブジェクトを含む promise を返す <code>read()</code> を呼び出します。 結果オブジェクトには、次のように読み取りの結果が <code>{ done, value }</code> の形式で含まれています。</p> + +<pre class="brush: js">return reader.read().then(({ done, value }) => {</pre> + +<p>結果は、次の3つの異なるタイプのいずれかになります。</p> + +<ul> + <li>チャンクが読み取り可能であれば、<code>{ value: theChunk, done: false }</code> の形式のオブジェクトで promise が満たされます。</li> + <li>ストリームが閉じられると、<code>{ value: undefined, done: true }</code> という形式のオブジェクトで promise が満たされます。</li> + <li>ストリームにエラーが発生すると、関連するエラーで promise が拒否されます。</li> +</ul> + +<p>次に、<code>done</code> が <code>true</code> であるかどうかを確認します。 その場合、読み込むチャンクはもうないので（値は <code>undefined</code> です）、関数から戻り、{{domxref("ReadableStreamDefaultController.close()")}} でカスタムストリームを閉じます。</p> + +<pre class="brush: js">if (done) { + controller.close(); + return; +}</pre> + +<div class="note"> +<p><strong>注</strong>: <code>close()</code> は、ここで説明している元のストリームではなく、新しいカスタムストリームの一部です。 次のセクションでカスタムストリームについて詳しく説明します。</p> +</div> + +<p><code>done</code> が <code>true</code> でない場合、読み込んだ新しいチャンク（結果オブジェクトの <code>value</code> プロパティに含まれる）を処理してから、再度 <code>pump()</code> 関数を呼び出して次のチャンクを読み込みます。</p> + +<pre class="brush: js">// 次のデータチャンクを対象のストリームのキューに入れます +controller.enqueue(value); +return pump();</pre> + +<p>これは、ストリームのリーダーを使用するときに示される次のような標準パターンです。</p> + +<ol> + <li>ストリームの読み取りを開始する関数を作成します。</li> + <li>読み込むストリームがこれ以上ない場合は、関数から戻ります。</li> + <li>さらに読み込むストリームがある場合は、現在のチャンクを処理してから、関数を再度実行します。</li> + <li>読み取るストリームがなくなるまで関数を再帰的に実行し続けます。 この場合、手順2が実行されます。</li> +</ol> + +<h2 id="Creating_your_own_custom_readable_stream" name="Creating_your_own_custom_readable_stream">カスタムの読み取り可能なストリームを作成する</h2> + +<p>この記事で学習している単純なストリームポンプの例には2番目の部分が含まれています — フェッチしたボディから画像をチャンク単位で読み取った後、独自作成の別のカスタムストリームのキューに入れます。 これをどのように作成するのでしょうか？ <code>ReadableStream()</code> コンストラクターです。</p> + +<h3 id="The_ReadableStream_constructor" name="The_ReadableStream_constructor">ReadableStream() コンストラクター</h3> + +<p>Fetch の場合のように、ブラウザーが提供するストリームから簡単に読み取ることができますが、カスタムストリームを作成して、独自のチャンクを追加する必要がある場合があります。 {{domxref("ReadableStream.ReadableStream","ReadableStream()")}} コンストラクターを使用すると、最初は複雑に見えますが実際にはそれほど悪くない構文を使用してこれを行うことができます。</p> + +<p>汎用の構文の骨組みは次のようになります。</p> + +<pre class="brush: js">const stream = new ReadableStream({ + start(controller) { + + }, + pull(controller) { + + }, + cancel() { + + }, + type, + autoAllocateChunkSize +}, { + highWaterMark, + size() +});</pre> + +<p>コンストラクターはパラメーターとして2つのオブジェクトを取ります。 最初のオブジェクトは必須であり、データの読み取り元である基になるソースのモデルを JavaScript で作成します。 2番目のオブジェクトはオプションであり、ストリームに使用する<a href="/ja/docs/Web/API/Streams_API/Concepts#Internal_queues_and_queuing_strategies">カスタムのキューイング戦略</a>を指定できます。 これを行う必要はほとんどないため、ここでは最初のものに集中します。</p> + +<p>次のように最初のオブジェクトには最大5つのメンバーを含めることができますが、最初のオブジェクトのみが必要です。</p> + +<ol> + <li><code>start(controller)</code> — <code>ReadableStream</code> が構築された直後に1回だけ呼び出されるメソッド。 このメソッド内には、ストリーム機能を設定するコードを含める必要があります。 例えば、データの生成を開始するか、ソースにアクセスします。</li> + <li><code>pull(controller)</code> — 含まれている場合、ストリームの内部キューがいっぱいになるまで繰り返し呼び出されるメソッド。 これは、より多くのチャンクがキューに入れられるときにストリームを制御するために使用できます。</li> + <li><code>cancel()</code> — 含まれている場合、ストリームをキャンセルすることをアプリが通知した場合に呼び出されるメソッド（例えば、{{domxref("ReadableStream.cancel()")}} が呼び出された場合）。 内容は、ストリームのソースへのアクセスを解放するために必要なことを行う必要があります。</li> + <li><code>type</code> および <code>autoAllocateChunkSize</code> — これらが含まれている場合、ストリームがバイトストリームであることを示すために使用されます。 バイトストリームは、通常の（デフォルトの）ストリームとは目的やユースケースが多少異なるため、今後のチュートリアルで個別に取り上げます。 また、まだどこにも実装されていません。</li> +</ol> + +<p>簡単な例のコードをもう一度見ると、次のように <code>ReadableStream()</code> コンストラクターには、フェッチしたストリームからすべてのデータを読み取るための単一のメソッド <code>start()</code> のみが含まれていることがわかります。</p> + +<pre class="brush: js"> return new ReadableStream({ + start(controller) { + return pump(); + function pump() { + return reader.read().then(({ done, value }) => { + // データを消費する必要がなくなったら、ストリームを閉じます + if (done) { + controller.close(); + return; + } + // 次のデータチャンクを対象のストリームのキューに入れます + controller.enqueue(value); + return pump(); + }); + } + } + }) +}) +</pre> + +<h3 id="ReadableStream_controllers" name="ReadableStream_controllers">ReadableStream コントローラー</h3> + +<p><code>ReadableStream()</code> コンストラクターに渡される <code>start()</code> メソッドと <code>pull()</code> メソッドには <code>controller</code> パラメーターが与えられます。 これらは、ストリームの制御に使用できる {{domxref("ReadableStreamDefaultController")}} クラスのインスタンスです。</p> + +<p>この例では、コントローラーの {{domxref("ReadableStreamDefaultController.enqueue","enqueue()")}} メソッドを使用して、値をフェッチしたボディから読み取った後、カスタムストリームのキューに入れます。</p> + +<p>さらに、フェッチしたボディの読み取りが完了したら、コントローラーの {{domxref("ReadableStreamDefaultController.close","close()")}} メソッドを使用してカスタムストリームを閉じます。 以前にキューに入れられたチャンクはそれから読み取ることができますが、キューに入れることはできません。 読み取りが終了すると、ストリームは閉じられます。</p> + +<h3 id="Reading_from_custom_streams" name="Reading_from_custom_streams">カスタムストリームからの読み取り</h3> + +<p>単純なストリームポンプの例では、カスタムの読み取り可能なストリームを {{domxref("Response.Response", "Response")}} コンストラクターの呼び出しに渡すことで消費し、その後 <code>blob()</code> として消費します。</p> + +<pre class="brush: js">.then(stream => new Response(stream)) +.then(response => response.blob()) +.then(blob => URL.createObjectURL(blob)) +.then(url => console.log(image.src = url)) +.catch(err => console.error(err));</pre> + +<p>ただし、カスタムストリームは引き続き <code>ReadableStream</code> インスタンスであるため、それにリーダーを取りつけることができます。 例として、カスタムストリームを作成し、いくつかのランダムな文字列をキューに入れてから、[文字列の生成を停止] ボタンが押されるとストリームからデータを再度読み取る、単純なランダムストリーム（<a href="https://github.com/mdn/dom-examples/blob/master/streams/simple-random-stream/index.html">Simple random stream</a>）のデモをご覧ください（<a href="https://mdn.github.io/dom-examples/streams/simple-random-stream/">ライブも参照</a>）。</p> + +<p>カスタムストリームのコンストラクターには、{{domxref("WindowTimers.setInterval()")}} 呼び出しを使用して1秒ごとにランダムな文字列を生成する <code>start()</code> メソッドがあります。 次に、{{domxref("ReadableStreamDefaultController.enqueue()")}} を使用してストリームにエンキューします。 ボタンが押されると、インターバルがキャンセルされ、<code>readStream()</code> と呼ばれる関数が呼び出されて、データをストリームから再度読み取ります。 また、チャンクをストリームのキューへ入れることを止めたため、ストリームを閉じます。</p> + +<pre class="brush: js">const stream = new ReadableStream({ + start(controller) { + interval = setInterval(() => { + let string = randomChars(); + // ストリームに文字列を追加 + controller.enqueue(string); + // それを画面に表示 + let listItem = document.createElement('li'); + listItem.textContent = string; + list1.appendChild(listItem); + }, 1000); + button.addEventListener('click', function() { + clearInterval(interval); + readStream(); + controller.close(); + }) + }, + pull(controller) { + // この例では実際には pull は必要ありません + }, + cancel() { + // リーダーがキャンセルされた場合に呼び出されるため、 + // 文字列の生成を停止する必要があります + clearInterval(interval); + } +});</pre> + +<p><code>readStream()</code> 関数自体では、{{domxref("ReadableStream.getReader()")}} を使用してリーダーをストリームにロックし、先ほど見たのと同様のパターンに従います。 <code>read()</code> で各チャンクを読み取り、<code>done</code> が <code>true</code> であるかどうかを確認し、その場合はプロセスを終了し、そうでない場合は <code>read()</code> メソッドを再度実行する前に次のチャンクを読み取って処理します。</p> + +<pre class="brush: js">function readStream() { + const reader = stream.getReader(); + let charsReceived = 0; + + // read() は、値を受け取ったときに解決するプロミスを返します + reader.read().then(function processText({ done, value }) { + // 結果オブジェクトには2つのプロパティが含まれます。 + // done - ストリームがすべてのデータを既に提供している場合は true。 + // value - 一部のデータ。 done が true の場合、常に undefined。 + if (done) { + console.log("Stream complete"); + para.textContent = result; + return; + } + + charsReceived += value.length; + const chunk = value; + let listItem = document.createElement('li'); + listItem.textContent = 'Read ' + charsReceived + ' characters so far. Current chunk = ' + chunk; + list2.appendChild(listItem); + + result += chunk; + + // さらに読み、この関数を再度呼び出します + return reader.read().then(processText); + }); +}</pre> + +<h3 id="Closing_and_cancelling_streams" name="Closing_and_cancelling_streams">ストリームのクローズとキャンセル</h3> + +<p>{{domxref("ReadableStreamDefaultController.close()")}} を使用してリーダーを閉じる例を既に示しました。 前に言ったように、以前にキューに入れられたチャンクはすべて読み込まれますが、閉じられているため、それ以上キューに入れることはできません。</p> + +<p>ストリームを完全に取り除き、キューに入れられたチャンクを破棄したい場合は、{{domxref("ReadableStream.cancel()")}} または {{domxref("ReadableStreamDefaultReader.cancel()")}} を使用します。</p> + +<h2 id="Teeing_a_stream" name="Teeing_a_stream">ストリームのティーイング</h2> + +<p>ストリームを2回同時に読み取りたい場合があります。 これは、{{domxref("ReadableStream.tee()")}} メソッドを介して実現されます — 元の読み取り可能なストリームの2つの同一コピーを含む配列を出力し、2つの別々のリーダーで個別に読み取ることができます。</p> + +<p>例えば、サーバーから応答をフェッチしてブラウザーにストリームするが、Service Worker キャッシュにもストリームする場合は、<a href="/ja/docs/Web/API/Service_Worker_API">ServiceWorker</a> でこれを行うことができます。 応答のボディを複数回使用することはできず、ストリームを一度に複数のリーダーで読み取ることはできないため、これを行うには2つのコピーが必要です。</p> + +<p>単純な tee の例（<a href="https://github.com/mdn/dom-examples/blob/master/streams/simple-tee-example/index.html">Simple tee example</a>）でこの例を示します（<a href="https://mdn.github.io/dom-examples/streams/simple-tee-example/">ライブも参照</a>）。 この例は、単純なランダムストリームとほぼ同じように機能しますが、ボタンを押してランダムな文字列の生成を停止すると、カスタムストリームが取得されて tee され、結果の両方のストリームが読み取られる点が異なります。</p> + +<pre class="brush: js">function teeStream() { + const teedOff = stream.tee(); + readStream(teedOff[0], list2); + readStream(teedOff[1], list3); + }</pre> + +<h2 id="Pipe_chains" name="Pipe_chains">パイプチェーン</h2> + +<p>トリームの非常に実験的な機能の1つは、ストリームを相互にパイプする機能です（<a href="/ja/docs/Web/API/Streams_API/Concepts#Pipe_chains">パイプチェーン</a>と呼ばれます）。 これには2つのメソッドが含まれます。 {{domxref("ReadableStream.pipeThrough()")}} は、読み取り可能ストリームをライター/リーダーのペアにパイプしてデータ形式を別の形式に変換し、{{domxref("ReadableStream.pipeTo()")}} は読み取り可能ストリームをパイプチェーンの終点として動作するライターにパイプします。</p> + +<p>この機能は非常に実験的な段階であり、変更される可能性があるため、現時点ではあまり深く探求していません。</p> + +<p>画像をストリームとしてフェッチし、それをバイナリデータストリームから PNG チャンクを取得するカスタム PNG 変換ストリームにパイプする PNG のチャンクをアンパック（<a href="https://github.com/mdn/dom-examples/tree/master/streams/png-transform-stream">Unpack Chunks of a PNG</a>）という例を作成しました（<a href="https://mdn.github.io/dom-examples/streams/png-transform-stream/">ライブも参照</a>）。</p> + +<pre class="brush: js">// 元の画像をフェッチ +fetch('png-logo.png') +// その body を ReadableStream として取得 +.then(response => response.body) +// 元の画像からグレースケール PNG ストリームを作成 +.then(rs => logReadableStream('Fetch Response Stream', rs)) +.then(body => body.pipeThrough(new PNGTransformStream())) +.then(rs => logReadableStream('PNG Chunk Stream', rs))</pre> + +<h2 id="Summary" name="Summary">まとめ</h2> + +<p>これは、「デフォルト」の読み取り可能なストリームの基本を説明しています。 バイトストリームがブラウザーで利用可能になったら、今後の別の記事でバイトストリームについて説明します。</p> diff --git a/files/ja/web/api/streams_api/using_writable_streams/index.html b/files/ja/web/api/streams_api/using_writable_streams/index.html new file mode 100644 index 0000000000..24444fef38 --- /dev/null +++ b/files/ja/web/api/streams_api/using_writable_streams/index.html @@ -0,0 +1,170 @@ +--- +title: 書き込み可能なストリームの使用 +slug: Web/API/Streams_API/Using_writable_streams +tags: + - API + - Controller + - Guide + - Streams + - WritableStream + - writable streams + - writer +translation_of: Web/API/Streams_API/Using_writable_streams +--- +<div>{{apiref("Streams")}}</div> + +<p><span class="seoSummary">JavaScript 開発者として、プログラムでストリームにデータを書き込むことは非常に便利です！ この記事では、<a href="/ja/docs/Web/API/Streams_API">Streams API</a> の書き込み可能なストリームの機能について説明します。</span></p> + +<div class="note"> +<p><strong>注</strong>: この記事は、書き込み可能なストリームのユースケースを理解し、高レベルの概念を理解していることを前提としています。 そうでない場合は、まず <a href="/ja/docs/Web/API/Streams_API#Concepts_and_usage">Streams の概念と使用方法の概要</a>と専用の <a href="/ja/docs/Web/API/Streams_API/Concepts">Streams API の概念</a>の記事を読んでから、戻ってくることをお勧めします。</p> +</div> + +<div class="note"> +<p><strong>注</strong>: 読み取り可能なストリームに関する情報を探している場合は、代わりに<a href="/ja/docs/Web/API/Streams_API/Using_readable_streams">読み取り可能なストリーム</a>の使用を試してください。</p> +</div> + +<h2 id="Browser_support" name="Browser_support">ブラウザーのサポート</h2> + +<p>Streams API は実験的なものであり、サポートは現在初期段階にあります。 現在、基本的な書き込み可能なストリームが実装されているのは Chrome のみです。</p> + +<h2 id="Introducing_an_example" name="Introducing_an_example">例の紹介</h2> + +<p><a href="https://github.com/mdn/dom-examples/tree/master/streams">dom-examples/streams</a> リポジトリには、単純なライターの例（<a href="https://github.com/mdn/dom-examples/blob/master/streams/simple-writer/index.html">Simple writer example</a>）があります（<a href="https://mdn.github.io/dom-examples/streams/simple-writer/">ライブも参照</a>）。 これは、指定されたメッセージを取得して書き込み可能なストリームに書き込み、ストリームに書き込まれるときに UI に各チャンクを表示し、書き込みが終了すると UI にメッセージ全体を表示します。</p> + +<h2 id="How_writable_streams_work" name="How_writable_streams_work">書き込み可能なストリームの仕組み</h2> + +<p>書き込み可能なストリーム機能のデモの仕組みを見てみましょう。</p> + +<h3 id="Constructing_a_writable_stream" name="Constructing_a_writable_stream">書き込み可能なストリームの構築</h3> + +<p>書き込み可能なストリームを作成するには、{{domxref("WritableStream.WritableStream","WritableStream()")}} コンストラクターを使用します。 構文は最初は複雑に見えますが、実際にはそれほど悪くはありません。</p> + +<p>構文の骨組みは次のようになります。</p> + +<pre class="brush: js">const stream = new WritableStream({ + start(controller) { + + }, + write(chunk,controller) { + + }, + close(controller) { + + }, + abort(reason) { + + } +}, { + highWaterMark, + size() +});</pre> + +<p>コンストラクターはパラメーターとして2つのオブジェクトを取ります。 最初のオブジェクトは必須であり、データの書き込み先の基になるシンクのモデルを JavaScript で作成します。 2番目のオブジェクトはオプションであり、{{domxref("ByteLengthQueuingStrategy")}} または {{domxref("CountQueuingStrategy")}} のインスタンスの形式をとる、ストリームに使用する<a href="/ja/docs/Web/API/Streams_API/Concepts#Internal_queues_and_queuing_strategies">カスタムのキューイング戦略</a>を指定できます。</p> + +<p>次のように最初のオブジェクトには最大4つのメンバーを含めることができますが、それらはすべてオプションです。</p> + +<ol> + <li><code>start(controller)</code> — {{domxref("WritableStream")}} が構築された直後に1回だけ呼び出されるメソッド。 このメソッド内には、ストリーム機能を設定するコードを含める必要があります。 例えば、基になるシンクへのアクセスを取得します。</li> + <li><code>write(chunk,controller)</code> — 新しいチャンク（<code>chunk</code> パラメーターで指定）を基になるシンクに書き込む準備ができるたびに繰り返し呼び出されるメソッド。</li> + <li><code>close(controller)</code> — ストリームへのチャンクの書き込みが完了したことをアプリが通知した場合に呼び出されるメソッド。 基になるシンクへの書き込みを完了し、アクセスを解放するために必要なことは何でも行う必要があります。</li> + <li><code>abort(reason)</code> — ストリームを突然閉じてエラー状態にしたいとアプリが通知した場合に呼び出されるメソッド。</li> +</ol> + +<p>この例のコンストラクター呼び出しは次のようになります。</p> + +<pre class="brush: js">const decoder = new TextDecoder("utf-8"); +const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 }); +let result = ""; +const writableStream = new WritableStream({ + // シンクの実装 + write(chunk) { + return new Promise((resolve, reject) => { + var buffer = new ArrayBuffer(2); + var view = new Uint16Array(buffer); + view[0] = chunk; + var decoded = decoder.decode(view, { stream: true }); + var listItem = document.createElement('li'); + listItem.textContent = "Chunk decoded: " + decoded; + list.appendChild(listItem); + result += decoded; + resolve(); + }); + }, + close() { + var listItem = document.createElement('li'); + listItem.textContent = "[MESSAGE RECEIVED] " + result; + list.appendChild(listItem); + }, + abort(err) { + console.log("Sink error:", err); + } +}, queuingStrategy);</pre> + +<ul> + <li><code>write()</code> メソッドには、書き込まれた各チャンクを UI に書き込める形式にデコードするコードを含むプロミスが含まれています。 これは、各チャンクが実際に書き込まれるときに呼び出されます（次のセクションを参照）。</li> + <li><code>close()</code> メソッドは、書き込みが終了すると自動的に呼び出されます — デコードされた結果全体を1つの文字列で UI に出力します。</li> + <li><code>abort()</code> メソッドは、ストリームが中断された場合にコンソールにエラーを出力するだけです。</li> +</ul> + +<h3 id="Writing" name="Writing">書き込み</h3> + +<p>実際にストリームにコンテンツを書き込むには、次のように <code>sendMessage()</code> 関数を呼び出して、書き込むメッセージと書き込み先のストリームを渡します。</p> + +<pre class="brush: js">sendMessage("Hello, world.", writableStream);</pre> + +<p><code>sendMessage()</code> の定義は次のようになります。</p> + +<pre class="brush: js">function sendMessage(message, writableStream) { + // defaultWriter は WritableStreamDefaultWriter 型です + const defaultWriter = writableStream.getWriter(); + const encoder = new TextEncoder(); + const encoded = encoder.encode(message, { stream: true }); + encoded.forEach((chunk) => { + defaultWriter.ready + .then(() => { + return defaultWriter.write(chunk); + }) + .then(() => { + console.log("Chunk written to sink."); + }) + .catch((err) => { + console.log("Chunk error:", err); + }); + }); + // ライターを閉じる前にすべてのチャンクが確実に + // 書き込まれるように、ready を再度呼び出します。 + defaultWriter.ready + .then(() => { + defaultWriter.close(); + }) + .then(() => { + console.log("All chunks written"); + }) + .catch((err) => { + console.log("Stream error:", err); + }); +}</pre> + +<p>したがって、ここでは、{{domxref("WritableStream.getWriter()")}} を使用してストリームにチャンクを書き込むライターを作成します。 これにより、{{domxref("WritableStreamDefaultWriter")}} インスタンスが作成されます。</p> + +<p>また、関連するコンストラクターを使用して新しい {{domxref("TextEncoder")}} インスタンスを作成し、メッセージをチャンクにエンコードしてストリームに入れます。</p> + +<p>エンコードされたチャンクを使用して、結果の配列で {{jsxref("Array/forEach")}} を呼び出します。 このブロック内で、{{domxref("WritableStreamDefaultWriter.ready")}} を使用して、ライターに別のチャンクを書き込む準備ができているかどうかを確認します。 <code>ready</code> は、この場合に満たされるプロミスを返します。 その中で、{{domxref("WritableStreamDefaultWriter.write()")}} を呼び出して、実際にストリームにチャンクを書き込みます。 これにより、前述のように、<code>WritableStream()</code> コンストラクター内で指定された <code>write()</code> メソッドもトリガーされます。</p> + +<p>チャンクがすべて書き込まれた後、最後のチャンクの書き込みが完了し、すべての作業が完了したことを確認するために、もう一度 <code>ready</code> のチェックを実行します。この <code>ready</code> のチェックが完了すると、{{domxref("WritableStreamDefaultWriter.close()")}} を呼び出してストリームを閉じます。 これにより、前述のように、<code>WritableStream()</code> コンストラクター内で指定された <code>close()</code> メソッドもトリガーされます。</p> + +<h3 id="Controllers" name="Controllers">コントローラー</h3> + +<p><code>WritableStream()</code> 構文の骨組みを学習するときに気付くように、<code>start()</code>、<code>write()</code>、および <code>close()</code> メソッドには、オプションで <code>controller</code> パラメーターを渡すことができます。 これには、{{domxref("WritableStreamDefaultController")}} インターフェイスのインスタンスが含まれます。 これは、開発者が必要に応じてストリームをさらに制御するために使用できます。</p> + +<p>現在、このインターフェイスで使用できるメソッドは {{domxref("WritableStreamDefaultController.error()")}} のみです。 このメソッドを呼び出すと、ストリームとの今後の相互作用でエラーが発生します。 これは、アプリの別の部分がうまくいかず、がらくたがストリームに静かに書き込まれる (または同様に悪い）危険を冒すのではなく、システム全体がきれいに失敗するようにエラーをストリームに伝播したい場合に便利です。</p> + +<h3 id="Closing_and_aborting" name="Closing_and_aborting">終了および中止</h3> + +<p>上記のように、書き込みが終了すると <code>close()</code> メソッドを呼び出し、<code>WritableStream()</code> コンストラクター内で指定された <code>close()</code> メソッドをトリガーします。</p> + +<p>{{domxref("WritableStreamDefaultWriter.abort()")}} を呼び出してストリームを中止することもできます。</p> + +<p>違いは、<code>close()</code> を呼び出すと、ストリームが閉じられる前に、以前にキューに入れられたチャンクが書き込まれ、終了することです。</p> + +<p><code>abort()</code> を呼び出すと、以前にキューに入れられたチャンクはすぐに破棄され、ストリームはエラー状態に移行します。 また、これにより、<code>WritableStream()</code> コンストラクターで指定された <code>abort()</code> メソッドが呼び出されます。</p> |