browser.events

Descrição

Conceitos e uso

Um Event é um objeto que permite receber notificações quando algo interessante acontece. Confira um exemplo de como usar o evento browser.alarms.onAlarm para receber uma notificação sempre que um alarme expirar:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Como mostrado no exemplo, você se registra para receber notificações usando addListener(). O argumento de addListener() é sempre uma função definida para processar o evento, mas os parâmetros da função dependem do evento que você está processando. Ao verificar a documentação de alarms.onAlarm, você pode ver que a função tem um único parâmetro: um objeto alarms.Alarm com detalhes sobre o alarme decorrido.

Exemplos de APIs que usam eventos: alarms, i18n, identity, runtime. A maioria das APIs do Chrome faz isso.

Manipuladores de eventos declarativos

Os manipuladores de eventos declarativos oferecem uma maneira de definir regras que consistem em condições e ações declarativas. As condições são avaliadas no navegador em vez do mecanismo JavaScript, o que reduz as latências de ida e volta e permite uma eficiência muito alta.

Os manipuladores de eventos declarativos são usados, por exemplo, na API Content Declarative. Esta página descreve os conceitos básicos de todos os manipuladores de eventos declarativos.

Regras

A regra mais simples possível consiste em uma ou mais condições e uma ou mais ações:

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Se alguma das condições for atendida, todas as ações serão executadas.

Além de condições e ações, você pode dar a cada regra um identificador, o que simplifica o cancelamento do registro de regras registradas anteriormente, e uma prioridade para definir precedências entre as regras. As prioridades só são consideradas se as regras entrarem em conflito ou precisarem ser executadas em uma ordem específica. As ações são executadas em ordem decrescente de prioridade das regras.

const rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Objetos de evento

Objetos de evento podem oferecer suporte a regras. Esses objetos de evento não chamam uma função de callback quando eventos acontecem, mas testam se alguma regra registrada tem pelo menos uma condição atendida e executam as ações associadas a essa regra. Objetos de evento compatíveis com a API declarativa têm três métodos relevantes: events.Event.addRules(), events.Event.removeRules() e events.Event.getRules().

Adicionar regras

Para adicionar regras, chame a função addRules() do objeto de evento. Ele usa uma matriz de instâncias de regra como primeiro parâmetro e uma função de callback que é chamada quando a ação é concluída.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Se as regras forem inseridas com sucesso, o parâmetro details vai conter uma matriz de regras inseridas na mesma ordem do rule_list transmitido, em que os parâmetros opcionais id e priority foram preenchidos com os valores gerados. Se alguma regra for inválida, por exemplo, porque continha uma condição ou ação inválida, nenhuma das regras será adicionada, e a variável runtime.lastError será definida quando a função de callback for chamada. Cada regra em rule_list precisa conter um identificador exclusivo que não esteja sendo usado por outra regra ou um identificador vazio.

Remover regras

Para remover regras, chame a função removeRules(). Ele aceita uma matriz opcional de identificadores de regra como primeiro parâmetro e uma função de callback como segundo parâmetro.

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

Se rule_ids for uma matriz de identificadores, todas as regras com identificadores listados na matriz serão removidas. Se rule_ids listar um identificador desconhecido, ele será ignorado. Se rule_ids for undefined, todas as regras registradas dessa extensão serão removidas. A função callback() é chamada quando as regras são removidas.

Recuperar regras

Para recuperar uma lista de regras registradas, chame a função getRules(). Ele aceita uma matriz opcional de identificadores de regra com a mesma semântica de removeRules() e uma função de callback.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

O parâmetro details transmitido à função callback() se refere a uma matriz de regras, incluindo parâmetros opcionais preenchidos.

Desempenho

Para alcançar o desempenho máximo, siga estas diretrizes.

Registrar e cancelar o registro de regras em massa. Após cada registro ou cancelamento de registro, o Chrome precisa atualizar as estruturas de dados internas. Essa atualização é uma operação cara.

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Prefira a correspondência de substrings em vez de expressões regulares em um events.UrlFilter. A correspondência baseada em substrings é extremamente rápida.

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

Se houver muitas regras que compartilham as mesmas ações, mescle-as em uma só. As regras acionam as ações assim que uma condição é atendida. Isso acelera a correspondência e reduz o consumo de memória para conjuntos de ações duplicados.

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.declarativeWebRequest.onRequest.addRules([rule]);

Eventos filtrados

Os eventos filtrados são um mecanismo que permite aos listeners especificar um subconjunto de eventos de interesse. Um listener que usa um filtro não é invocado para eventos que não passam pelo filtro, o que torna o código de escuta mais declarativo e eficiente. Um service worker não precisa ser ativado para processar eventos que não são relevantes para ele.

Os eventos filtrados têm como objetivo permitir uma transição do código de filtragem manual.

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Os eventos oferecem suporte a filtros específicos que são relevantes para eles. A lista de filtros compatíveis com um evento está na seção "filters" da documentação dele.

Ao corresponder URLs (como no exemplo acima), os filtros de eventos são compatíveis com os mesmos recursos de correspondência de URL que podem ser expressos com um events.UrlFilter, exceto para correspondência de esquema e porta.