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() یا (برای ارسال پیام به یک content script) tabs.sendMessage().

از ایجاد چندین  onMessage() listeners برای همان نوع پیام خودداری کنید, زیرا نظم چندین listeners will fire تضمین نمی شود.

اگر می خواهید تحویل پیام به یک نقطه پایان خاص را تضمین کنید, از روش مبتنی بر اتصال برای پیام استفاده کنید.

همراه با 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.

بازگشت یک Promise در حال حاضر ترجیح داده می شود, زیرا sendResponse() از مشخصات W3C حذف می شود.

کتابخانه محبوب webextension-polyfill قبلا تابع ()sendResponse را از اجزای آن حذف کرده است.

شما همچنین می توانید از یک روش مبتنی بر اتصال برای تبادل پیام استفاده کنید.

Syntax

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 را بر میگرداند.

addListener syntax

پارامترها

listener

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

message
object. خود پیام است. این یک شیء با قابلیت JSON-ifiable است.
sender
یک runtime.MessageSender شیء به نمایندگی از فرستنده پیام.
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');
    }
  }
);

سازگاری مرورگر

No compatibility data found. Please contribute data for "webextensions.api.runtime.onMessage()" (depth: 1) to the MDN compatibility data repository.

Examples

Simple example

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
  });
}

Sending a synchronous response

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():

// 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);

Sending an asynchronous response using sendResponse

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);

Sending an asynchronous response using a Promise

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() 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);

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.