runtime.sendMessage()

向扩展内或其他扩展内的事件监听器发送单条消息。

如果发送给你的扩展，请省略 extensionId 参数。 runtime.onMessage 事件将在你的扩展中的每个页面触发，除了调用 runtime.sendMessage 的框架。

如果发送给其他扩展，请包含 extensionId 参数，并将其设置为其他扩展的 ID。 runtime.onMessageExternal 将在其他扩展中触发。默认情况下，你的扩展可以与自身以及任何其他扩展（由 extensionId 定义）交换消息。但是，可以使用 externally_connectable 清单键将通信限制为特定扩展。

扩展无法使用此方法向内容脚本发送消息。要向内容脚本发送消息，请使用 tabs.sendMessage。

这是一个返回 Promise 的异步函数。

注意：你也可以使用基于连接的消息传递方法交换消息。

语法

let sending = browser.runtime.sendMessage(
  extensionId,             // optional string
  message,                 // any
  options                  // optional object
)

参数

extensionId 可选

string。要向其发送消息的扩展的 ID。包含此内容以向其他扩展发送消息。如果目标接收者使用 manifest.json 中的 browser_specific_settings 键显式设置了 ID，则 extensionId 应具有该值。否则，它应具有为目标接收者生成的 ID。

如果省略 extensionId，则消息将发送到你的扩展。

message

any。可以进行结构化克隆序列化（请参阅数据克隆算法）的对象。

options 可选

object.

includeTlsChannelId 可选

boolean。是否将 TLS 通道 ID 传递到 runtime.onMessageExternal，用于正在监听连接事件的进程。

此选项仅在基于 Chromium 的浏览器中受支持。

根据给定的参数，此 API 有时会变得模棱两可。使用以下规则：

如果给定一个参数，则它是要发送的消息，并且消息将被内部发送。
如果给定两个参数
- 参数被解释为 (message, options)，并且消息被内部发送，如果第二个参数是以下任何一个
  1. 有效的 options 对象（这意味着它是一个仅包含浏览器支持的 options 属性的对象）
  2. null
  3. undefined
- 否则，参数被解释为 (extensionId, message)。消息将被发送到由 extensionId 标识的扩展。
如果给定三个参数，参数被解释为 (extensionId, message, options)。消息将被发送到由 extensionId 标识的扩展。

请注意，在 Firefox 55 之前，在 2 个参数的情况下，规则有所不同。在旧规则下，如果第一个参数是字符串，则它被视为 extensionId，并将消息作为第二个参数。这意味着，如果你使用类似 ("my-message", {}) 的参数调用 sendMessage()，那么它将向由 "my-message" 标识的扩展发送一条空消息。在新规则下，使用这些参数，你将使用空选项对象将消息 "my-message" 内部发送。

// 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) {
  const 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(`A content script sent a message: ${request.greeting}`);
  sendResponse({ response: "Response from background script" });
}

browser.runtime.onMessage.addListener(handleMessage);

注意：建议使用 Promise 来替换 sendResponse()，作为 Firefox 附加组件的推荐方法。在示例部分中的 runtime.onMessage 监听器中提供了使用 Promise 的示例。

扩展示例

注意：此 API 基于 Chromium 的 chrome.runtime API。此文档源自 Chromium 代码中的 runtime.json。

runtime.sendMessage()

语法

参数

返回值

浏览器兼容性

示例

扩展示例