browser.runtime

Описание

Используйте API chrome.runtime для получения информации о сервис-воркере, получения сведений о манифесте, а также для прослушивания и реагирования на события в жизненном цикле расширения. Вы также можете использовать этот API для преобразования относительных путей URL-адресов в полные URL-адреса.

Большинству членов этого API не требуются никакие разрешения. Это разрешение необходимо для connectNative() , sendNativeMessage() и onNativeConnect .

В следующем примере показано, как объявить разрешение "nativeMessaging" в манифесте:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

Понятия и применение

API среды выполнения предоставляет методы для поддержки ряда областей, которые могут использоваться вашими расширениями:

Передача сообщений
Ваше расширение может взаимодействовать с различными контекстами внутри самого расширения, а также с другими расширениями, используя следующие методы и события: connect() , onConnect , onConnectExternal , sendMessage() , onMessage и onMessageExternal . Кроме того, ваше расширение может передавать сообщения в нативные приложения на устройстве пользователя с помощью connectNative() и sendNativeMessage() .
Доступ к метаданным расширений и платформ.
Эти методы позволяют получить несколько конкретных фрагментов метаданных о расширении и платформе. К этой категории относятся методы getManifest() и getPlatformInfo() .
Управление жизненным циклом расширений и их опциями.
Эти свойства позволяют выполнять некоторые мета-операции с расширением и отображать страницу параметров. К методам и событиям этой категории относятся onInstalled , onStartup , openOptionsPage() , reload() , requestUpdateCheck() и setUninstallURL() .
Вспомогательные утилиты
Эти методы предоставляют такие возможности, как преобразование внутренних представлений ресурсов во внешние форматы. К методам этой категории относится getURL() .
утилиты режима киоска
Эти методы доступны только в ChromeOS и существуют в основном для поддержки киосков. К методам этой категории относятся restart() и restartAfterDelay() .

Поведение распакованного расширения

Когда распакованное расширение перезагружается , это рассматривается как обновление. Это означает, что событие browser.runtime.onInstalled будет срабатывать с причиной "update" . Это относится и к случаям перезагрузки расширения с помощью browser.runtime.reload() .

Варианты использования

Добавить изображение на веб-страницу

Для того чтобы веб-страница могла получить доступ к ресурсу, размещенному на другом домене, она должна указать полный URL-адрес ресурса (например <img src="https://example.com/logo.png"> ). То же самое относится и к включению ресурса расширения на веб-страницу. Два отличия заключаются в том, что ресурсы расширения должны быть доступны как веб-ресурсы , и что обычно за внедрение ресурсов расширения отвечают скрипты контента.

В этом примере расширение добавит logo.png на страницу, в которую внедряется скрипт содержимого , используя runtime.getURL() для создания полного URL-адреса. Но сначала этот ресурс должен быть объявлен как веб-доступный ресурс в манифесте.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

Отправка данных из скрипта контента в сервис-воркер.

Для скриптов контента расширения часто требуются данные, управляемые другой частью расширения, например, сервис-воркером. Подобно двум окнам браузера, открытым на одной и той же веб-странице, эти два контекста не могут напрямую получать доступ к значениям друг друга. Вместо этого расширение может использовать передачу сообщений для координации между этими различными контекстами.

В этом примере скрипту контента требуются данные от сервис-воркера расширения для инициализации пользовательского интерфейса. Чтобы получить эти данные, он передает сервис-воркеру сообщение get-user-data определенное разработчиком, и тот отвечает копией информации о пользователе.

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Соберите отзывы об удалении.

Многие расширения используют опросы после удаления, чтобы понять, как расширение может лучше удовлетворять потребности пользователей и повысить уровень удержания. В следующем примере показано, как добавить эту функциональность.

background.js:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Примеры

Дополнительные примеры использования API среды выполнения см. в демонстрационном примере Manifest V3 - Web Accessible Resources .

Типы

