chrome.events

Descrição

Conceitos e uso

Um Event é um objeto que permite receber uma notificação quando algo interessante acontecer. Confira um exemplo de como usar o evento chrome.alarms.onAlarm para receber uma notificação sempre que um alarme tiver passado:

chrome.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 para 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ê vê que a função tem um único parâmetro: um objeto alarms.Alarm que tem detalhes sobre o alarme decorrido.

Exemplos de APIs que usam eventos: alarmes, i18n, identidade, tempo de execução. A maioria das APIs do Chrome tem essa função.

Manipuladores de eventos declarativos

Com os manipuladores de eventos declarativos, é possível definir regras que consistem em condições e ações declarativas. As condições são avaliadas no navegador, e não no 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 Declarative Content. Nesta página, descrevemos os conceitos subjacentes 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 das 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

Os objetos de evento podem aceitar regras. Esses objetos de evento não chamam uma função de callback quando os eventos acontecem, mas testam se alguma regra registrada tem pelo menos uma condição atendida e executam as ações associadas a essa regra. Os 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. Ela usa uma matriz de instâncias de regras como o primeiro parâmetro e uma função de callback que é chamada após a conclusão.

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

Se as regras forem inseridas corretamente, o parâmetro details vai conter uma matriz de regras inseridas que aparecem na mesma ordem em que rule_list transmitidas, em que os parâmetros opcionais id e priority foram preenchidos com os valores gerados. Se alguma regra for inválida, por exemplo, por conter 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 retorno de chamada for chamada. Cada regra em rule_list precisa conter um identificador exclusivo que ainda não tenha sido usado por outra regra ou um identificador vazio.

Remover regras

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

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

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

Recuperar regras

Para recuperar uma lista de regras registradas, chame a função getRules(). Ele aceita uma matriz opcional de identificadores de regras 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 para a função callback() se refere a uma matriz de regras, incluindo parâmetros opcionais preenchidos.

Desempenho

Para alcançar o desempenho máximo, lembre-se das diretrizes a seguir.

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 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

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

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

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

const match = new chrome.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 suas ações assim que uma única condição é atendida. Isso acelera a correspondência e reduz o consumo de memória para conjuntos de ações duplicados.

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

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

Eventos filtrados

Os eventos filtrados são um mecanismo que permite aos listeners especificar um subconjunto de eventos em que estão interessados. Um listener que usa um filtro não será invocado para eventos que não passarem pelo filtro, o que torna o código de detecção mais declarativo e eficiente. Um service worker não precisa ser ativado para processar eventos que não importam.

O objetivo dos eventos filtrados é permitir uma transição do código de filtragem manual.

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

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

É possível usar filtros específicos que são significativos para os eventos. A lista de filtros compatíveis com um evento será listada na documentação desse evento na seção "filtros".

Ao corresponder URLs (como no exemplo acima), os filtros de evento 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.