browser.runtime

Описание

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

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

В примере ниже показано, как объявить разрешение "nativeMessaging" в манифесте.

manifest.json:

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

Основные понятия и использование

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

Примеры

Другие примеры использования Runtime API можно найти в демоверсии Manifest V3 – Web Accessible Resources.

Типы

ContextFilter

Chrome 114 и более поздних версий.

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

Свойства

• contextIds

  string[] необязательно

• contextTypes

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

• documentIds

  string[] необязательно

• documentOrigins

  string[] необязательно

• documentUrls

  string[] необязательно

• frameIds

  number[] optional

• инкогнито

  Логическое значение (необязательно)

• tabIds

  number[] optional

• windowIds

  number[] optional

ContextType

Chrome 114 и более поздних версий.

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

"TAB"
Указывает, что тип контекста – вкладка.

"POPUP"
Указывает, что тип контекста – всплывающее окно расширения.

"BACKGROUND"
Указывает, что тип контекста – сервис-воркер.

"OFFSCREEN_DOCUMENT"
Указывает, что тип контекста – документ вне экрана.

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

"DEVELOPER_TOOLS"
Указывает, что тип контекста – инструменты разработчика.

ExtensionContext

Chrome 114 и более поздних версий.

Контекст, в котором размещен контент расширения.

Свойства

• contextId

  string

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

• contextType

  ContextType

  Тип контекста, которому соответствует этот объект.

• documentId

  Строка (необязательно)

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

• documentOrigin

  Строка (необязательно)

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

• documentUrl

  Строка (необязательно)

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

• frameId

  число

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

• инкогнито

  Логическое значение

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

• tabId

  число

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

• windowId

  число

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

ExtensionLoadDetails

Chrome 157+

Сведения о событии загрузки расширения.

Свойства

• previousVersion

  Строка (необязательно)

  Указывает предыдущую версию расширения. Это поле присутствует, только если в поле reason указано значение update или enable. Если в поле reason указано значение update, то в этом поле будет версия расширения до обновления. Если reason – enable, это текущая версия расширения.

• reason

  OnLoadedReason

  Причина отправки этого события.

MessageSender

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

Свойства

• documentId

  Строка (необязательно)

  Chrome 106 и более поздних версий.

  UUID документа, который открыл подключение.

• documentLifecycle

  Строка (необязательно)

  Chrome 106 и более поздних версий.

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

• frameId

  number (необязательно)

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

• id

  Строка (необязательно)

  Идентификатор расширения, которое открыло подключение (если есть).

• nativeApplication

  Строка (необязательно)

  Chrome 74 и более поздних версий.

  Название нативного приложения, которое открыло подключение (если есть).

• происхождение

  Строка (необязательно)

  Chrome 80 и более поздних версий.

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

• табуляция

  Tab необязательный

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

• tlsChannelId

  Строка (необязательно)

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

• url

  Строка (необязательно)

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

OnInstalledReason

Chrome 44 и более поздних версий;

Причина отправки этого события.

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

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

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

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

"shared_module_update"
Причина события – обновление общего модуля.

OnLoadedReason

Chrome 157+

Причина отправки этого события.

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

"install"
Расширение было установлено.

"update"
Расширение было перезагружено после обновления.

browser_update
Браузер был обновлен до новой версии.

enable
Расширение было повторно включено после отключения.

startup
Расширение загружается при запуске браузера.

"reload"
Расширение было перезагружено (например, с помощью chrome.runtime.reload() или вручную пользователем).

OnRestartRequiredReason

Chrome 44 и более поздних версий;

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

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

"app_update"
Причиной события является обновление приложения.

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

"periodic"
Причина события – периодический перезапуск приложения.

PlatformArch

Chrome 44 и более поздних версий;

Архитектура процессора компьютера.

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

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

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

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

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

"mips"
Указывает, что архитектура процессора – mips.

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

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

PlatformInfo

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

Свойства

