runtime.onMessageExternal

使用此事件监听来自其他扩展或网页的消息。

默认情况下，扩展可以接收来自任何其他扩展的消息。但是，externally_connectable 清单键可用于将通信限制为特定扩展并启用与网站的通信。

要发送由onMessageExternal 监听器接收的消息，请使用 runtime.sendMessage()，并在extensionId 参数中传递接收者的 ID。

除了消息本身之外，监听器还会传递

  • 一个sender 对象，提供有关消息发送者的详细信息
  • 一个sendResponse 函数，监听器可以使用它将响应发送回发送者。

此 API 无法在内容脚本中使用。

语法

js
browser.runtime.onMessageExternal.addListener()
browser.runtime.onMessageExternal.removeListener(listener)
browser.runtime.onMessageExternal.hasListener(listener)

事件具有三个函数

addListener(listener)

为此事件添加监听器。

removeListener(listener)

停止监听此事件。listener 参数是要移除的监听器。

hasListener(listener)

检查是否为此事件注册了listener。如果正在监听，则返回true，否则返回false。

addListener 语法

参数

listener

此事件发生时调用的函数。该函数将传递以下参数

message

object。消息本身。这是一个可 JSON 化的对象。

sender

一个表示消息发送者的 runtime.MessageSender 对象。

sendResponse

一个最多调用一次的函数，用于向消息发送响应。该函数接受一个参数，该参数可以是任何可 JSON 化的对象。此参数将传递回消息发送者。

如果在同一文档中有多个onMessageExternal 监听器，则只有一个可以发送响应。

要同步发送响应，请在监听器函数返回之前调用sendResponse。要异步发送响应，请执行以下操作之一

  • 保留对sendResponse 参数的引用，并从监听器函数返回true。然后，您可以在监听器函数返回后调用sendResponse。
  • 从监听器函数返回一个 Promise，并在响应准备就绪时解析该 promise。

浏览器兼容性

BCD 表仅在启用 JavaScript 的浏览器中加载。

示例

在此示例中，扩展“[email protected]”向扩展“[email protected]”发送消息

js
// sender: browser.runtime.id === "[email protected]"

// Send a message to the extension whose ID is "[email protected]"
browser.runtime.sendMessage("[email protected]", "my message");
js
// recipient: browser.runtime.id === "[email protected]"

function handleMessage(message, sender) {
  // check that the message is from "[email protected]"
  if (sender.id === "[email protected]") {
    // process message
  }
}

browser.runtime.onMessageExternal.addListener(handleMessage);

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