Управляйте событиями с помощью фоновых сценариев

Предупреждение: вы просматриваете устаревшую версию этой статьи Manifest V2. Эквивалент MV3 см. в Манифесте V3 — О работниках службы расширения . Интернет-магазин Chrome больше не принимает расширения Manifest V2. Следуйте руководству по миграции Manifest V3 , чтобы преобразовать расширение в Manifest V3.

Расширения — это программы, основанные на событиях, используемые для изменения или улучшения работы браузера Chrome. События — это триггеры браузера, такие как переход на новую страницу, удаление закладки или закрытие вкладки. Расширения отслеживают эти события в своем фоновом сценарии, а затем реагируют указанными инструкциями.

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

• Расширение сначала устанавливается или обновляется до новой версии.
• Фоновая страница прослушивала событие, и событие было отправлено.
• Сценарий содержимого или другое расширение отправляет сообщение.
• Другое представление в расширении, например всплывающее окно, вызывает runtime.getBackgroundPage .

После загрузки фоновая страница будет работать до тех пор, пока она выполняет какое-либо действие, например вызывает API Chrome или отправляет сетевой запрос. Кроме того, фоновая страница не будет выгружаться до тех пор, пока не будут закрыты все видимые представления и все порты сообщений. Обратите внимание, что открытие представления не приводит к загрузке страницы событий, а только предотвращает ее закрытие после загрузки.

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

Регистрация фоновых сценариев

Фоновые сценарии регистрируются в манифесте в поле "background" . Они перечислены в массиве после ключа "scripts" , а "persistent" должно быть указано как false.

{
  "name": "Awesome Test Extension",
  ...
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  ...
}

Для модульного кода можно зарегистрировать несколько фоновых сценариев.

{
    "name": "Awesome Test Extension",
    ...
    "background": {
      "scripts": [
        "backgroundContextMenus.js",
        "backgroundOmniBox.js",
        "backgroundOauth.js"
      ],
      "persistent": false
    },
    ...
  }

Предупреждение. Единственный случай, когда фоновый скрипт остается активным, — это если расширение использует API chrome.webRequest для блокировки или изменения сетевых запросов. API webRequest несовместим с непостоянными фоновыми страницами. По умолчанию для параметра "persistent" установлено значение true.

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

Инициализировать расширение

Прослушайте событие runtime.onInstalled , чтобы инициализировать расширение при установке. Используйте это событие для установки состояния или для однократной инициализации, например контекстного меню .

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

Настройка прослушивателей

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

Слушатели должны быть зарегистрированы синхронно с начала страницы.

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

// This will run when a bookmark is created.
chrome.bookmarks.onCreated.addListener(function() {
  // do something
});

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

chrome.runtime.onInstalled.addListener(function() {
  // ERROR! Events must be registered synchronously from the start of
  // the page.
  chrome.bookmarks.onCreated.addListener(function() {
    // do something
  });
});

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

chrome.runtime.onMessage.addListener(function(message, sender, reply) {
    chrome.runtime.onMessage.removeListener(event);
});

Фильтровать события

Используйте API, поддерживающие фильтры событий , чтобы ограничить прослушиватели теми случаями, которые важны для расширения. Если расширение прослушивает событие tabs.onUpdated , попробуйте вместо этого использовать событие webNavigation.onCompleted с фильтрами, поскольку API вкладок не поддерживает фильтры.

chrome.webNavigation.onCompleted.addListener(function() {
    alert("This is my favorite website!");
}, {url: [{urlMatches : 'https://www.google.com/'}]});

Реагируйте на слушателей

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

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message.data == "setAlarm") {
    chrome.alarms.create({delayInMinutes: 5})
  } else if (message.data == "runLogic") {
    chrome.tabs.executeScript({file: 'logic.js'});
  } else if (message.data == "changeColor") {
    chrome.tabs.executeScript(
        {code: 'document.body.style.backgroundColor="orange"'});
  };
});

Выгрузить фоновые сценарии

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

chrome.storage.local.set({variable: variableInformation});

Если расширение использует передачу сообщений , убедитесь, что все порты закрыты. Фоновый сценарий не будет выгружаться до тех пор, пока все порты сообщений не закроются. Прослушивание события runtime.Port.onDisconnect позволит узнать, когда открытые порты закрываются. Вручную закройте их с помощью runtime.Port.disconnect .

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message == 'hello') {
    sendResponse({greeting: 'welcome!'})
  } else if (message == 'goodbye') {
    chrome.runtime.Port.disconnect();
  }
});

Время жизни фонового сценария можно наблюдать, отслеживая появление и исчезновение записи о расширении в диспетчере задач Chrome.

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

Фоновые сценарии выгружаются самостоятельно через несколько секунд бездействия. Если требуется какая-либо очистка в последнюю минуту, прослушайте событие runtime.onSuspend .

chrome.runtime.onSuspend.addListener(function() {
  console.log("Unloading.");
  chrome.browserAction.setBadgeText({text: ""});
});

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