Web/API/Worker/postMessage を新規翻訳

- 2021/08/22 時点の英語版に基づき新規翻訳

1 files changed, 156 insertions, 0 deletions

diff --git a/files/ja/web/api/worker/postmessage/index.html b/files/ja/web/api/worker/postmessage/index.html
new file mode 100644
index 0000000000..58005903b1
--- /dev/null
+++ b/files/ja/web/api/worker/postmessage/index.html
@@ -0,0 +1,156 @@
+---
+title: Worker.prototype.postMessage()
+slug: Web/API/Worker/postMessage
+tags:
+  - API
+  - JavaScript
+  - Method
+  - Reference
+  - Web Workers
+  - Worker
+  - postMessage
+browser-compat: api.Worker.postMessage
+translation_of: Web/API/Worker/postMessage
+---
+<p>{{APIRef("Web Workers API")}}</p>
+
+<p><code><strong>postMessage()</strong></code> は {{domxref("Worker")}} インターフェイスのメソッドで、ワーカーの内部スコープにメッセージを送信します。これは、ワーカーに送信するデータを単一の引数として受け取ります。このデータは任意の値、または循環参照を含む場合は<a href="/ja/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">構造化クローン</a>アルゴリズムで扱う JavaScript オブジェクトが許可されます。</p>
+
+<p>{{domxref("Worker")}} の <code>postMessage()</code> メソッドは {{domxref("MessagePort")}} の {{domxref("MessagePort.postMessage", "postMessage()")}} メソッドに委任して、受信する {{domxref("MessagePort")}} に対応するイベントループのタスクを追加します。</p>
+
+<p><code>Worker</code> は {{domxref("DedicatedWorkerGlobalScope.postMessage")}} メソッド使用して自分を起動したスレッドに情報を送り返すことができます。</p>
+
+<h2 id="Syntax">構文</h2>
+
+<pre class="brush: js">worker.postMessage(message, [transfer]);</pre>
+
+<h3 id="Parameters">引数</h3>
+
+<dl>
+ <dt><em>message</em></dt>
+ <dd>ワーカーに送るオブジェクトです。これは {{domxref("DedicatedWorkerGlobalScope.onmessage")}} ハンドラーに配信されるイベントの <code>data</code> フィールドに入ります。このデータは任意の値、または循環参照を含む場合は<a href="/ja/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">構造化クローン</a>アルゴリズムで扱う JavaScript オブジェクトが許可されます。</dd>
+ <dd><code>message</code> 引数が提供されて<em>いない</em>場合は、 <code>TypeError</code> が発生します。ワーカーに渡すデータが重要でない場合は、 <code>null</code> または <code>undefined</code> を明示的に渡すことができます。</dd>
+ <dt><em>transfer</em> {{optional_inline}}</dt>
+ <dd>オプションで、所有権を移転する {{domxref("Transferable")}} オブジェクトの<a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array">配列</a>です。オブジェクトの所有権が移転されると、そのオブジェクトは送信元のコンテキストでは使用できなくなり、送信先のワーカーのみが使用できるようになります。</dd>
+ <dd>Transferable オブジェクトは {{jsxref("ArrayBuffer")}}、{{domxref("MessagePort")}}、{{domxref("ImageBitmap")}} のような移転可能なクラスのインスタンスです。 <code>null</code> を <code>transfer</code> の値として受け付けることはできません。</dd>
+</dl>
+
+<h3 id="Returns">返値</h3>
+
+<p>なし。</p>
+
+<h2 id="Example">例</h2>
+
+<p>次のコードスニペットは、 {{domxref("Worker.Worker", "Worker()")}} コンストラクターを使用して {{domxref("Worker")}} オブジェクトを作成しています。2 つのフォーム入力要素 (<code>first</code> と <code>second</code>) のどちらかの値が変更されると、変更イベントによって <code>postMessage()</code> が呼び出され、両方の入力要素の値が現在のワーカーに送信されます。
+
+<pre class="brush: js">var myWorker = new Worker('worker.js');
+
+first.onchange = function() {
+  myWorker.postMessage([first.value,second.value]);
+  console.log('Message posted to worker');
+}
+
+second.onchange = function() {
+  myWorker.postMessage([first.value,second.value]);
+  console.log('Message posted to worker');
+}
+</pre>
+
+<p>完全な例は、<a class="external external-icon" href="https://github.com/mdn/simple-web-worker">簡単なワーカーの例</a> (<a class="external external-icon" href="https://mdn.github.io/simple-web-worker/">実行例</a>) を参照してください。</p>
+
+<div class="note">
+<p><strong>メモ:</strong> <code>postMessage()</code> は同時に一つしかオブジェクトを送信できません。上記のように、複数の値を渡したい場合は配列を送信してください。</p>
+</div>
+
+<h3 id="Transfer_Example">移転を伴う例</h3>
+
+<p>この最小限の例では、 <code>main</code> が <code>ArrayBuffer</code> を作成して <code>myWorker</code> に移転し、次に <code>myWorker</code> がそれを <code>main</code> に再移転して、それぞれの段階で大きさを記録します。</p>
+
+<h4 id="main.js_code">main.js のコード:</h4>
+
+<pre class="brush: js">
+// ワーカーの生成
+var myWorker = new Worker("myWorker.js");
+
+// myWorker を待ち受けしてバッファーを main に再移転する
+myWorker.addEventListener("message", function handleMessageFromWorker(msg) {
+  console.log("message from worker received in main:", msg);
+
+  var bufTransferredBackFromWorker = msg.data;
+
+  console.log(
+    "buf.byteLength in main AFTER transfer back from worker:",
+    bufTransferredBackFromWorker.byteLength
+  );
+});
+
+// バッファーの生成
+var myBuf = new ArrayBuffer(8);
+
+console.log(
+  "buf.byteLength in main BEFORE transfer to worker:",
+  myBuf.byteLength
+);
+
+// myBuf を myWorker に送信し、配下の ArrayBuffer を移転する
+myWorker.postMessage(myBuf, [myBuf]);
+
+console.log(
+  "buf.byteLength in main AFTER transfer to worker:",
+  myBuf.byteLength
+);
+</pre>
+
+<h4 id="myWorker.js_code">myWorker.js のコード</h4>
+
+<pre class="brush: js">
+// main を待ち受けしてバッファーを myWorker に移転する
+self.onmessage = function handleMessageFromMain(msg) {
+  console.log("message from main received in worker:", msg);
+
+  var bufTransferredFromMain = msg.data;
+
+  console.log(
+    "buf.byteLength in worker BEFORE transfer back to main:",
+    bufTransferredFromMain.byteLength
+  );
+
+  // バッファーを main に送信し返し、配下の ArrayBuffer を移転する
+  self.postMessage(bufTransferredFromMain, [bufTransferredFromMain]);
+
+  console.log(
+    "buf.byteLength in worker AFTER transfer back to main:",
+    bufTransferredFromMain.byteLength
+  );
+};
+</pre>
+
+<h4 id="Output_logged">ログ出力</h4>
+
+<pre class="brush: bash">
+buf.byteLength in main BEFORE transfer to worker:        8                     main.js:19
+buf.byteLength in main AFTER transfer to worker:         0                     main.js:27
+
+message from main received in worker:                    MessageEvent { ... }  myWorker.js:3
+buf.byteLength in worker BEFORE transfer back to main:   8                     myWorker.js:7
+buf.byteLength in worker AFTER transfer back to main:    0                     myWorker.js:15
+
+message from worker received in main:                    MessageEvent { ... }  main.js:6
+buf.byteLength in main AFTER transfer back from worker:  8                     main.js:10
+</pre>
+
+<p><code>byteLength</code> は <code>ArrayBuffer</code> が移転されると 0 になります。 <code>ArrayBuffer</code> の移転のより洗練された完全な動作例については、 <a href="https://github.com/Noitidart/ChromeWorker/tree/aca57d9cadc4e68af16201bdecbfb6f9a6f9ca6b">GitHub :: ChromeWorker - demo-transfer-arraybuffer</a> の Firefox デモアドオンを参照してください。</p>
+
+<h2 id="Specifications">仕様書</h2>
+
+{{Specifications}}
+
+<h2 id="Browser_compatibility">ブラウザーの互換性</h2>
+
+<p>{{Compat}}</p>
+
+<h2 id="See_also">関連情報</h2>
+
+<ul>
+ <li>所属先の {{domxref("Worker")}} インターフェイス</li>
+</ul>