chrome.events

Descrição

Conceitos e uso

Um Event é um objeto que permite receber uma notificação 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((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, no 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:

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

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

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (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 ainda não esteja sendo usado por outra regra ou por 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 retorno de chamada como 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 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.

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

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 substring em vez de expressões regulares em um 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 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.

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

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

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.