runtime.sendMessage()
向你的扩展或其他扩展中的事件监听器发送一条消息。
如果想发给你自己的扩展,则省略 extensionId
参数。扩展中除调用 runtime.sendMessage
的页面以外的所有页面都会触发 runtime.onMessage
事件。
如果要发送给其他扩展,则将参数 extensionId
设置为其他扩展的 ID。其他扩展的 runtime.onMessageExternal
将会被触发。默认情况下,你的扩展可以与其自身以及其他任何扩展(通过 extensionId
定义)传递消息。但是,可以使用 externally_connectable
来限制与特定扩展的通信。
扩展不能使用此方法给内容脚本发送消息。要给内容脚本发送消息,请使用 tabs.sendMessage
。
这是一个返回 Promise
的异步函数。
备注:你还可以使用基于连接的方法来传递消息。
语法
let sending = browser.runtime.sendMessage(
extensionId, // 可选字符串
message, // 任何值
options, // 可选对象
)
参数
extensionId
可选-
string
。要将消息发送到的扩展的 ID。包含该参数可将消息发送到其他扩展。如果接收方使用 manifest.json 中的 browser_specific_settings 键显式设置了 ID,则extensionId
应该设为该值。否则,它应该是为接收方生成的 ID。如果省略了
extensionId
,则消息会被发送到你自己的扩展。 message
-
any
。可以使用结构化克隆算法序列化的对象。(参见数据克隆算法)。 options
可选-
object
。includeTlsChannelId
可选-
boolean
。是否将 TLS 通道 ID 传递给正在监听连接事件的进程的runtime.onMessageExternal
。只有基于 Chromium 的浏览器支持此选项。
根据给出的参数不同,API 有时并不明确。此时会使用以下规则:
-
只有 1 个参数:为要发送的消息,且该消息会在内部传递。
-
有 2 个参数:
-
若第二个参数符合下面的规则,则参数将会被解释为
(message, options)
,且消息会在内部传递:- 一个有效的
options
对象(也就是说,它是一个仅包含浏览器支持的options
属性的对象) - null
- undefined
- 一个有效的
-
否则,参数将会被解释为
(extensionId, message)
。消息将会发送给由extensionId
标识的扩展。
-
-
有 3 个参数:将会被解释为
(extensionId, message, options)
。消息将会给发送给由extensionId
标识的扩展。
注意,在 Firefox 55 之前,2 个参数的情况下的规则是不同的。在旧规则下,如果第一个参数是字符串,则将其视为 extensionId
,第二个参数作为消息。这意味着如果你使用 ("my-message", {})
这样的参数调用 sendMessage()
,那么它将向标识为“my-message”的扩展发送空消息。根据新规则,使用这样的参数,将会是在带有一个空的 options 对象的情况下,在内部发送消息“my-message”。
返回值
一个 Promise
。若接收方发送了响应,Promise 将会兑现为该响应。否则,它将不带任何参数兑现。如果连接到扩展时发生了错误,则 Promise 将以一个错误消息拒绝。
浏览器兼容性
BCD tables only load in the browser
示例
这是一个内容脚本,当用户点击内容窗口时,会向后台脚本发送一条消息。消息载荷是 {greeting: "来自内容脚本的问候"}
,发送者还期望得到一个响应,该响应在 handleResponse
函数中处理:
// content-script.js
function handleResponse(message) {
console.log(`来自后台脚本的消息:${message.response}`);
}
function handleError(error) {
console.log(`错误:${error}`);
}
function notifyBackgroundPage(e) {
const sending = browser.runtime.sendMessage({
greeting: "来自内容脚本的问候",
});
sending.then(handleResponse, handleError);
}
window.addEventListener("click", notifyBackgroundPage);
对应的后台脚本如下所示:
// background-script.js
function handleMessage(request, sender, sendResponse) {
console.log(`内容脚本发送了一条消息:${request.greeting}`);
sendResponse({ response: "来自后台脚本的响应" });
}
browser.runtime.onMessage.addListener(handleMessage);
备注:对于 Firefox 附加组件,建议使用返回 Promise
的方法,而不是使用 sendResponse()
。使用 Promise 的示例可在 runtime.onMessage
监听器的“示例”小节中找到。
示例扩展
- content-script-register
- devtools-panels
- export-helpers
- find-across-tabs
- mocha-client-tests
- notify-link-clicks-i18n
- store-collected-images
- user-script-register
- webpack-modules
备注:此 API 基于 Chromium 的 chrome.runtime
API。本文档源自 Chromium 代码中的 runtime.json
。