browser.events

Descrição

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

Conceitos e uso

Um Event é um objeto que permite que você receba uma notificação quando algo interessante acontece. Veja um exemplo de como usar o evento browser.alarms.onAlarm para receber notificações sempre que um alarme for acionado:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Como mostra o exemplo, você se inscreve 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 da função dependem do evento que está sendo processado. Ao verificar a documentação de alarms.onAlarm, você pode ver 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: alarms, i18n, identity, runtime. A maioria das APIs do Chrome faz isso.

Manipuladores de eventos declarativos

Os manipuladores de eventos declarativos fornecem um meio de 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 Content Declarative. 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, é possível 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 ser compatíveis com 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 que dão 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 de anúncio, chame a função addRules() do objeto de evento. Ela usa uma matriz de instâncias de regra como 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, o parâmetro details vai conter uma matriz de regras inseridas na mesma ordem que em rule_list, 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 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 ainda não esteja sendo 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 regra como primeiro parâmetro e uma função de callback como segundo parâmetro.

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

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.

Recuperar regras

Para recuperar uma lista de regras registradas, chame a função getRules(). Ela 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 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 as diretrizes abaixo.

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.

em vez de
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);
Prefere
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Dê preferência à correspondência de substrings em vez de expressões regulares em um events.UrlFilter. A correspondência baseada em substring é extremamente rápida.

em vez de
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Prefere
const match = new browser.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 a correspondência e reduz o consumo de memória para conjuntos de ações duplicados.

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

Eventos filtrados

Os eventos filtrados são um mecanismo que permite que os listeners especifiquem 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 são relevantes para ele.

Os eventos filtrados têm como objetivo permitir uma transição do código de filtragem manual.

em vez de
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Prefere
browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

Ao fazer a correspondência de URLs (como no exemplo acima), os filtros de eventos 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.

Tipos

Event

Um objeto que permite adicionar e remover listeners de um evento do Chrome.

Propriedades

  • addListener

    void

    Registra um callback de listener de eventos em um evento.

    A função addListener é semelhante a: 

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

    • callback

      H

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

  • addRules

    void

    Registra regras para processar eventos.

    A função addRules é semelhante a: 

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

    • regras

      Regra<anyany>[]

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

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      (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 é semelhante a: 

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

    • ruleIdentifiers

      string[] opcional

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

    • callback

      função

      O parâmetro callback é semelhante a: 

      (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 é semelhante a: 

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

    • callback

      H

      O listener cujo status de registro será testado.

    • retorna

      booleano

      Verdadeiro se callback estiver registrado no evento.

  • hasListeners

    void

    A função hasListeners é semelhante a: 

    () => {...}

    • retorna

      booleano

      Verdadeiro se houver listeners de eventos registrados para o evento.

  • removeListener

    void

    Cancela o registro de um callback de listener de eventos.

    A função removeListener é semelhante a: 

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

    • callback

      H

      Listener que terá o registro cancelado.

  • removeRules

    void

    Cancela o registro das regras registradas no momento.

    A função removeRules é semelhante a: 

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

    • ruleIdentifiers

      string[] opcional

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

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      () => void

Rule

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

Propriedades

  • actions

    any[]

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

  • condições

    any[]

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

  • ID

    string opcional

    Identificador opcional que permite referenciar essa regra.

  • prioridade

    número optional

    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 de acordo com vários critérios. Consulte filtragem de eventos. Todos os critérios diferenciam maiúsculas de minúsculas.

Propriedades

  • cidrBlocks

    string[] opcional

    Chrome 123+ browser.* desde o Chrome 148

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

  • hostContains

    string opcional

    Corresponde se o nome do host do URL tiver uma string especificada. Para testar se um componente de nome de host tem um prefixo "foo", use hostContains: ".foo". Isso 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 correspondência exata aos componentes (".foo."). A correspondência exata e de sufixo para os últimos componentes precisa ser feita separadamente usando hostSuffix, porque nenhum ponto implícito é adicionado ao final do nome do host.

  • hostEquals

    string opcional

    Corresponde se o nome do host do URL for igual a uma string especificada.

  • hostPrefix

    string opcional

    Corresponde se o nome do host do URL começar com uma string especificada.

  • hostSuffix

    string opcional

    Corresponde se o nome do host do URL terminar com uma string especificada.

  • originAndPathMatches

    string opcional

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

  • pathContains

    string opcional

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

  • pathEquals

    string opcional

    Corresponde se o segmento de caminho do URL for igual a uma string especificada.

  • pathPrefix

    string opcional

    Corresponde se o segmento de caminho do URL começar com uma string especificada.

  • pathSuffix

    string opcional

    Corresponde se o segmento de caminho do URL terminar com uma string especificada.

  • portas

    (número | número[])[] opcional

    Corresponde se a porta do URL estiver contida em qualquer uma das listas de portas especificadas. Por exemplo, [80, 443, [1000, 1200]] corresponde a todas as solicitações nas portas 80, 443 e no intervalo de 1000 a 1200.

  • queryContains

    string opcional

    Corresponde se o segmento de consulta do URL tiver uma string especificada.

  • queryEquals

    string opcional

    Corresponde se o segmento de consulta do URL for igual a uma string especificada.

  • queryPrefix

    string opcional

    Corresponde se o segmento de consulta do URL começar com uma string especificada.

  • querySuffix

    string opcional

    Corresponde se o segmento de consulta do URL terminar com uma string especificada.

  • planeja

    string[] opcional

    Corresponde se o esquema do URL for igual a qualquer um dos esquemas especificados na matriz.

  • urlContains

    string opcional

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

  • urlEquals

    string opcional

    Corresponde se o URL (sem identificador de fragmento) for igual a uma string especificada. Os números de porta serão removidos do URL se corresponderem ao número de porta padrão.

  • urlMatches

    string opcional

    Será acionado se o URL (sem identificador de fragmento) corresponder a uma expressão regular especificada. Os números de porta serão removidos do URL se corresponderem ao número de porta padrão. As expressões regulares usam a sintaxe RE2.

  • urlPrefix

    string opcional

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

  • urlSuffix

    string opcional

    Corresponde se o URL (sem identificador de fragmento) terminar com uma string especificada. Os números de porta serão removidos do URL se corresponderem ao número de porta padrão.