chrome.runtime

Описание

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

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

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

манифест.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() ` .

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

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

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

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

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

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

манифест.json:

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

контент.js: 

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

Отправка данных из сценария содержимого сервисному работнику

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

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

контент.js:

// 1. Send a message to the service worker requesting the user's data
chrome.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);
});

сервис-worker.js: 

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

chrome.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);
  }
});

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

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

фон.js: 

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

Примеры

Дополнительные примеры API среды выполнения см. в демонстрации «Манифест V3 — доступные веб-ресурсы» .

Типы

ContextFilter

Хром 114+

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

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

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

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

  • типы контекста

    КонтекстТип [] необязательно

  • идентификаторы документов

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

  • DocumentOrigins

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

  • URL-адреса документов

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

  • идентификаторы фреймов

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

  • инкогнито

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

  • tabIds

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

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

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

ContextType

Хром 114+

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

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

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

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

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

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

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

ExtensionContext

Хром 114+

Содержимое расширения контекстного хостинга.

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

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

    нить

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

  • тип контекста

    Контексттипе

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

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

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

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

  • DocumentOrigin

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

    Происхождение документа связано с этим контекстом или не определено, если контекст не размещен в документе.

  • URL-адрес документа

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

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

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

    число

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

  • инкогнито

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

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

  • идентификатор табуляции

    число

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

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

    число

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

MessageSender

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

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

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

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

    Хром 106+

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

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

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

    Хром 106+

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

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

    номер необязательно

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

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

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

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

  • родное приложение

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

    Хром 74+

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

  • источник

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

    Хром 80+

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

  • вкладка

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

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

  • тлсканалид

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

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

  • URL

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

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

OnInstalledReason

Хром 44+

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

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

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

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

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

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

OnRestartRequiredReason

Хром 44+

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

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

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

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

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

PlatformArch

Хром 44+

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

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

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

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

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

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

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

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

PlatformInfo

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

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

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

  • Собственная клиентская архитектура. На некоторых платформах это может отличаться от Arch.

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

PlatformNaclArch

Хром 44+

Собственная клиентская архитектура. На некоторых платформах это может отличаться от Arch.

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

"рука"
Указывает собственную клиентскую архитектуру как Arm.

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

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

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

"мипс64"
Указывает собственную клиентскую архитектуру mips64.

PlatformOs

Хром 44+

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

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

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

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

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

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

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

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

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

Port

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

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

  • имя

    нить

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

  • onDisconnect

    Событие<functionvoidvoid>

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

    Функция onDisconnect.addListener выглядит так: 

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

    • перезвонить

      функция

      Параметр callback выглядит так: 

      (port: Port) => void

  • onMessage

    Событие<functionvoidvoid>

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

    Функция onMessage.addListener выглядит так: 

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

    • перезвонить

      функция

      Параметр callback выглядит так: 

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

      • сообщение

        любой

      • порт

        Порт

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

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

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

  • отключиться

    пустота

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

    Функция disconnect выглядит так: 

    () => {...}

  • сообщениеСообщение

    пустота

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

    Функция postMessage выглядит так: 

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

    • сообщение

      любой

      Хром 52+

      Сообщение для отправки. Этот объект должен поддерживать формат JSON.

RequestUpdateCheckStatus

Хром 44+

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

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

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

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

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

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

id

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

Тип

нить

lastError

Заполняется сообщением об ошибке в случае сбоя вызова функции API; в противном случае неопределенно. Это определяется только в пределах обратного вызова этой функции. Если возникает ошибка, но доступ runtime.lastError в обратном вызове не осуществляется, в консоль записывается сообщение с указанием функции API, вызвавшей ошибку. Функции API, возвращающие обещания, не устанавливают это свойство.

Тип

объект

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

  • сообщение

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

    Подробности о произошедшей ошибке.

Методы

connect()

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

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

Параметры

  • идентификатор расширения

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

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

  • ConnectInfo

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

    • включитьTlsChannelId

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

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

    • имя

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

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

Возврат

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

Параметры

  • приложение

    нить

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

Возврат

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

getBackgroundPage()

Обещание только на переднем плане
chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (backgroundPage?: Window) => void

    • фонСтраница

      Окно опционально

      Объект JavaScript «окно» для фоновой страницы.

Возврат

  • Обещание<Окно | не определено>

    Хром 99+

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

getContexts()

Обещание Chrome 116+ MV3+
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

Параметры

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

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (contexts: ExtensionContext[]) => void

Возврат

  • Обещание< ExtensionContext []>

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

getManifest()

chrome.runtime.getManifest()

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

Возврат

  • объект

    Подробности манифеста.

getPackageDirectoryEntry()

Обещание только на переднем плане
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

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

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (directoryEntry: DirectoryEntry) => void

    • каталогВход

      DirectoryEntry

Возврат

  • Обещание<DirectoryEntry>

    Хром 122+

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

getPlatformInfo()

Обещать
chrome.runtime.getPlatformInfo(
  callback?: function,
)

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

Параметры

Возврат

  • Хром 99+

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

Параметры

  • путь

    нить

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

Возврат

  • нить

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

openOptionsPage()

Обещать
chrome.runtime.openOptionsPage(
  callback?: function,
)

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

Точное поведение может зависеть от вашего манифеста [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) или [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) или то, что Chrome поддерживает в данный момент. Например, страница может быть открыта в новой вкладке, в chrome://extensions, в приложении или просто перейти на страницу открытых параметров. Это никогда не приведет к перезагрузке страницы вызывающего абонента.

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

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

    Хром 99+

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

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

Обещать
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

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

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

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

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

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (result: object) => void

    • результат

      объект

      Хром 109+

      Объект RequestUpdateCheckResult, который содержит состояние проверки обновлений и любые сведения о результате, если доступно обновление.

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

      • версия

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

        Если обновление доступно, оно содержит версию доступного обновления.

Возврат

  • Обещание<объект>

    Хром 109+

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Обещание Chrome 53+
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

Параметры

  • секунды

    число

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

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

    Хром 99+

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

sendMessage()

Обещать
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

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

Параметры

  • идентификатор расширения

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

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

  • сообщение

    любой

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

  • параметры

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

    • включитьTlsChannelId

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

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

  • перезвонить

    функция необязательна

    Хром 99+

    Параметр callback выглядит так: 

    (response: any) => void

    • ответ

      любой

      Объект ответа JSON, отправленный обработчиком сообщения. Если при подключении к расширению возникает ошибка, обратный вызов будет вызван без аргументов, а runtime.lastError будет установлено сообщение об ошибке.

Возврат

  • Обещание <любое>

    Хром 99+

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

sendNativeMessage()

Обещать
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

Параметры

  • приложение

    нить

    Имя собственного узла обмена сообщениями.

  • сообщение

    объект

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

  • перезвонить

    функция необязательна

    Хром 99+

    Параметр callback выглядит так: 

    (response: any) => void

    • ответ

      любой

      Ответное сообщение, отправленное собственным узлом обмена сообщениями. Если при подключении к собственному узлу обмена сообщениями возникает ошибка, обратный вызов будет вызван без аргументов, а runtime.lastError будет установлено сообщение об ошибке.

Возврат

  • Обещание <любое>

    Хром 99+

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

setUninstallURL()

Обещать
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

Параметры

  • URL

    нить

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

  • перезвонить

    функция необязательна

    Хром 45+

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

    Хром 99+

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

События

onBrowserUpdateAvailable

Устарело
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Пожалуйста, используйте runtime.onRestartRequired .

Запускается, когда доступно обновление Chrome, но не устанавливается сразу, поскольку требуется перезагрузка браузера.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    () => void

onConnect

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (port: Port) => void

onConnectExternal

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (port: Port) => void

onConnectNative

Хром 76+
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (port: Port) => void

onInstalled

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (details: object) => void

    • подробности

      объект

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

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

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

      • предыдущая версия

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

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

      • причина

        OnInstalledReason

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

onMessage

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • сообщение

      любой

    • ОтправитьОтвет

      функция

      Параметр sendResponse выглядит так: 

      () => void

    • возвращает

      логическое | неопределенный

onMessageExternal

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • сообщение

      любой

    • ОтправитьОтвет

      функция

      Параметр sendResponse выглядит так: 

      () => void

    • возвращает

      логическое | неопределенный

onRestartRequired

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

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

Параметры

onStartup

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    () => void

onSuspend

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    () => void

onSuspendCanceled

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    () => void

onUpdateAvailable

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

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (details: object) => void

    • подробности

      объект

      • версия

        нить

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

onUserScriptConnect

Хром 115+ МВ3+
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Запускается, когда соединение осуществляется из пользовательского скрипта из этого расширения.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (port: Port) => void

onUserScriptMessage

Хром 115+ МВ3+
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • сообщение

      любой

    • ОтправитьОтвет

      функция

      Параметр sendResponse выглядит так: 

      () => void

    • возвращает

      логическое | неопределенный