Eventos em service workers

Os service workers de extensão oferecem suporte a eventos do service worker padrão e a muitos eventos nas APIs de extensão. Esta seção descreve o que está disponível e dá dicas para usá-los.

Declarar eventos de extensão

Os manipuladores de eventos em service workers precisam ser declarados no escopo global, o que significa que devem estar no nível superior do script e não estar aninhados dentro de 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 ao service worker assim que ele for iniciado. Exemplo:

Não recomendado

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

Melhor

chrome.action.onClicked.addListener(handleActionClick);

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

Eventos comuns

Os service workers de extensão oferecem suporte a eventos em APIs específicas. Alguns exemplos comuns são descritos a seguir. Observe que algumas dessas APIs exigem permissões para serem usadas e outras podem ter eventos, métodos ou propriedades que não estão disponíveis em todas as versões do Chrome. Para mais detalhes, consulte a documentação da API vinculada, principalmente os eventos, métodos ou propriedades que você quer usar.

chrome.action

Acionada 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 (guia) ou toda a extensão.

chrome.management

Oferece 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 notificações do sistema geradas pela extensão.

chrome.permissions

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

chrome.runtime

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

chrome.storage.onChanged

Acionado sempre que algum 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 trânsito.

Filtros

Para restringir eventos a casos de uso específicos ou eliminar chamadas de eventos desnecessárias, use APIs compatíveis com filtros de eventos. Por exemplo, considere uma extensão que detecta o evento tabs.onUpdated para detectar quando um usuário navega até um site específico. Esse evento vai 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 service workers de extensão oferecem suporte a mais eventos de ciclo de vida do que os descritos em outro lugar.

ServiceWorkerGlobal.fetch

Disparado quando algo é recuperado do pacote de extensão ou quando fetch() e XMLHttpRequest() são chamados de um script de extensão ou pop-up. Chamadas de scripts de conteúdo não são interceptadas pelo gerenciador fetch do service worker. Nos últimos casos, será necessário adicionar os URLs das páginas que você quer buscar à chave "host_permissions" no manifest.json.

ServiceWorkerGlobal.message

A transmissão de mensagens do service worker está disponível além da transmissão de mensagens de 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 por gerenciadores de mensagens do service worker. Da mesma forma, as mensagens enviadas usando postMessage() não são interceptadas por gerenciadores de mensagens de extensão. Os dois tipos de gerenciadores de mensagens, ou seja, ServiceWorkerGlobal.message e chrome.runtime.onMessage, são compatíveis com os service workers de extensão.

É melhor usar as mensagens de extensão, a menos que você tenha um motivo específico para usar as mensagens do service worker.