• arch

  PlatformArch

  Архитектура процессора компьютера.

• nacl_arch

  PlatformNaclArch необязательный

  Поддержка прекращена в Chrome 149

  Этот атрибут больше не поддерживается, поскольку Native Client был полностью удален.

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

• os

  PlatformOs

  Операционная система, в которой запущен Chrome.

PlatformNaclArch

Chrome 44+ Поддержка прекращена в Chrome 149

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

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

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

"arm"
Указывает, что архитектура нативного клиента – arm.

"x86-32"
Указывает, что архитектура Native Client – x86-32.

"x86-64"
Указывает, что архитектура Native Client – x86-64.

"mips"
Указывает, что архитектура Native Client – mips.

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

PlatformOs

Chrome 44 и более поздних версий;

Операционная система, в которой запущен Chrome.

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

"mac"
Операционная система macOS.

"win"
Операционная система Windows.

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

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

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

"openbsd"
Операционная система OpenBSD.

Port

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

Свойства

• name

  string

  Название порта, указанное в вызове runtime.connect.

• onDisconnect

  Event<functionvoidvoid>

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

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

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

  • обратный вызов

    function

    Параметр callback выглядит следующим образом:

    (port: Port) => void

    • порт

      Порт

• onMessage

  Event<functionvoidvoid>

  Это событие запускается, когда postMessage вызывается другим концом порта.

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

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

  • обратный вызов

    function

    Параметр callback выглядит следующим образом:

    (message: any, port: Port) => void

    • Сообщение

      любой

    • порт

      Порт

• отправитель

  MessageSender необязательный

  Это свойство будет присутствовать только в портах, переданных слушателям onConnect, onConnectExternal и onConnectNative.

• отключить

  void

  Немедленно отключите порт. Вызов disconnect() для уже отключенного порта не имеет эффекта. Когда порт отключен, новые события не будут отправляться в этот порт.

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

  () => {...}

• postMessage

  void

  Отправьте сообщение на другой конец порта. Если порт отключен, возникает ошибка.

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

  (message: any) => {...}

  • Сообщение

    любой

    Chrome 52 и более поздних версий;

    Отправляемое сообщение. Этот объект должен быть сериализуемым в JSON.

RequestUpdateCheckStatus

Chrome 44 и более поздних версий;

Результат проверки обновлений.

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

"throttled"
Проверка статуса была ограничена. Это может произойти, если вы несколько раз подряд за короткое время проверили наличие обновлений.

"no_update"
Указывает, что доступных обновлений нет.

"update_available"
Указывает, что доступно обновление.

Свойства

id

Идентификатор расширения или приложения.

Тип

string

lastError

Содержит сообщение об ошибке, если вызов функции API не удался. В противном случае значение не определено. Оно определяется только в области обратного вызова этой функции. Если возникает ошибка, но runtime.lastError не вызывается в обратном вызове, в консоль записывается сообщение с указанием функции API, которая привела к ошибке. Функции API, возвращающие объекты Promise, не задают это свойство.

Тип

Объект

Свойства

• Сообщение

  Строка (необязательно)

  Подробные сведения о возникшей ошибке.

Методы

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

Попытки подключить прослушиватели в расширении (например, на фоновой странице) или другие расширения/приложения. Это полезно для скриптов контента, подключающихся к процессам расширения, для связи между приложениями и расширениями, а также для веб-сообщений. Обратите внимание, что это не подключается ни к каким прослушивателям в скрипте контента. Расширения могут подключаться к скриптам для содержимого, встроенным во вкладки, с помощью tabs.connect.

Параметры

• extensionId

  Строка (необязательно)

  Идентификатор расширения, к которому нужно подключиться. Если этот параметр не указан, будет предпринята попытка подключения к вашему расширению. Обязательно, если сообщения отправляются с веб-страницы для обмена сообщениями в интернете.