ContextFilter

Chrome 114+

Фильтр для сопоставления с определенными контекстами расширения. Соответствующие контексты должны соответствовать всем указанным фильтрам; любой неуказанный фильтр соответствует всем доступным контекстам. Таким образом, фильтр `{}` будет соответствовать всем доступным контекстам.

Характеристики

  • contextIds

    строка[] необязательный

  • contextTypes

    ContextType [] необязательный

  • documentIds

    строка[] необязательный

  • documentOrigins

    строка[] необязательный

  • documentUrls

    строка[] необязательный

  • frameIds

    число[] необязательно

  • инкогнито

    логический необязательный

  • tabIds

    число[] необязательно

  • windowIds

    число[] необязательно

ContextType

Chrome 114+

Перечисление

"ТАБ"
Указывает тип контекста в виде вкладки.

"НЕОЖИДАННО ВОЗНИКНУТЬ"
Указывает тип контекста как всплывающее окно расширения.

"ФОН"
Указывает тип контекста как сервисный работник.

"OFFSCREEN_DOCUMENT"
Указывает тип контекста как документ, находящийся за пределами видимой области экрана.

"БОКОВАЯ ПАНЕЛЬ"
Указывает тип контекста в виде боковой панели.

"ИНСТРУМЕНТЫ_РАЗРАБОТЧИКА"
Указывает тип контекста как инструменты разработчика.

ExtensionContext

Chrome 114+

Контекст, содержащий контент расширения.

Характеристики

  • контекстId

    нить

    Уникальный идентификатор для данного контекста

  • contextType

    ContextType

    Это соответствует определенному типу контекста.

  • documentId

    строка необязательный

    UUID документа, связанного с данным контекстом, или undefined, если данный контекст размещен не в документе.

  • documentOrigin

    строка необязательный

    Источник документа, связанного с данным контекстом, или не определен, если контекст не размещен в документе.

  • documentUrl

    строка необязательный

    URL-адрес документа, связанного с данным контекстом, или undefined, если контекст не размещен в документе.

  • frameId

    число

    Идентификатор фрейма для данного контекста или -1, если данный контекст не размещен во фрейме.

  • инкогнито

    логический

    Связан ли данный контекст с профилем инкогнито.

  • tabId

    число

    Идентификатор вкладки для данного контекста или -1, если данный контекст не размещен во вкладке.

  • windowId

    число

    Идентификатор окна для данного контекста или -1, если данный контекст не размещен в окне.

MessageSender

Объект, содержащий информацию о контексте скрипта, отправившего сообщение или запрос.

Характеристики

  • documentId

    строка необязательный

    Chrome 106+

    UUID документа, открывшего соединение.

  • жизненный цикл документа

    строка необязательный

    Chrome 106+

    Жизненный цикл документа, открывшего соединение на момент создания порта. Обратите внимание, что состояние жизненного цикла документа могло измениться с момента создания порта.

  • frameId

    число необязательно

    Кадр , установивший соединение. 0 для кадров верхнего уровня, положительное значение для дочерних кадров. Это значение будет установлено только при установке tab .

  • идентификатор

    строка необязательный

    Идентификатор расширения, открывшего соединение, если таковое имелось.

  • нативное приложение

    строка необязательный

    Chrome 74+

    Название нативного приложения, установившего соединение, если таковое имелось.

  • источник

    строка необязательный

    Chrome 80+

    Источник страницы или фрейма, открывшего соединение. Он может отличаться от свойства URL (например, about:blank) или быть непрозрачным (например, изолированные iframe). Это полезно для определения того, можно ли доверять источнику, если это невозможно сразу определить по URL.

  • вкладка

    Вкладка ( необязательно)

    Свойство tabs.Tab указывает, какая вкладка открыла соединение, если таковая имеется. Это свойство будет присутствовать только в том случае, если соединение было открыто из вкладки (включая скрипты контента) и только если получателем является расширение, а не приложение.

  • tlsChannelId

    строка необязательный

    Идентификатор TLS-канала страницы или фрейма, открывшего соединение, если это запрошено расширением и если он доступен.

  • url

    строка необязательный

    URL страницы или фрейма, открывшего соединение. Если отправитель находится во фрейме, будет указан URL фрейма, а не URL страницы, на которой он размещен.

