Événements dans les service workers

Les service workers d'extension sont compatibles avec les événements standard des service workers et avec de nombreux événements des API d'extension. Cette section décrit les éléments disponibles et fournit des conseils pour les utiliser.

Déclarer des événements d'extension

Les gestionnaires d'événements dans les service workers doivent être déclarés dans le champ d'application global. Cela signifie qu'ils doivent se trouver au niveau supérieur du script et ne pas être imbriqués dans des fonctions. Cela garantit qu'ils sont enregistrés de manière synchrone lors de l'exécution initiale du script, ce qui permet à Chrome de distribuer des événements au service worker dès son démarrage. Exemple :

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
  browser.action.onClicked.addListener(handleActionClick);
});

browser.action.onClicked.addListener(handleActionClick);

browser.storage.local.get(["badgeText"], ({ badgeText }) => {
  browser.action.setBadgeText({ text: badgeText });
});

Événements courants

Les service workers d'extension sont compatibles avec les événements dans des API spécifiques. Vous trouverez ci-dessous quelques exemples courants. Notez que certaines de ces API nécessitent des autorisations pour être utilisées, et que d'autres peuvent comporter des événements, des méthodes ou des propriétés qui ne sont pas disponibles dans toutes les versions de Chrome. Pour en savoir plus, consultez la documentation de l'API associée, en particulier les événements, les méthodes ou les propriétés que vous souhaitez utiliser.

browser.action

Déclenché en réponse à une interaction de l'utilisateur avec l'icône de la barre d'outils de votre extension, que cette action concerne une page (onglet) spécifique ou l'ensemble de l'extension.

browser.management

Fournit des événements liés à l'installation, à la désinstallation, à l'activation et à la désactivation des extensions.

browser.notifications

Fournit des événements liés à l'interaction de l'utilisateur avec les notifications système générées par l'extension.

browser.permissions

Indique quand les autorisations d'extension sont accordées ou révoquées par l'utilisateur.

browser.runtime

Fournit des événements liés au cycle de vie de l'extension, des messages envoyés par d'autres parties de l'extension et une notification d'une extension ou d'une mise à jour Chrome disponibles.

browser.storage.onChanged

Déclenché chaque fois qu'un objet StorageArea est effacé ou que la valeur d'une clé est modifiée ou définie. Notez que chaque instance StorageArea possède son propre événement onChanged.

browser.webNavigation

Fournit des informations sur l'état des demandes de navigation en cours.

Filtres

Pour limiter les événements à un cas d'utilisation spécifique ou éliminer les appels d'événements inutiles, utilisez des API compatibles avec les filtres d'événements. Par exemple, prenons l'exemple d'une extension qui écoute l'événement tabs.onUpdated pour détecter quand un utilisateur accède à un site Web spécifique. Cet événement sera appelé à chaque navigation dans chaque onglet. Utilisez plutôt webNavigation.onCompleted avec un filtre. Exemple :

const filter = {
  url: [
    {
      urlMatches: 'https://www.google.com/',
    },
  ],
};

browser.webNavigation.onCompleted.addListener(() => {
  console.info("The user has loaded my favorite website!");
}, filter);

Événements Web Service Worker

Les service workers d'extension sont compatibles avec plus que les événements de cycle de vie décrits ailleurs.

ServiceWorkerGlobal.fetch

Déclenché lorsque des éléments sont récupérés à partir du package d'extension ou lorsque fetch() et XMLHttpRequest() sont appelés à partir d'un script d'extension ou de fenêtre pop-up. (Les appels provenant de scripts de contenu ne sont pas interceptés par le gestionnaire fetch du service worker.) Dans ce dernier cas, vous devrez ajouter les URL des pages que vous souhaitez récupérer à la clé "host_permissions" dans le fichier manifest.json.

ServiceWorkerGlobal.message

Le transfert de messages du service worker est disponible en plus du transfert de messages de l'extension, mais les deux systèmes ne sont pas interopérables. Cela signifie que les messages envoyés à l'aide de sendMessage() (disponible à partir de plusieurs API d'extension) ne sont pas interceptés par les gestionnaires de messages du service worker. De même, les messages envoyés à l'aide de postMessage() ne sont pas interceptés par les gestionnaires de messages d'extension. Les deux types de gestionnaires de messages (ServiceWorkerGlobal.message et browser.runtime.onMessage) sont compatibles avec les service workers d'extension.

Vous devez privilégier la messagerie d'extension, sauf si vous avez une raison spécifique d'utiliser la messagerie Service Worker.