Chrome теперь поддерживает стандартизированное пространство имен browser.* (доступно начиная с Chrome 148). Мы постепенно обновляем документацию. Подробнее читайте в нашем руководстве по переходу .

Эта страница переведена с помощью Cloud Translation API.

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.

browser.runtime Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

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

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

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

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

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

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

Примеры

Типы

ContextFilter

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

ContextType

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

ExtensionContext

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

MessageSender

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

OnInstalledReason

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

OnRestartRequiredReason

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

PlatformArch

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

PlatformInfo

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

PlatformNaclArch

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

PlatformOs

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

browser.runtime