runtime.sendMessage()

翻译不完整。 请帮助我们翻译这篇文章！

向你的扩展或其他扩展发送单条消息。
 
如果想发给你自己的扩展，则省略 extensionId 参数。扩展中所有页面的runtime.onMessage将会被触发，除了调用runtime.sendMessage的页面。

 

如果发送给其他扩展，则将参数 extensionId 设置为其他扩展的ID。其他扩展的 runtime.onMessageExternal 将会被触发。

此接口不能给 content script 发消息，如果要给 content script 发消息，请使用 tabs.sendMessage。

这是个异步方法，将返回一个 Promise。

Syntax

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

参数

extensionId可选
string. 若你想要发给不同的扩展，这里传入接收方的扩展ID。The ID of the extension to send the message to. Include this to send the message to a different extension. If the intended recipient has set an ID explicitly using the applications key in manifest.json, then extensionId should have this value. Otherwise it should be have the ID that was generated for the intended recipient.
若此省略此参数，则发送给自己的扩展。
message
any. 任何可以序列化成JSON的东西。
options可选
object.
includeTlsChannelId可选
boolean. Whether the TLS channel ID will be passed into runtime.onMessageExternal for processes that are listening for the connection event.
toProxyScript可选
boolean. Must be True if the message is intended for a PAC file loaded using the proxy API.

根据给出的参数不同，API遵循如下规则：

  • 只有1个参数：将会被当做 message 发送给自己的扩展。
  • 有2个参数：
    • 若第二个参数符合下面的规则，将会被当做 (message, options)，将消息发送给自己的扩展：
      1. 一个合法的配置对象（也就是说这个对象只包含options参数支持的属性）
      2. null
      3. undefined
    • 否则，将会被当做 (extensionId, message)。消息将会给发送给 extensionId 指定ID的扩展
  • 有3个参数：将会被当做 (extensionId, message, options). 消息将会给发送给 extensionId 指定ID的扩展

在Firefox 55之前，只给出2个参数时，规则会有所不同：
Under the old rules, if the first argument was a string, it was treated as the extensionId, with the message as the second argument. This meant that if you called sendMessage() with arguments like ("my-message", {}), then it would send an empty message to the extension identified by "my-message". Under the new rules, with these arguments you would send the message "my-message" internally, with an empty options object.

Return value

返回一个 Promise。若接收方响应，Promise将会变为 fulfilled 并且返回接收方响应的JSON对象（数字、字符串、数组、true/false都是合法的JSON对象）。否则，Promise会变为 fulfilled 但是不返回任何参数。如果发生了连接错误，Promise将会变为 rejected 并返回一个错误消息。

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
sendMessageChrome Full support 26Edge Full support 14
Notes
Full support 14
Notes
Notes `runtime.onMessage` listeners in extension views receive the messages they sent.
Firefox Full support 45Opera Full support 15Firefox Android Full support 48

Legend

Full support  
Full support
See implementation notes.
See implementation notes.

Examples

Here's a content script that sends a message to the background script when the user clicks the content window. The message payload is {greeting: "Greeting from the content script"}, and the sender also expects to get a response, which is handled in the handleResponse function:

// 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) {
  var sending = browser.runtime.sendMessage({
    greeting: "Greeting from the content script"
  });
  sending.then(handleResponse, handleError);  
}

window.addEventListener("click", notifyBackgroundPage);

The corresponding background script looks like this:

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log("Message from the content script: " +
    request.greeting);
  sendResponse({response: "Response from background script"});
}

browser.runtime.onMessage.addListener(handleMessage);

Example extensions

Acknowledgements

This API is based on Chromium's chrome.runtime API. This documentation is derived from runtime.json in the Chromium code.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.