O Chrome agora oferece suporte ao namespace browser.* padronizado (disponível no Chrome 148). Estamos atualizando a documentação gradualmente. Leia mais no nosso guia de transição.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 receber notificações quando algo interessante acontece. Confira um exemplo de como usar o evento browser.alarms.onAlarm para receber uma notificação sempre que um alarme expirar:

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

Como mostrado no exemplo, 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.

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 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 Content Declarative. 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:

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

Objetos de evento podem oferecer suporte a regras. Esses objetos de evento não chamam uma função de callback quando 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().

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.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Se as regras forem inseridas com sucesso, 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, 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 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.

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. 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(). 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, siga estas diretrizes.

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

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

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 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 aos listeners especificar um subconjunto de eventos de 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.

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 oferecem suporte a filtros específicos que são relevantes para eles. A lista de filtros compatíveis com um evento está na seção "filters" da documentação dele.

Ao corresponder 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 para um evento do Chrome.

Propriedades

addListener

void

Registra um callback de listener de eventos em um evento.

A função addListener tem esta aparência:
```
(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 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 registradas, e 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, somente as regras com identificadores contidos nela serão retornadas.
- callback
  
  função
  
  O parâmetro callback tem esta aparência:
```
(rules: Rule<anyany>[]) => void
```
  - regras
    
    Regra<anyany>[]
    
    Regras registradas, e os parâmetros opcionais são preenchidos com valores.
hasListener

void

A função hasListener tem esta aparência:
```
(callback: H) => {...}
```
- callback
  
  H
  
  Listener cujo status de registro será testado.
- retorna
  booleano
  
  Verdadeiro se callback estiver registrado no evento.
hasListeners

void

A função hasListeners tem esta aparência:
```
() => {...}
```
- retorna
  booleano
  
  Verdadeiro se algum listener de evento estiver registrado para o evento.
removeListener

void

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

A função removeListener tem esta aparência:
```
(callback: H) => {...}
```
- callback
  
  H
  
  Listener que será cancelado.
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, apenas 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 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 por vários critérios. Consulte filtragem de eventos. Todos os critérios diferenciam maiúsculas de minúsculas.

Propriedades

cidrBlocks

string[] opcional

Chrome 123+

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 contém uma string especificada. Para testar se um componente de nome do host tem o prefixo "foo", use hostContains: ".foo". Isso corresponde a "www.foobar.com" e "foo.com", porque um ponto implícito é adicionado ao 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 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ça com uma string especificada.
hostSuffix

string opcional

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

string opcional

Corresponde 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 são removidos do URL se corresponderem ao número de porta padrão. As expressões regulares usam a sintaxe RE2.
pathContains

string opcional

Corresponde 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ça com uma string especificada.
pathSuffix

string opcional

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

(number | number[])[] optional

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

string opcional

Corresponde se o segmento de consulta do URL contém 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 termina 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

Corresponde se o URL (sem identificador de fragmento) contém uma string especificada. Os números de porta sã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 são removidos do URL se corresponderem ao número de porta padrão.
urlMatches

string opcional

Corresponde se o URL (sem identificador de fragmento) corresponder a uma expressão regular especificada. Os números de porta sã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 sã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 são removidos do URL se corresponderem ao número de porta padrão.

browser.events Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Conceitos e uso

Manipuladores de eventos declarativos

Regras

Objetos de evento

Adicionar regras

Remover regras

Recuperar regras

Desempenho

Eventos filtrados

Tipos

Event

Propriedades

Rule

Propriedades

UrlFilter

Propriedades

browser.events