消息传递

由于内容脚本是在网页的上下文中运行，而不是在运行它们的扩展程序中运行，因此它们通常需要与扩展程序的其余部分进行通信。例如，RSS 阅读器扩展程序可能会使用内容脚本检测网页上是否存在 RSS Feed，然后通知服务工件显示该网页的操作图标。

这种通信使用消息传递，这让扩展程序和内容脚本都可以监听对方的邮件并在同一渠道上做出响应。消息可以包含任何有效的 JSON 对象（null、布尔值、数字、字符串、数组或对象）。有两个消息传递 API：一个用于一次性请求，另一个用于允许发送多条消息的长连接，该 API 更为复杂。如需了解如何在扩展程序之间发送消息，请参阅跨扩展程序消息部分。

一次性请求

如需将单条消息发送到扩展程序的其他部分，并视需要获取回复，请调用 runtime.sendMessage() 或 tabs.sendMessage()。借助这些方法，您可以将一次性 JSON 可序列化消息从内容脚本发送到扩展程序，或从扩展程序发送到内容脚本。如需处理响应，请使用返回的 Promise。为了向后兼容旧版扩展程序，您可以改为将回调作为最后一个参数传递。您不能在同一调用中使用 promise 和回调。

如需了解如何将回调转换为 Promise 并在扩展程序中使用它们，请参阅 Manifest V3 迁移指南。

从内容脚本发送请求如下所示：

content-script.js：

(async () => {
  const response = await chrome.runtime.sendMessage({greeting: "hello"});
  // do something with response here, not outside the function
  console.log(response);
})();

如果您想对消息进行同步响应，只需在有响应后调用 sendResponse，并返回 false 以指示已完成即可。如需异步响应，请返回 true 以保持 sendResponse 回调处于活动状态，直到您准备好使用它为止。不支持使用异步函数，因为它们会返回 Promise，而 Promise 不受支持。

如需向内容脚本发送请求，请指定请求适用于哪个标签页，如下所示。此示例适用于以标签页形式打开的 Service Worker、弹出式窗口和 chrome-extension:// 页面。

(async () => {
  const [tab] = await chrome.tabs.query({active: true, lastFocusedWindow: true});
  const response = await chrome.tabs.sendMessage(tab.id, {greeting: "hello"});
  // do something with response here, not outside the function
  console.log(response);
})();

如需接收消息，请设置 runtime.onMessage 事件监听器。扩展程序和内容脚本中使用相同的代码：

content-script.js 或 service-worker.js：

chrome.runtime.onMessage.addListener(
  function(request, sender, sendResponse) {
    console.log(sender.tab ?
                "from a content script:" + sender.tab.url :
                "from the extension");
    if (request.greeting === "hello")
      sendResponse({farewell: "goodbye"});
  }
);

在前面的示例中，sendResponse() 是同步调用的。如需异步使用 sendResponse()，请将 return true; 添加到 onMessage 事件处理脚本。

如果有多个网页监听 onMessage 事件，则只有第一个针对特定事件调用 sendResponse() 的网页才能成功发送响应。系统会忽略对该事件的所有其他响应。

长连接

如需创建可重复使用的长期消息传递渠道，请调用 runtime.connect() 以将消息从内容脚本传递到扩展程序页面，或调用 tabs.connect() 将消息从扩展程序页面传递到内容脚本。您可以为频道命名 以区分不同类型的连接

长连接的一个潜在用例是自动表单填充扩展程序。内容脚本可能会针对特定登录打开一个通道到扩展程序页面，并针对页面上的每个输入元素向扩展程序发送消息，以请求填充表单数据。借助共享连接，扩展程序可以在扩展程序组件之间共享状态。

建立连接时，每个端都会分配一个 runtime.Port 对象，以便通过该连接发送和接收消息。

使用以下代码从内容脚本打开渠道，并发送和监听消息：

content-script.js：

var port = chrome.runtime.connect({name: "knockknock"});
port.postMessage({joke: "Knock knock"});
port.onMessage.addListener(function(msg) {
  if (msg.question === "Who's there?")
    port.postMessage({answer: "Madame"});
  else if (msg.question === "Madame who?")
    port.postMessage({answer: "Madame... Bovary"});
});

如需从扩展程序向内容脚本发送请求，请将前面的示例中对 runtime.connect() 的调用替换为 tabs.connect()。

如需处理内容脚本或扩展程序页面的传入连接，请设置 runtime.onConnect 事件监听器。当扩展程序的其他部分调用 connect() 时，它会激活此事件和 runtime.Port 对象。响应传入连接的代码如下所示：

service-worker.js：

chrome.runtime.onConnect.addListener(function(port) {
  console.assert(port.name === "knockknock");
  port.onMessage.addListener(function(msg) {
    if (msg.joke === "Knock knock")
      port.postMessage({question: "Who's there?"});
    else if (msg.answer === "Madame")
      port.postMessage({question: "Madame who?"});
    else if (msg.answer === "Madame... Bovary")
      port.postMessage({question: "I don't get it."});
  });
});

充电桩生命周期

端口旨在作为扩展程序不同部分之间的双向通信方法。顶级帧是扩展程序中可以使用端口的最小部分。当扩展程序的某个部分调用 tabs.connect()、runtime.connect() 或 runtime.connectNative() 时，它会创建一个端口，该端口可以立即使用 postMessage() 发送消息。

如果标签页中有多个帧，则调用 tabs.connect() 会针对标签页中的每个帧调用 runtime.onConnect 事件一次。同样，如果调用 runtime.connect()，则 onConnect 事件会针对扩展进程中的每个帧触发一次。

