Chrome拡張機能のメッセージング（chrome.runtime.onMessage）完全解説

Last updated at 2025-05-02Posted at 2025-05-02

Chrome拡張機能の異なるコンポーネント（バックグラウンドスクリプト、コンテンツスクリプト、ポップアップなど）間でデータをやり取りするためのメッセージングシステムについて詳しく解説します。

基本的な使い方

メッセージの送信側


chrome.runtime.sendMessage(
  { action: "getData", parameter: "some value" },  // 送信するメッセージ
  function(response) {                             // 返信を受け取るコールバック
    console.log("受信した返信:", response);
  }
);

第1引数: 送信するメッセージオブジェクト（任意のJSONシリアライズ可能なデータ）
第2引数: 受信側からの返信を処理するコールバック関数

メッセージの受信側（リスナー）

chrome.runtime.onMessage.addListener(
  function(message, sender, sendResponse) {
    // message: 送信されたメッセージオブジェクト
    // sender: メッセージを送信した側の情報
    // sendResponse: 返信するための関数

    console.log("メッセージを受け取りました:", message);
    
    // 送信元に返信する場合
    sendResponse({ status: "メッセージを受け取りました" });
    
    // 非同期で返信する場合は true を返す
    // return true;
  }
);

パラメータの対応関係

message:
- 送信側の chrome.runtime.sendMessage の第1引数として渡されたオブジェクト
- 例: { action: "getData", parameter: "some value" }
sender:
- メッセージを送信した拡張機能やタブに関する情報を含むオブジェクト
- 主なプロパティ:
  - tab: メッセージを送信したタブの情報（コンテンツスクリプトから送信された場合）
  - id: 送信元の拡張機能ID
  - url: 送信元のURL（コンテンツスクリプトの場合）
sendResponse:
- 送信側のコールバック関数に値を渡すための関数
- この関数を呼び出すと、送信側の第2引数のコールバック関数が実行される
- 例：
```
function(response) {
    console.log("受信した返信:", response);
}
```

図解

送信側                                  受信側
---------------------------------------------------------
chrome.runtime.sendMessage(            chrome.runtime.onMessage.addListener(
  { action: "getData" },  --------→      function(message, sender, sendResponse) {
                                           // message = { action: "getData" }
                                           
  function(response) {      ←--------     sendResponse({ response: "OK" });
    // response = { response: "OK" }     }
  }                                    );
);

sendResponse関数（コールバック関数）の役割

sendResponse は「返信するための関数」で、Chrome拡張機能のメッセージングシステムが自動的に生成して、リスナー関数の第3引数として提供します。

通信の流れ

以下の流れで送信側と受信側でデータのやり取りが行われます：

受信側で sendResponse({ status: "処理結果データ" }) のように呼び出します
すると送信側のコールバック関数 function(responseData) { ... } が実行されます
この時、送信側のコールバック関数の引数 responseData には、{ status: "処理結果データ" } というオブジェクトが渡されます

つまり、sendResponse に渡したオブジェクトが、そのまま送信側のコールバック関数の引数になります。

コールバック関数が使われる局面

コールバック関数は 「送り元の環境の状態での処理に、送り先の情報が必要な時」 に使われる重要なパターンです。

コールバック関数の特性

コンテキストの保持: 送信元（例：ポップアップ）のDOM要素などへのアクセスを維持できる
非同期処理の結果を元の環境に戻す: 受信側で取得したデータを、送信元のUI更新などに使える
環境間のギャップを埋める: 異なる実行コンテキスト間でデータをやり取りできる

具体例

例えば、ポップアップUI（フロント）からバックグラウンドスクリプト（バックエンド）にユーザーデータを要求し、受け取ったデータでUIを更新する場合：

// ポップアップ側（送り元）
function updateUI() {
  const statusElement = document.getElementById("status");
  statusElement.textContent = "データを取得中...";
  
  chrome.runtime.sendMessage(
    { action: "fetchUserData" },
    function(response) {
      // このコールバック関数はポップアップのコンテキストで実行される
      if (response.success) {
        statusElement.textContent = "ようこそ、" + response.userData.name + "さん";
        document.getElementById("userEmail").textContent = response.userData.email;
      } else {
        statusElement.textContent = "エラー: " + response.error;
      }
    }
  );
}

非同期応答と `return true`

`return true` の基本ルール

基本原則: 非同期処理を行い、その完了後に sendResponse を呼び出す場合は、リスナー関数から return true する必要があります。

なぜ `return true` が必要なのか？

Chrome拡張機能のメッセージングシステムは、デフォルトでは同期的な応答を想定しています。

1. 同期応答の場合: リスナー関数が終了すると同時に通信チャネルが閉じられます
2. 非同期応答の場合: return true によって「後で応答するので通信チャネルを開いたままにしておいてください」と伝えます

return true の配置ルール

配置場所: chrome.runtime.onMessage.addListener に渡すリスナー関数の中
配置位置: 対応するメッセージ処理ブロックの最後
スコープ: 非同期処理を行うスコープ内で return true する

同期応答の例（return true 不要）

chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  if (message.action === "getTime") {
    // 即座に応答
    sendResponse({ time: new Date().toString() });
    // return true は不要
  }
});

