runtime.onMessage

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

События имеют три функции:

addListener(listener)

Добавляет обработчик к этому событию.

removeListener(listener)

Прекратить прослушивание этого события. Аргумент listener — это обработчик, который нужно удалить.

hasListener(listener)

Проверяет, зарегистрирован ли хотя бы один обработчик для этого события. Возвращает true, если прослушивание активно, false, в противном случае.

listener

Функция обратного вызова, которая будет вызвана при возникновении этого события. Функции будут переданы следующие аргументы:

message

object. Само сообщение. Это сериализуемый объект (см. алгоритм клонирования данных).

sender

Объект runtime.MessageSender, представляющий отправителя сообщения.

sendResponse

Функция, которую нужно вызвать (не более одного раза) для отправки ответа message. Функция принимает один аргумент, который может быть любым сериализуемым объектом (см. алгоритм клонирования данных). Этот аргумент передаётся обратно отправителю сообщения.

Если у вас в одном документе более одного onMessage() обработчика, то только один может отправить ответ.

Для отправки синхронного ответа вызовите sendResponse() перед возвратом функции-обработчика.

Для отправки асинхронного ответа:

• либо сохраните ссылку на аргумент sendResponse() и верните true из функции-обработчика. Тогда вы сможете вызвать sendResponse() после возвращения функции-обработчика.
• либо верните Promise из функции-обработчика и разрешите промис, когда ответ будет готов. Это предпочтительный способ.

Функция listener может возвращать либо булево значение, либо Promise.

Примечание: Если вы передаёте асинхронную функцию в addListener(), обработчик вернёт промис для каждого полученного сообщения, препятствуя ответам других обработчиков:

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

Если вы хотите, чтобы обработчик реагировал только на сообщения определённого типа, вы должны определить обработчик как не-async функцию и возвращать промис только для тех сообщений, на которые обработчик должен отвечать — а в остальных случаях возвращать false или undefined:

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

Этот скрипт содержимого прослушивает события клика на веб-странице. Если клик был по ссылке, он отправляет сообщение на страницу фона с целевым URL:

// content-script.js

window.addEventListener("click", notifyExtension);

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

Скрипт фона прослушивает эти сообщения и отображает уведомление с помощью API notifications:

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

Этот скрипт содержимого отправляет сообщение на скрипт фона, когда пользователь кликает по странице. Он также регистрирует любой ответ, отправленный скриптом фона:

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

Вот версия соответствующего скрипта фона, который отправляет ответ синхронно, внутри обработчика:

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

И вот ещё одна версия, которая использует 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);

Вот альтернативная версия скрипта фона из предыдущего примера. Он отправляет ответ асинхронно после возвращения обработчика. Обратите внимание на return true; в обработчике: это указывает браузеру, что вы намерены использовать аргумент sendResponse после возвращения обработчика.

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

Этот скрипт содержимого получает первую <a> ссылку на странице и отправляет сообщение, спрашивая, занесена ли ссылка в закладки. Он ожидает получить булевый ответ (true если ссылка в закладках, false в противном случае):

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

Вот скрипт фона. Он использует bookmarks.search() для проверки, находится ли ссылка в закладках, что возвращает Promise:

// background-script.js

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

browser.runtime.onMessage.addListener(isBookmarked);

Если асинхронный обработчик не возвращает промис, вы можете явно построить промис. Этот довольно искусственный пример отправляет ответ после задержки в 1 секунду, используя 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