Eventos em service workers

Os service workers de extensão oferecem suporte a eventos padrão e a muitos eventos nas APIs de extensão. Esta seção descreve o que está disponível e oferece dicas de uso.

Declarar eventos de extensão

Os manipuladores de eventos em service workers precisam ser declarados no escopo global, ou seja, precisam estar no nível superior do script e não podem ser aninhados em funções. Isso garante que eles sejam registrados de forma síncrona na execução inicial do script, o que permite que o Chrome envie eventos para o service worker assim que ele for iniciado. Exemplo:

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

chrome.action.onClicked.addListener(handleActionClick);

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

Eventos comuns

Os workers de serviço de extensão oferecem suporte a eventos em APIs específicas. Confira a seguir alguns exemplos comuns. Algumas dessas APIs exigem permissões para uso, e outras podem ter eventos, métodos ou propriedades que não estão disponíveis em todas as versões do Chrome. Para saber mais, consulte a documentação da API vinculada, principalmente os eventos, métodos ou propriedades que você quer usar.

chrome.action

É acionado em resposta a uma interação do usuário com o ícone da barra de ferramentas da extensão, seja para uma página específica (aba) ou para toda a extensão.

chrome.management

Fornece eventos relacionados à instalação, desinstalação, ativação e desativação de extensões.

chrome.notifications

Fornece eventos relacionados à interação do usuário com as notificações do sistema geradas pela extensão.

chrome.permissions

Indica quando as permissões da extensão são concedidas ou revogadas pelo usuário.

chrome.runtime

Fornece eventos relacionados ao ciclo de vida da extensão, mensagens enviadas de outras partes da extensão e notificação de uma extensão disponível ou atualização do Chrome.

chrome.storage.onChanged

É acionado sempre que qualquer objeto StorageArea é limpo ou quando o valor de uma chave é alterado ou definido. Cada instância de StorageArea tem o próprio evento onChanged.

chrome.webNavigation

Fornece informações sobre o status das solicitações de navegação em voo.

Filtros

Para restringir eventos a um caso de uso específico ou eliminar chamadas de eventos desnecessárias, use APIs que oferecem suporte a filtros de eventos. Por exemplo, considere uma extensão que ouve o evento tabs.onUpdated para detectar quando um usuário navega até um site específico. Esse evento será chamado em todas as navegações em todas as guias. Em vez disso, use webNavigation.onCompleted com um filtro. Exemplo:

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

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

Eventos de service worker da Web

Os workers de serviço de extensão oferecem suporte a mais eventos de ciclo de vida do que os descritos em outros lugares.

ServiceWorkerGlobal.fetch

É acionado quando algo é recuperado do pacote de extensão ou quando fetch() e XMLHttpRequest() são chamados de uma extensão ou um script pop-up. As chamadas de scripts de conteúdo não são interceptadas pelo gerenciador fetch do worker de serviço. Nesses casos, você precisa adicionar os URLs das páginas que quer buscar à chave "host_permissions" no manifest.json.

ServiceWorkerGlobal.message

A transmissão de mensagens do worker de serviço está disponível além da transmissão de mensagens da extensão, mas os dois sistemas não são interoperáveis. Isso significa que as mensagens enviadas usando sendMessage() (disponível em várias APIs de extensão) não são interceptadas pelos manipuladores de mensagens do worker de serviço. Da mesma forma, as mensagens enviadas usando postMessage() não são interceptadas pelos processadores de mensagens de extensão. Ambos os tipos de manipuladores de mensagens, ou seja, ServiceWorkerGlobal.message e chrome.runtime.onMessage, são aceitos em workers de serviço de extensão.

Use mensagens de extensão, a menos que você tenha um motivo específico para usar mensagens de worker de serviço.