برخی از موارد مورد استفاده برای مثال:
- در یک 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'); } } );
سازگاری مرورگر
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.
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
to see if the link is bookmarked, which returns a bookmarks.search()
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
- 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
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.
// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.