chrome.events

Descrição

Um Event é um objeto que permite receber notificações quando algo interessante acontece. Este é um Exemplo de uso do evento chrome.alarms.onAlarm para ser notificado sempre que um alarme tiver passado:

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

Como mostra o exemplo, você se registra para receber notificações usando addListener(). O argumento para addListener() é sempre uma função que você define para processar o evento, mas os parâmetros para o dependem do evento que está manipulando. Verificando a documentação de alarms.onAlarm, 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 maior parte do Google Chrome APIs.

Manipuladores de eventos declarativos

Os manipuladores de eventos declarativos fornecem um meio de definir regras que consistem em condições declarativas e ações. As condições são avaliadas no navegador em vez de no mecanismo JavaScript, o que reduz latências de ida e volta e alta eficiência.

Manipuladores de eventos declarativos são usados, por exemplo, na API Declarative Web Request e API Declarative Content. Nesta página, descrevemos os conceitos de todos os eventos declarativos .

Regras

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

var 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 atribuir um identificador a cada regra, o que simplifica cancelar o registro de regras registradas anteriormente e uma prioridade para definir precedências entre regras. As prioridades só são consideradas se as regras entrarem em conflito entre si ou precisarem ser executadas em um ordem. As ações são executadas em ordem decrescente de prioridade das regras.

var 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 acontecem, mas testa se alguma regra registrada tem pelo menos uma condição atendida e é executada as ações associadas a ela. Os objetos de evento que oferecem suporte à 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 pega uma matriz de instâncias de regra como seu primeiro parâmetro e uma função de retorno de chamada que é chamada na conclusão.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

Se as regras forem inseridas, o parâmetro details vai conter uma matriz de regras inseridas aparecendo na mesma ordem que na rule_list transmitida, 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 foi adicionada, e a variável runtime.lastError é definido quando a função de callback é chamada. Cada regra em rule_list precisa conter um identificador que não esteja sendo usado por outra regra ou por um identificador vazio.

Removendo 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 retorno de chamada como segundo parâmetro.

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

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

Como recuperar regras

Para recuperar uma lista das regras registradas no momento, 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.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(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, lembre-se das diretrizes a seguir.

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

Em vez de:

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

preferem:

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

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

Em vez de:

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

preferem:

var 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 as ações assim que uma única condição é atendida. Isso acelera o e reduz o consumo de memória para conjuntos de ações duplicados.

Em vez de:

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

preferem:

  var 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 aos quais interesse. Um listener que usa um filtro não será invocado para eventos que não passarem na filtro, o que torna o código de detecção mais declarativo e eficiente. A necessidade de um service worker não ser acordado para lidar com eventos que não importam.

Os eventos filtrados servem para permitir uma transição do código de filtragem manual como este:

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

para isso:

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

Os eventos são compatíveis com filtros específicos importantes para o evento. A lista de filtros que um evento com suporte serão listados na documentação do evento na coluna "filtros" nesta seção.

Ao fazer a correspondência de URLs (como no exemplo acima), os filtros de eventos oferecem suporte à mesma correspondência de URL capacidades expressas com um events.UrlFilter, exceto a correspondência de esquema e porta.