OnInstalledReason

Chrome 44+

Причина отправки данного сообщения.

Перечисление

"установить"
Указывает в качестве причины события установку.

"обновлять"
Указывается причина события как обновление расширения.

"chrome_update"
Указывает в качестве причины события обновление Chrome.

"shared_module_update"
Указывается причина события как обновление общего модуля.

OnRestartRequiredReason

Chrome 44+

Причина отправки события. 'app_update' используется, когда перезапуск необходим из-за обновления приложения до более новой версии. 'os_update' используется, когда перезапуск необходим из-за обновления браузера/ОС до более новой версии. 'periodic' используется, когда система работает дольше разрешенного времени безотказной работы, установленного в корпоративной политике.

Перечисление

"app_update"
Указывает в качестве причины события обновление приложения.

"os_update"
Указывает в качестве причины события обновление операционной системы.

"периодический"
Указывается причина события: периодический перезапуск приложения.

PlatformArch

Chrome 44+

Архитектура процессора машины.

Перечисление

"рука"
Указывает архитектуру процессора как arm.

"arm64"
Указывает архитектуру процессора как arm64.

"x86-32"
Указывает архитектуру процессора как x86-32.

"x86-64"
Указывает архитектуру процессора как x86-64.

"мипсы"
Указывает архитектуру процессора в формате MIPS.

"mips64"
Указывает архитектуру процессора как mips64.

"riscv64"
Указывает архитектуру процессора как riscv64.

PlatformInfo

Объект, содержащий информацию о текущей платформе.

Характеристики

  • арка

    PlatformArch

    Архитектура процессора машины.

  • nacl_arch

    PlatformNaclArch optional

    Устарело с версии Chrome 149.

    Этот атрибут устарел после полного удаления Native Client.

    Архитектура нативного клиента. На некоторых платформах она может отличаться от архитектуры.

  • Операционная система, на которой работает Chrome.

PlatformNaclArch

Chrome 44+ Устарело с версии Chrome 149

Данный перечисление устарело после полного удаления Native Client.

Архитектура нативного клиента. На некоторых платформах она может отличаться от архитектуры.

Перечисление

"рука"
Указывает архитектуру клиентского приложения как arm.

"x86-32"
Указывается архитектура нативного клиента как x86-32.

"x86-64"
Указывается архитектура нативного клиента как x86-64.

"мипсы"
Указывает архитектуру нативного клиента как MIPS.

"mips64"
Указывает архитектуру нативного клиента как mips64.

PlatformOs

Chrome 44+

Операционная система, на которой работает Chrome.

Перечисление

"мак"
Указывает операционную систему MacOS.

"победить"
Указывает операционную систему Windows.

"андроид"
Указывает операционную систему Android.

"кросс"
Указывает операционную систему Chrome.

"линук"
Указывает операционную систему Linux.

"openbsd"
Указывает операционную систему OpenBSD.

Port

Объект, обеспечивающий двустороннюю связь с другими страницами. Дополнительную информацию см. в разделе «Долгосрочные соединения» .

Характеристики

  • имя

    нить

    Имя порта, указанное в вызове функции runtime.connect .

  • onDisconnect

    Событие<functionvoidvoid>

    Событие срабатывает при отключении порта от другого конца (концов). Если отключение порта произошло из-за ошибки, может быть установлено значение runtime.lastError . Если порт закрыт из-за отключения , то это событие срабатывает только на другом конце. Это событие срабатывает не более одного раза (см. также Время жизни порта ).

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

    (callback: function) => {...}