MessagePort: postMessage() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.

メモ: この機能はウェブワーカー内で利用可能です。

postMessage() は MessagePort インターフェイスのメソッドで、ポートからのメッセージを送信します。任意で、オブジェクトの所有権を他の閲覧コンテキストへ転送します。

構文

js
postMessage(message)
postMessage(message, transfer)
postMessage(message, options)

引数

message

チャンネル経由で送信するメッセージ。これはいずれかの基本データ型です。複数のデータアイテムを配列として送信できます。

transfer 省略可

オプションで、所有権を委譲する移譲可能オブジェクトの配列。これらのオブジェクトの所有権は出力先に移動され、送信側ではそれらを使用できなくなります。これらの移譲可能オブジェクトはメッセージに添付する必要があります。そうでない場合、移動はされますが、受信側では実際にアクセスできなくなります。

options 省略可

オプションで、以下のプロパティを持つオブジェクトです。

transfer 省略可

transfer 引数と同じ意味です。

返値

なし (undefined)。

例

次のコードブロックでは、MessageChannel() コンストラクターで新しいチャンネルを作成しています。IFrame が読み込まれた時、MessageChannel.port2 が window.postMessage メソッドによってメッセージとともに IFrame へ渡されます。すると、handleMessage が onmessage によって IFrame から返されたメッセージに応答し、そのメッセージを段落に出力します。ここで、MessageChannel.port1 は、メッセージが到着したときに確認するための待機状態にあります。

js
const channel = new MessageChannel();
const para = document.querySelector("p");

const ifr = document.querySelector("iframe");
const otherWindow = ifr.contentWindow;

ifr.addEventListener("load", iframeLoaded, false);

function iframeLoaded() {
  otherWindow.postMessage("Transferring message port", "*", [channel.port2]);
}

channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}

// in the iframe…

window.addEventListener("message", (event) => {
  const messagePort = event.ports?.[0];
  messagePort.postMessage("Hello from the iframe!");
});

完全に動作する例は、Github 上の チャンネルメッセージ送信の基本デモ を見てください (実際の動作も確認できます)。

仕様書

Specification
HTML
# dom-messageport-postmessage-dev

ブラウザーの互換性

BCD tables only load in the browser

関連情報