runtime.sendMessage()

単一のメッセージを、自分や別の拡張機能が持つイベントリスナーに送信します。

自分自身の拡張機能に送信する場合は、引数 extensionId を省略してください。自らの拡張機能に含まれる全てのページで runtime.onMessage イベントが起動されます。ただし、runtime.sendMessage を実行したフレームは除きます。

別の拡張機能に送信する場合は、引数 extensionId に拡張機能の ID を設定してください。その拡張機能で runtime.onMessageExternal (en-US) イベントが起動されます。

このメソッドを使ってコンテンツスクリプトにメッセージを送信することはできません。コンテンツスクリプトにメッセージを送信するには、tabs.sendMessage (en-US) を使ってください。

これは、Promise を返す非同期関数です。

メモ: コネクションベースのメッセージを使うこともできます。

string 型。メッセージを送信する拡張機能の ID。別の拡張機能にメッセージを送信する場合は、この引数を含めてください。受信させることを意図している拡張機能が manifest.json の applications キーを使って明示的に ID を設定されている場合は、その値を extensionId に指定する必要があります。そうでない場合、受信側の拡張機能のために生成された ID を指定する必要があります。もし extensionId が省略された場合、メッセージは自分自身の拡張機能に送信されます。

message

any 型。シリアライズされたクローンに構造化できるオブジェクト。

options省略可

object 型。

includeTlsChannelId省略可: boolean 型。接続イベントを待つプロセスのための runtime.onMessageExternal (en-US) に TLS チャンネル ID が渡されるかどうか。
toProxyScript省略可: boolean 型。メッセージが proxy API を使って読み込まれる PAC ファイル向けである場合、true を指定しなければならない。

引数に指定される値によっては、この API はあいまいです。以降のルールが使われます。

引数が一つの場合、それは送信されるメッセージで、内部的に送信されます。
引数が二つの場合
- 二番目の引数が次のいずれかである場合、引数は (message, options) と解釈され、メッセージは内部的に送信されます。
  1. 有効な options オブジェクトである (つまり、ブラウザーがサポートする options のプロパティのみを持つオブジェクト)
  2. null
  3. undefined
- それ以外の場合、引数は (extensionId, message) と解釈され、メッセージは extensionId によって識別された拡張機能に送信されます。
引数が三つの場合、引数は (extensionId, message, options) と解釈されます。メッセージは extensionId によって識別された拡張機能に送信されます。

Firefox 55 より前では、引数が二つの場合のルールが異なることに注意してください。古いルールでは、最初の引数が文字列である場合、それを extensionId と扱い、二番目の引数をメッセージとして使います。これは、sendMessage() を ("my-message", {}) のような引数を使って実行する場合、空のメッセージを "my-message" によって識別される拡張機能に送信してしまうということです。新しいルールのもとでは、このような引数を使うと、"my-message" というメッセージを空のオプションオブジェクトを使って内部的に送信します。

戻り値

Promise 型。受信側が応答を送信する場合、その応答を JSON オブジェクトとして使って fulfilled 状態にされます。それ以外の場合、値を持たない fulfilled 状態になります。拡張機能との接続中にエラーが発生した場合、Promise はエラーメッセージを持つ rejected 状態になります。

ブラウザーの互換性

BCD tables only load in the browser

使用例

これは、ユーザーがコンテンツのウィンドウをクリックしたときにバックグラウンドスクリプトにメッセージを送信するコンテンツスクリプトです。送信されるメッセージは {greeting: "Greeting from the content script"} で、送信側は応答を受信をすることになっており、それを handleResponse 関数で扱います。

// content-script.js

function handleResponse(message) {
  console.log(`Message from the background script:  ${message.response}`);
}

function handleError(error) {
  console.log(`Error: ${error}`);
}

function notifyBackgroundPage(e) {
  var sending = browser.runtime.sendMessage({
    greeting: "Greeting from the content script",
  });
  sending.then(handleResponse, handleError);
}

window.addEventListener("click", notifyBackgroundPage);

対応するバックグラウンドスクリプトは次のようなものです。

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log("Message from the content script: " + request.greeting);
  sendResponse({ response: "Response from background script" });
}

browser.runtime.onMessage.addListener(handleMessage);

Example extensions

メモ: この API は Chromium の chrome.runtime API に基づいています。このドキュメントは runtime.json における Chromium のコードに基づいています。Microsoft Edge での実装状況は Microsoft Corporation から提供されたものであり、ここでは Creative Commons Attribution 3.0 United States License に従っています。

構文

引数

戻り値

ブラウザーの互換性

使用例

Example extensions