• connectInfo

  Объект (необязательно)

  • includeTlsChannelId

    Логическое значение (необязательно)

    Определяет, будет ли идентификатор канала TLS передаваться в onConnectExternal для процессов, ожидающих события подключения.

  • name

    Строка (необязательно)

    Будет передано в onConnect для процессов, которые прослушивают событие подключения.

Возвраты

• Порт

  Порт, через который можно отправлять и получать сообщения. Если расширение не существует, активируется событие onDisconnect порта.

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

Подключается к нативному приложению на хост-машине. Для этого способа требуется разрешение "nativeMessaging". Подробнее о нативном обмене сообщениями…

Параметры

• приложение

  string

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

Возвраты

• Порт

  Порт, через который приложение может отправлять и получать сообщения.

getBackgroundPage()

Только на переднем плане Устарело в Chrome 133

chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

В расширениях MV3 нет фоновых страниц.

Получает объект window JavaScript для фоновой страницы, запущенной в текущем расширении или приложении. Если фоновая страница является страницей событий, система убедится, что она загружена, прежде чем вызывать обратный вызов. Если фоновой страницы нет, возвращается ошибка.

Возвраты

• Promise<Window | undefined>

  Chrome 99 и более поздних версий.

getContexts()

Chrome 116 и более поздних версий MV3 и более поздних версий

chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

Получает информацию об активных контекстах, связанных с этим расширением.

Параметры

• фильтр

  ContextFilter

  Фильтр для поиска подходящих контекстов. Контекст считается соответствующим, если он соответствует всем указанным в фильтре полям. Любое неуказанное поле в фильтре соответствует всем контекстам.

Возвраты

• Promise<ExtensionContext[]>

  Promise, который разрешается с соответствующими контекстами, если таковые имеются.

getManifest()

chrome.runtime.getManifest(): object

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

Возвраты

• Объект

  Сведения о манифесте.

getPackageDirectoryEntry()

Только в активном режиме

chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

Возвращает DirectoryEntry для каталога пакета.

Возвраты

• Promise<DirectoryEntry>

  Chrome 122 и более поздних версий

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

Возвращает информацию о текущей платформе.

Возвраты

• Promise<PlatformInfo>

  Chrome 99 и более поздних версий.

  Promise, который разрешается с информацией о текущей платформе.

getURL()

chrome.runtime.getURL(
  path: string,
): string

Преобразует относительный путь в каталоге установки приложения или расширения в полный URL.

Параметры

• путь

  string

  Путь к ресурсу в приложении или расширении, указанный относительно каталога установки.

Возвраты

• string

  Полный URL ресурса.

getVersion()

Chrome 143 и более поздних версий

chrome.runtime.getVersion(): string

Возвращает версию расширения, указанную в манифесте.

Возвраты

• string

  Версия расширения.

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

Если возможно, откройте страницу настроек расширения.

Точное поведение может зависеть от ключа options_ui или options_page в манифесте или от того, что поддерживает Chrome в данный момент. Например, страница может открываться в новой вкладке, в chrome://extensions, в приложении или просто фокусироваться на открытой странице настроек. Это никогда не приведет к перезагрузке вызывающей страницы.

Если в расширении не объявлена страница настроек или Chrome не удалось создать ее по другой причине, обратный вызов установит lastError.

Возвраты

• Promise<void>

  Chrome 99 и более поздних версий.

reload()

chrome.runtime.reload(): void

Перезагружает приложение или расширение. Этот метод не поддерживается в режиме киоска. Для режима киоска используйте метод chrome.runtime.restart().

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise<object>

Запрашивает немедленную проверку обновлений для этого приложения или расширения.

Важно! Большинству расширений и приложений не нужно использовать этот метод, поскольку Chrome уже выполняет автоматические проверки каждые несколько часов, и вы можете прослушивать событие runtime.onUpdateAvailable без необходимости вызывать requestUpdateCheck.

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

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

Возвраты

• Promise<object>

  Chrome 109 и более поздних версий.

restart()

chrome.runtime.restart(): void