您可能需要了解连接何时关闭，例如，如果您要为每个打开的端口维护单独的状态。为此，请监听 runtime.Port.onDisconnect 事件。当通道的另一端没有有效的端口时，系统会触发此事件。这可能由以下任一原因造成：

  • 在另一端没有 runtime.onConnect 的监听器。
  • 包含相应端口的标签页会被卸载（例如，如果已浏览此标签页）。
  • 调用 connect() 的帧已卸载。
  • 接收了端口（通过 runtime.onConnect）的所有帧均已卸载。
  • runtime.Port.disconnect() 由另一端调用。如果 connect() 调用导致接收器端有多个端口，而其中任何端口上调用了 disconnect()，则 onDisconnect 事件仅在发送端口触发，而不会在其他端口触发。

跨附加信息消息

除了在扩展程序中的不同组件之间发送消息之外，您还可以使用消息传递 API 与其他扩展程序进行通信。这样，您就可以公开一个公共 API 供其他扩展程序使用。

如需监听来自其他扩展程序的传入请求和连接，请使用 runtime.onMessageExternal 或 runtime.onConnectExternal 方法。以下是每种类型的示例：

service-worker.js

// For a single request:
chrome.runtime.onMessageExternal.addListener(
  function(request, sender, sendResponse) {
    if (sender.id === blocklistedExtension)
      return;  // don't allow this extension access
    else if (request.getTargetData)
      sendResponse({targetData: targetData});
    else if (request.activateLasers) {
      var success = activateLasers();
      sendResponse({activateLasers: success});
    }
  });

// For long-lived connections:
chrome.runtime.onConnectExternal.addListener(function(port) {
  port.onMessage.addListener(function(msg) {
    // See other examples for sample onMessage handlers.
  });
});

如需向其他扩展程序发送消息，请按如下方式传递您要与之通信的扩展程序的 ID：

service-worker.js

// The ID of the extension we want to talk to.
var laserExtensionId = "abcdefghijklmnoabcdefhijklmnoabc";

// For a simple request:
chrome.runtime.sendMessage(laserExtensionId, {getTargetData: true},
  function(response) {
    if (targetInRange(response.targetData))
      chrome.runtime.sendMessage(laserExtensionId, {activateLasers: true});
  }
);

// For a long-lived connection:
var port = chrome.runtime.connect(laserExtensionId);
port.postMessage(...);

通过网页发送消息

扩展程序还可以接收和回复来自其他网页的消息，但无法向网页发送消息。如需从网页向扩展程序发送消息，请在 manifest.json 中使用 "externally_connectable" 清单键指定要与哪些网站通信。例如：

manifest.json

"externally_connectable": {
  "matches": ["https://*.example.com/*"]
}

这样，Messaging API 便会向与您指定的网址模式匹配的任何网页公开。网址模式必须至少包含一个二级域名；也就是说，不支持“*”，“*.com”“*.co.uk”和“*.appspot.com”等主机名模式。从 Chrome 107 开始，您可以使用 <all_urls> 访问所有网域。请注意，由于它会影响所有主机，因此在 Chrome 应用商店中审核使用它的扩展程序可能需要更长时间。

使用 runtime.sendMessage() 或 runtime.connect() API 向特定应用或扩展程序发送消息。例如：

webpage.js

// The ID of the extension we want to talk to.
var editorExtensionId = "abcdefghijklmnoabcdefhijklmnoabc";

// Make a simple request:
chrome.runtime.sendMessage(editorExtensionId, {openUrlInEditor: url},
  function(response) {
    if (!response.success)
      handleError(url);
  });

在您的扩展程序中，使用 runtime.onMessageExternal 或 runtime.onConnectExternal API 监听来自网页的消息，如跨扩展程序消息传递中所述。示例如下：

service-worker.js

chrome.runtime.onMessageExternal.addListener(
  function(request, sender, sendResponse) {
    if (sender.url === blocklistedWebsite)
      return;  // don't allow this web page access
    if (request.openUrlInEditor)
      openUrl(request.openUrlInEditor);
  });

原生消息传递

扩展程序可以与注册为原生消息传递主机的原生应用交换消息。如需详细了解此功能，请参阅原生消息传递。

安全注意事项

以下是与消息相关的一些安全注意事项。

内容脚本的可信度较低

与扩展程序服务工件相比，内容脚本的可信度较低。例如，恶意网页可能会破坏运行内容脚本的呈现进程。假设内容脚本中的消息可能是由攻击者伪造的，并确保验证并清理所有输入。假设发送到内容脚本的任何数据都可能会泄露到网页。限制可由从内容脚本收到的消息触发的特权操作的范围。

跨站点脚本攻击

请务必保护您的脚本免受跨网站脚本攻击。从不受信任的来源（例如用户输入、通过内容脚本或 API 接收其他网站）接收数据时，请注意不要将其解读为 HTML，或以可能导致意外代码运行的方式使用这些数据。

更安全的方法

请尽可能使用不会运行脚本的 API：

service-worker.js

chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // JSON.parse doesn't evaluate the attacker's scripts.
  var resp = JSON.parse(response.farewell);
});

service-worker.js

chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // innerText does not let the attacker inject HTML elements.
  document.getElementById("resp").innerText = response.farewell;
});
不安全的方法

避免使用会使您的扩展程序易受攻击的以下方法：

service-worker.js

chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // WARNING! Might be evaluating a malicious script!
  var resp = eval(`(${response.farewell})`);
});

service-worker.js

chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // WARNING! Might be injecting a malicious script!
  document.getElementById("resp").innerHTML = response.farewell;
});