Eventos em service workers

Os service workers de extensão são compatíveis com eventos padrão e 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 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 para o service worker assim que ele for iniciado. Exemplo:

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

Eventos comuns

Os service workers de extensão oferecem suporte a eventos em APIs específicas. Alguns exemplos comuns são descritos a seguir. 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 mais detalhes, consulte a documentação da API vinculada, principalmente os eventos, métodos ou propriedades que você quer usar.

browser.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 (guia) específica ou para toda a extensão.

browser.management

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

browser.notifications

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

browser.permissions

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

browser.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.

browser.storage.onChanged

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

browser.webNavigation

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

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 escuta 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 de todas as guias. Em vez disso, use webNavigation.onCompleted com um filtro. Exemplo:

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

browser.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 do que os eventos de ciclo de vida 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. As chamadas de scripts de conteúdo não são interceptadas pelo manipulador fetch do service worker. Nos últimos casos, é necessário adicionar os URLs das páginas que você quer buscar à chave "host_permissions" em manifest.json.

ServiceWorkerGlobal.message

A transmissão de mensagens do service worker 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 service worker. Da mesma forma, as mensagens enviadas usando postMessage() não são interceptadas por manipuladores de mensagens de extensão. Os dois tipos de manipuladores de mensagens (ServiceWorkerGlobal.message e browser.runtime.onMessage) são compatíveis com service workers de extensão.

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