Перезапустите устройство с ChromeOS, когда приложение работает в режиме киоска. В противном случае ничего не происходит.

restartAfterDelay()

Chrome 53 и более поздних версий;

chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

Перезагрузка устройства с ChromeOS, когда приложение работает в режиме киоска, через указанное количество секунд. Если вызвать ее снова до окончания времени, перезагрузка будет отложена. Если вызвать метод со значением -1, перезагрузка будет отменена. В режиме, отличном от режима киоска, это правило не действует. Повторно вызывать этот API может только расширение, которое вызвало его первым.

Параметры

• сек.

  число

  Время ожидания в секундах перед перезагрузкой устройства или -1 для отмены запланированной перезагрузки.

Возвраты

• Promise<void>

  Chrome 99 и более поздних версий.

  Объект Promise, который распознается, когда запрос на перезапуск успешно перенесен.

sendMessage()

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

Отправляет одно сообщение прослушивателям событий в вашем расширении или в другом расширении или приложении. Похоже на runtime.connect, но отправляет только одно сообщение с необязательным ответом. Если сообщение отправляется вашему расширению, событие runtime.onMessage будет запущено в каждом фрейме расширения (кроме фрейма отправителя). Если сообщение отправляется другому расширению, будет запущено событие runtime.onMessageExternal. Обратите внимание, что расширения не могут отправлять сообщения скриптам обработки контента с помощью этого метода. Чтобы отправлять сообщения скриптам контента, используйте tabs.sendMessage.

Параметры

• extensionId

  Строка (необязательно)

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

• Сообщение

  любой

  Отправляемое сообщение. Это сообщение должно быть объектом, который можно преобразовать в JSON.

• Параметры

  Объект (необязательно)

  • includeTlsChannelId

    Логическое значение (необязательно)

    Определяет, будет ли идентификатор канала TLS передаваться в onMessageExternal для процессов, которые прослушивают событие подключения.

Возвраты

• Promise<any>

  Chrome 99 и более поздних версий.

  В Chrome 99 добавлена поддержка Promise для контекстов расширений. При обмене данными между веб-страницей и расширением промисы доступны начиная с Chrome 118.

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

Отправляет одно сообщение нативному приложению. Для этого способа требуется разрешение "nativeMessaging".

Параметры

• приложение

  string

  Название хоста для нативного обмена сообщениями или сведения о цели.

• Сообщение

  Объект

  Сообщение, которое будет передано хосту для нативного обмена сообщениями.

Возвраты

• Promise<any>

  Chrome 99 и более поздних версий.

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

Задает URL, который будет открываться при удалении. Это может использоваться для очистки данных на стороне сервера, проведения аналитики и реализации опросов. Максимальное количество символов – 1023.

Параметры

• url

  string

  URL, который будет открыт после удаления расширения. URL должен начинаться с http: или https:. Если задать пустую строку, то при удалении новая вкладка открываться не будет.

Возвраты

• Promise<void>

  Chrome 99 и более поздних версий.

  Promise, который разрешается, когда задан URL удаления. Если указанный URL недействителен, объект возвращает отказ.

События

onBrowserUpdateAvailable

Поддержка прекращена

chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Используйте runtime.onRestartRequired.

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

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Срабатывает, когда устанавливается подключение из процесса расширения или скрипта контента (с помощью runtime.connect).

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (port: Port) => void

  • порт

    Порт

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

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

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (port: Port) => void

  • порт

    Порт

onConnectNative

Chrome 76 и более поздних версий;

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Срабатывает, когда подключение устанавливается из нативного приложения. Для этого события требуется разрешение "nativeMessaging". Оно поддерживается только в ChromeOS.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (port: Port) => void

  • порт

    Порт

onEnabled

Chrome 155+

chrome.runtime.onEnabled.addListener(
  callback: function,
)

Срабатывает, когда расширение переходит из отключенного состояния во включенное.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  () => void

onExtensionLoaded

