chrome.events

Descrição

O namespace chrome.events contém tipos comuns usados por APIs que distribuem eventos para notificar você quando algo interessante acontece.

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.

Tipos

Event

Um objeto que permite a adição e remoção de listeners para um evento do Chrome.

Propriedades

  • addListener

    void

    Registra um callback de listener de um evento.

    A função addListener tem esta aparência:

    (callback: H) => {...}

    • callback

      H

      Chamado quando ocorre um evento. Os parâmetros dessa função dependem do tipo de evento.

  • addRules

    void

    Registra regras para lidar com eventos.

    A função addRules tem esta aparência:

    (rules: Rule<anyany>[], callback?: function) => {...}

    • regras

      Regra<anyany>[]

      Regras a serem registradas. Elas não substituem as regras registradas anteriormente.

    • callback

      função opcional

      O parâmetro callback tem esta aparência:

      (rules: Rule<anyany>[]) => void

      • regras

        Regra<anyany>[]

        Regras que foram registradas, os parâmetros opcionais são preenchidos com valores.

  • getRules

    void

    Retorna as regras registradas no momento.

    A função getRules tem esta aparência:

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

      string[] opcional

      Se uma matriz for transmitida, apenas as regras com identificadores contidos nessa matriz serão retornadas.

    • callback

      função

      O parâmetro callback tem esta aparência:

      (rules: Rule<anyany>[]) => void

      • regras

        Regra<anyany>[]

        Regras que foram registradas, os parâmetros opcionais são preenchidos com valores.

  • hasListener

    void

    A função hasListener tem esta aparência:

    (callback: H) => {...}

    • callback

      H

      Listener com status de registro que precisa ser testado.

    • retorna

      booleano

      Verdadeiro se o callback estiver registrado no evento.

  • hasListeners

    void

    A função hasListeners tem esta aparência:

    () => {...}

    • retorna

      booleano

      Verdadeiro se alguma escuta de evento estiver registrada para o evento.

  • removeListener

    void

    Cancela o registro de um callback de listener de um evento.

    A função removeListener tem esta aparência:

    (callback: H) => {...}

    • callback

      H

      Listener que não será registrado.

  • removeRules

    void

    Cancela o registro das regras registradas no momento.

    A função removeRules tem esta aparência:

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • ruleIdentifiers

      string[] opcional

      Se uma matriz for transmitida, somente as regras com identificadores contidos nela serão canceladas.

    • callback

      função opcional

      O parâmetro callback tem esta aparência:

      () => void

Rule

Descrição de uma regra declarativa para tratar eventos.

Propriedades

  • corretivas

    qualquer[]

    Lista de ações que serão acionadas se uma das condições for atendida.

  • conditions

    qualquer[]

    Lista de condições que podem acionar as ações.

  • id

    string opcional

    Identificador opcional que permite fazer referência a esta regra.

  • prioridade

    número opcional

    Prioridade opcional desta regra. O padrão é 100.

  • tags

    string[] opcional

    As tags podem ser usadas para anotar regras e realizar operações em conjuntos de regras.

UrlFilter

Filtra URLs para vários critérios. Consulte filtragem de eventos. Todos os critérios diferenciam maiúsculas de minúsculas.

Propriedades

  • cidrBlocks

    string[] opcional

    Chrome 123 ou versões mais recentes

    Corresponde se a parte do host do URL é um endereço IP e está contida em qualquer um dos blocos CIDR especificados na matriz.

  • hostContains

    string opcional

    Faz correspondência se o nome do host do URL contém uma string especificada. Para testar se um componente de nome de host tem o prefixo "foo", use hostContains: ".foo". Corresponde a "www.foobar.com" e "foo.com", porque um ponto implícito é adicionado no início do nome do host. Da mesma forma, hostContains pode ser usado para corresponder ao sufixo do componente ('foo.') e para corresponder exatamente aos componentes ('.foo.'). A correspondência exata e de sufixo para os últimos componentes precisa ser feita separadamente com o uso de hostício, porque nenhum ponto implícito é adicionado ao final do nome do host.

  • hostEquals

    string opcional

    Faz correspondência se o nome do host do URL é igual a uma string especificada.

  • hostPrefix

    string opcional

    Faz correspondência se o nome do host do URL começa com uma string especificada.

  • hostSuffix

    string opcional

    Faz correspondência se o nome do host do URL termina com uma string especificada.

  • originAndPathMatches

    string opcional

    Faz correspondência se o URL sem segmento de consulta e identificador de fragmento corresponde a uma expressão regular especificada. Os números de porta serão retirados do URL se corresponderem ao número de porta padrão. As expressões regulares usam a sintaxe RE2.

  • pathContains

    string opcional

    Faz correspondência se o segmento de caminho do URL contém uma string especificada.

  • pathEquals

    string opcional

    Faz correspondência se o segmento de caminho do URL é igual a uma string especificada.

  • pathPrefix

    string opcional

    Faz correspondência se o segmento de caminho do URL começa com uma string especificada.

  • pathSuffix

    string opcional

    Faz correspondência se o segmento de caminho do URL termina com uma string especificada.

  • ports

    (number | number[])[] opcional

    Corresponde se a porta do URL está contida em alguma das listas de portas especificadas. Por exemplo, [80, 443, [1000, 1200]] corresponde a todas as solicitações na porta 80, 443 e no intervalo 1000-1200.

  • queryContains

    string opcional

    Faz correspondência se o segmento de consulta do URL contém uma string especificada.

  • queryEquals

    string opcional

    Faz correspondência se o segmento de consulta do URL é igual a uma string especificada.

  • queryPrefix

    string opcional

    Faz correspondência se o segmento de consulta do URL começa com uma string especificada.

  • querySuffix

    string opcional

    Faz correspondência se o segmento de consulta do URL termina com uma string especificada.

  • planeja

    string[] opcional

    Faz correspondência se o esquema do URL é igual a qualquer um dos esquemas especificados na matriz.

  • urlContains

    string opcional

    Faz correspondência se o URL (sem identificador de fragmento) contém uma string especificada. Os números de porta serão retirados do URL se corresponderem ao número de porta padrão.

  • urlEquals

    string opcional

    Faz correspondência se o URL (sem identificador de fragmento) é igual a uma string especificada. Os números de porta serão retirados do URL se corresponderem ao número de porta padrão.

  • urlMatches

    string opcional

    Faz correspondência se o URL (sem identificador de fragmento) corresponde a uma expressão regular especificada. Os números de porta serão retirados do URL se corresponderem ao número de porta padrão. As expressões regulares usam a sintaxe RE2.

  • urlPrefix

    string opcional

    Faz correspondência se o URL (sem identificador de fragmento) começa com uma string especificada. Os números de porta serão retirados do URL se corresponderem ao número de porta padrão.

  • urlSuffix

    string opcional

    Faz correspondência se o URL (sem identificador de fragmento) termina com uma string especificada. Os números de porta serão retirados do URL se corresponderem ao número de porta padrão.