chrome.events

refresh date: 2026-09-25 robots: noindex

Descrição

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

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

Como o exemplo mostra, 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.

Exemplo 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 Declarative Web Request e na API Declarative Content. 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:

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

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

Objetos de evento podem oferecer suporte a 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. 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.

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

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

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

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

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

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(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, siga estas diretrizes.

Registrar e cancelar o registro de regras em massa. Depois de cada registro ou cancelamento de registro, o Chrome precisa atualizar as 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]);

prefer:

var rule1 = {...};
var rule2 = {...};
chrome.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.

Em vez de:

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

prefer:

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 condição é atendida. Isso acelera a correspondência 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]);

prefer:

  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 em que têm 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.

O objetivo dos eventos filtrados é permitir uma transição de um 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 isto:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {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 que um evento aceita vai aparecer na documentação dele, na seção "filters".

Ao corresponder URLs (como no exemplo acima), os filtros de eventos oferecem suporte aos mesmos recursos de correspondência de URL que podem ser expressos com um events.UrlFilter, exceto para correspondência de esquema e porta.