Chrome 157+

chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

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

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (details: ExtensionLoadDetails) => void

  • подробные сведения

    ExtensionLoadDetails

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Срабатывает при первой установке расширения, при его обновлении до новой версии и при обновлении Chrome до новой версии.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (details: object) => void

  • подробные сведения

    Объект

    • id

      Строка (необязательно)

      Указывает идентификатор импортированного расширения общего модуля, которое было обновлено. Этот параметр присутствует, только если в поле reason указано значение shared_module_update.

    • previousVersion

      Строка (необязательно)

      Указывает предыдущую версию расширения, которое только что было обновлено. Этот параметр присутствует, только если в поле reason указано значение update.

    • reason

      OnInstalledReason

      Причина отправки этого события.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Срабатывает, когда сообщение отправляется из runtime.sendMessage или tabs.sendMessage.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

  • Сообщение

    любой

  • отправитель

    MessageSender

  • sendResponse

    function

    Параметр sendResponse выглядит следующим образом:

    (response?: any) => void

    • Ответ

      any optional

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

  • Возвращает

    boolean | Promise<any> | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Срабатывает, когда сообщение отправляется из другого расширения (с помощью runtime.sendMessage). Нельзя использовать в скрипте контента.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

  • Сообщение

    любой

  • отправитель

    MessageSender

  • sendResponse

    function

    Параметр sendResponse выглядит следующим образом:

    (response?: any) => void

    • Ответ

      any optional

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

  • Возвращает

    boolean | Promise<any> | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Срабатывает, когда нужно перезапустить приложение или устройство, на котором оно работает. Приложение должно закрыть все свои окна при первой возможности, чтобы перезапуск состоялся. Если приложение не выполняет никаких действий, перезапуск будет принудительно выполнен по истечении 24-часового льготного периода. В настоящее время это событие активируется только для киоск-приложений ChromeOS.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Активируется при первом запуске профиля, в котором установлено это расширение. Это событие не запускается при запуске профиля инкогнито, даже если это расширение работает в режиме инкогнито "разделение".

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Отправляется на страницу события непосредственно перед ее выгрузкой. Это позволяет расширению выполнить очистку. Поскольку страница выгружается, нет гарантии, что асинхронные операции, начатые во время обработки этого события, будут завершены. Если до выгрузки страницы событий произойдет больше действий, будет отправлено событие onSuspendCanceled и страница не будет выгружена.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

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

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

Срабатывает, когда доступно обновление, но оно не устанавливается сразу, потому что приложение запущено. Если вы ничего не предпримете, обновление будет установлено при следующей выгрузке фоновой страницы. Если вы хотите, чтобы оно было установлено раньше, вы можете явно вызвать chrome.runtime.reload(). Если ваше расширение использует постоянную фоновую страницу, фоновая страница, конечно, никогда не выгружается, поэтому, если вы не вызовете chrome.runtime.reload() вручную в ответ на это событие, обновление не будет установлено до следующего перезапуска самого Chrome. Если обработчики не прослушивают это событие, а у расширения есть постоянная фоновая страница, оно ведет себя так, как если бы в ответ на это событие вызывался метод chrome.runtime.reload().

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (details: object) => void

  • подробные сведения

    Объект

    • version

      string

      Номер версии доступного обновления.

onUserScriptConnect

Chrome 115 и более поздних версий MV3 и более поздних версий

chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Активируется, когда пользовательский скрипт из этого расширения устанавливает подключение.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (port: Port) => void

  • порт

    Порт

onUserScriptMessage

Chrome 115 и более поздних версий MV3 и более поздних версий

chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Срабатывает, когда сообщение отправляется из пользовательского скрипта, связанного с тем же расширением.

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • Сообщение

    любой

  • отправитель

    MessageSender

  • sendResponse

    function

    Параметр sendResponse выглядит следующим образом:

    (response?: any) => void

    • Ответ

      any optional

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

  • Возвращает

    boolean | undefined