非同期応答の例（return true が必要）

chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  if (message.action === "fetchData") {
    // 非同期処理
    fetch('https://api.example.com/data')
      .then(response => response.json())
      .then(data => {
        // 非同期処理完了後に応答
        sendResponse({ success: true, data: data });
      })
      .catch(error => {
        sendResponse({ success: false, error: error.message });
      });
    
    // 非同期応答のために通信チャネルを維持
    return true;
  }
});

よくある間違い

非同期処理なのに return true を忘れる:

// 間違い例
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  setTimeout(() => {
    sendResponse({ result: "データ" }); // この応答は届かない
  }, 1000);
  // return true がないので通信チャネルが閉じられる
});

同期処理なのに不要な return true を含める:

// 冗長な例（動作はするが不要）
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  sendResponse({ result: "即時応答" });
  return true; // 不要（同期応答なので）
});

return true の位置が正しくない:

// 間違い例
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  if (message.action === "fetchData") {
    fetch('https://api.example.com/data')
      .then(data => {
        sendResponse({ data: data });
        return true; // ← 間違い: Promise内ではなくリスナー関数の中で返す必要がある
      });
  }
});

実用的な例

例1: ポップアップとバックグラウンド間の通信

// ポップアップ側
document.getElementById("getSettings").addEventListener("click", function() {
  chrome.runtime.sendMessage({ action: "getSettings" }, function(response) {
    if (response && response.settings) {
      // 設定データを使ってUIを更新
      document.getElementById("settingsDisplay").textContent = 
        JSON.stringify(response.settings, null, 2);
    }
  });
});

// バックグラウンド側
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  if (message.action === "getSettings") {
    chrome.storage.sync.get("settings", function(data) {
      sendResponse({ settings: data.settings || {} });
    });
    return true; // 非同期応答のために必須
  }
});

例2: コンテンツスクリプトとポップアップ間の通信

// ポップアップ側
document.getElementById("getPageInfo").addEventListener("click", function() {
  chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
    chrome.tabs.sendMessage(tabs[0].id, {action: "getPageInfo"}, function(response) {
      if (response) {
        document.getElementById("title").textContent = response.title;
        document.getElementById("url").textContent = response.url;
        document.getElementById("wordCount").textContent = response.wordCount;
      }
    });
  });
});

// コンテンツスクリプト側
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  if (message.action === "getPageInfo") {
    // ページからデータを収集
    const text = document.body.innerText;
    const wordCount = text.split(/\s+/).filter(Boolean).length;
    
    sendResponse({
      title: document.title,
      url: window.location.href,
      wordCount: wordCount
    });
  }
});

例3: 非同期APIを使った処理

// 送信側
chrome.runtime.sendMessage(
  { action: "fetchUserData", userId: "12345" },
  function(response) {
    if (response.success) {
      console.log("ユーザーデータ:", response.userData);
      // データを使った処理
    } else {
      console.error("エラー:", response.error);
    }
  }
);

// 受信側
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
  if (message.action === "fetchUserData") {
    fetch(`https://api.example.com/users/${message.userId}`)
      .then(response => response.json())
      .then(userData => {
        sendResponse({ success: true, userData });
      })
      .catch(error => {
        sendResponse({ success: false, error: error.message });
      });
    return true; // 非同期応答のために必須
  }
});

まとめ

Chrome拡張機能のメッセージングシステムは、異なるコンポーネント間の通信を可能にする重要な機能です。

基本構造: 送信側（sendMessage）と受信側（onMessage.addListener）
データの流れ: 送信側から受信側へのメッセージ、受信側から送信側への応答
コールバック関数: 送信元のコンテキストでの処理を可能にする
非同期処理: return true で通信チャネルを維持

これらの概念を理解することで、複雑な拡張機能でも効率的なコンポーネント間通信を実現できます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up