runtime.onMessage

برخی از موارد مورد استفاده برای مثال:

• در یک content script ، برای گوش دادن به پیام های background script.
• در یک background script ، برای گوش دادن به پیام های content script
• در یک صفحه options page یا popup script, برای گوش دادن به پیام هایbackground script.
• در یک background script, برای گوش دادن به پیام های options page یا popup script.

برای ارسال پیام که توسط onMessage() listener, از runtime.sendMessage() (en-US) یا (برای ارسال پیام به یک content script) tabs.sendMessage() (en-US).

همراه با message خود, به listener منتقل می شود:

• یک شیء فرستنده که جزئیاتی درباره فرستنده پیام می دهد.
• یک تابع ()sendResponse که می تواند برای ارسال پاسخ به فرستنده استفاده شود.

شما می توانید با فراخوانی تابع ()sendResponse در listener خود. مثالی را ببینید.

برای ارسال  response ناهمزمان, دو گزینه وجود دارد:

• رویداد listener را  true برگردانید. این کار باعث می شود تابع ()sendResponse پس از بازگشت listener معتبر باشد, بنابراین میتوانید بعدأ آن را صدا بزنید. مثالی را ببینید.
• return a Promise from the event listener, and resolve when you have the response (or reject it in case of an error). See an example.

browser.runtime.onMessage.addListener(listener)
browser.runtime.onMessage.removeListener(listener)
browser.runtime.onMessage.hasListener(listener)

رویکردها سه تابع دارند:

addListener(listener)

به این رویداد یک listener اضلفه می کند.

removeListener(listener)

listening به این رویداد را متوقف می کند. یک listener دلیلی است برای حذف listener.

hasListener(listener)

بررسی می کند که حداقل یک listener برای این رویداد ثبت شده باشد. اگر listening وجود داشت true برمیگرداند, در غیر این صورت false را بر میگرداند.

listener

یک تابع برگشتی که هنگام وقوع این رویداد فراخوانی می شود. به دلایل زیر این تابع پاس داده می شود:

message

object. خود پیام است. این یک شیء با قابلیت JSON-ifiable است.

sender

یک runtime.MessageSender (en-US) شیء به نمایندگی از فرستنده پیام.

sendResponse

یک تابع برای صدا زدن, حداکثر یک بار, برای ارسال پاسخ به پیام. این تابع یک آرگومان واحد را شامل می شود, که ممکن است هر شیء با قابلیت JSON باشد. این آرگومان به فرستنده پیام ارسال می شود.

اگر بیش از یک شنونده  onMessage() در همان سند دارید, پس فقط ممکن است یک نفر پاسخی ارسال کند.

برای ارسال پاسخ همزمان, قبل از بازگشت تابع listener با  sendResponse() تماس بگیرید.

برای ارسال پاسخ به صورت ناهمزمان:

• یا یک رفرنس برای آرگومان ()sendResponse نگه دارید و  مقدار true را برای تابع listener برگردانید. شما می توانید پس از بازگشت تابع listener، با  ()sendResponse تماس بگیرید.
• یا یک Promise را از تابع listener برگردانید و  promise  را در صورت آماده بودن پاسخ حل کنید.  این یک روش ترجیحی است.

تابع  listener می تواند مقدار Boolean یا  Promise را برگرداند.

مهم: با استفاده از تابع async  با  ()addListener تماس نگیرید:

// don't do this
browser.runtime.onMessage.addListener(
  async (data, sender) => {
    if (data.type === 'handle_me') { return 'done'; }
  }
);

این امر باعث می شود شنونده هر پیامی را که دریافت می کند, به طور موثر همه شنوندگان دیگر را از دریافت و پردازش پیام مسدود می کند.

اگر می خواهید رویکردی ناهمزمان داشته باشید, به جای این کار از یک  Promise استفاده کنید, مانند مثال زیر:

browser.runtime.onMessage.addListener(
  (data, sender) => {
    if (data.type === 'handle_me') {
      return Promise.resolve('done');
    }
  }
);

The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

This content script listens for click events on the web page. If the click was on a link, it messages the background page with the target URL:

// content-script.js

window.addEventListener("click", notifyExtension);

function notifyExtension(e) {
  if (e.target.tagName != "A") {
    return;
  }
  browser.runtime.sendMessage({"url": e.target.href});
}

The background script listens for these messages and displays a notification using the notifications API:

// background-script.js

browser.runtime.onMessage.addListener(notify);

function notify(message) {
  browser.notifications.create({
    "type": "basic",
    "iconUrl": browser.extension.getURL("link.png"),
    "title": "You clicked a link!",
    "message": message.url
  });
}

This content script sends a message to the background script when the user clicks on the page. It also logs any response sent by the background script:

// content-script.js

function handleResponse(message) {
  console.log(`background script sent a response: ${message.response}`);
}

function handleError(error) {
  console.log(`Error: ${error}`);
}

function sendMessage(e) {
  const sending = browser.runtime.sendMessage({content: "message from the content script"});
  sending.then(handleResponse, handleError);
}

window.addEventListener("click", sendMessage);

Here is a version of the corresponding background script, that sends a response synchronously, from inside in the listener:

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`content script sent a message: ${request.content}`);
  sendResponse({response: "response from background script"});
}

browser.runtime.onMessage.addListener(handleMessage);

And here is another version which uses Promise.resolve() (en-US):

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`content script sent a message: ${request.content}`);
  return Promise.resolve({response: "response from background script"});
}

browser.runtime.onMessage.addListener(handleMessage);

Here is an alternative version of the background script from the previous example. It sends a response asynchronously after the listener has returned. Note return true; in the listener: this tells the browser that you intend to use the sendResponse argument after the listener has returned.

// background-script.js

function handleMessage(request, sender, sendResponse) {
  console.log(`content script sent a message: ${request.content}`);
  setTimeout(() => {
    sendResponse({response: "async response from background script"});
  }, 1000);
  return true;
}

browser.runtime.onMessage.addListener(handleMessage);

This content script gets the first <a> link on the page and sends a message asking if the link's location is bookmarked. It expects to get a Boolean response (true if the location is bookmarked, false otherwise):

// content-script.js

const firstLink = document.querySelector("a");

function handleResponse(isBookmarked) {
  if (isBookmarked) {
    firstLink.classList.add("bookmarked");
  }
}

browser.runtime.sendMessage({
  url: firstLink.href
}).then(handleResponse);

Here is the background script. It uses bookmarks.search() (en-US) to see if the link is bookmarked, which returns a Promise:

// background-script.js

function isBookmarked(message, sender, response) {
  return browser.bookmarks.search({
    url: message.url
  }).then(function(results) {
    return results.length > 0;
  });
}

browser.runtime.onMessage.addListener(isBookmarked);

If the asynchronous handler doesn't return a Promise, you can explicitly construct a promise. This rather contrived example sends a response after a 1-second delay, using Window.setTimeout():

// background-script.js

function handleMessage(request, sender, sendResponse) {
  return new Promise(resolve => {
    setTimeout( () => {
      resolve({response: "async response from background script"});
    }, 1000);
  });
}

browser.runtime.onMessage.addListener(handleMessage);

• beastify
• content-script-register
• cookie-bg-picker
• devtools-panels
• export-helpers
• find-across-tabs
• imagify
• mocha-client-tests
• notify-link-clicks-i18n
• store-collected-images
• user-script-register
• webpack-modules