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.

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.

Observação:as regras são persistentes em todas as sessões de navegação. Portanto, você deve instalar as regras tempo de instalação da extensão usando o evento runtime.onInstalled. Este evento é também é acionada quando uma extensão é atualizada. Portanto, é necessário limpar os dados das instâncias e registrar novas regras.

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.

em vez de

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

Prefere

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.

em vez de

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

Prefere

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.

em vez de

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

Prefere

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.

em vez de

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

Prefere

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.

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.