Descrição
O namespace chrome.events
contém tipos comuns usados pelas APIs que distribuem eventos para notificar você quando algo interessante acontece.
Um Event
é um objeto que permite que você seja notificado quando algo interessante acontecer. Confira um
exemplo de como usar o evento chrome.alarms.onAlarm
para receber uma notificação sempre que um alarme tiver passado:
chrome.alarms.onAlarm.addListener(function(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 para
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ê vê 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: alarmes, i18n, identidade, tempo de execução. A maioria das APIs do Chrome tem essa função.
Manipuladores de eventos declarativos
Com os manipuladores de eventos declarativos, é possível 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 Declarativa Web Request e na API Declarative Content. 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:
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 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.
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
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 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. Ela usa uma matriz de instâncias de regras como o primeiro parâmetro e uma função de callback que é chamada após a conclusão.
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
Se as regras forem inseridas corretamente, o parâmetro details
vai conter uma matriz de regras inseridas que aparecem na mesma ordem em que rule_list
transmitidas, 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 ação ou condição inválida, nenhuma das regras será adicionada e a variável runtime.lastError será definida quando a função de retorno de chamada for chamada. Cada regra em rule_list
precisa conter um identificador exclusivo que não seja usado no momento por outra regra ou um identificador vazio.
Removendo regras
Para remover regras, chame a função removeRules()
. Ela aceita uma matriz opcional de identificadores de regras como o primeiro parâmetro e uma função de callback como o 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 removidas. Se rule_ids
listar um identificador desconhecido, ele será ignorado silenciosamente. Se rule_ids
for undefined
, todas as regras registradas desta extensão serão removidas. A função callback()
é chamada quando as regras foram removidas.
Como recuperar regras
Para recuperar uma lista de regras registradas no momento, chame a função getRules()
. Ele aceita uma
matriz opcional de identificadores de regras 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, lembre-se das diretrizes a seguir.
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:
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 substrings em vez de expressões regulares em 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 suas 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:
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 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 importam.
O objetivo dos eventos filtrados é permitir uma transição do código de filtragem manual desta forma:
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'}]});
É possível usar filtros específicos que são significativos para os eventos. A lista de filtros compatíveis com um evento será listada na documentação desse evento na seção "filtros".
Ao corresponder URLs (como no exemplo acima), os filtros de evento 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 a adição e remoção de 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 ocorre um evento. 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<any>[]
Regras a serem registradas. Eles não substituem as regras já registradas.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(rules: Rule<anyany>[]) => void
-
regras
Regra<any>[]
Para as regras que foram registradas, os parâmetros opcionais são preenchidos com valores.
-
-
-
getRules
void
Retorna as regras registradas atualmente.
A função
getRules
tem esta aparência:(ruleIdentifiers?: string[], callback: function) => {...}
-
ruleIdentifiers
string[] opcional
Se uma matriz for passada, 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<any>[]
Para as 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 cujo status de registro será testado.
-
retorna
boolean
Verdadeiro se callback estiver registrado no evento.
-
-
hasListeners
void
A função
hasListeners
tem esta aparência:() => {...}
-
retorna
boolean
Verdadeiro se algum listener de evento estiver registrado no 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 não será registrado.
-
-
removeRules
void
Cancela o registro das regras registradas atualmente.
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 optional
O parâmetro
callback
tem esta aparência:() => void
-
Rule
Descrição de uma regra declarativa para lidar com eventos.
Propriedades
-
corretivas
qualquer um[]
Lista de ações que são acionadas se uma das condições for atendida.
-
conditions
qualquer um[]
Lista de condições que podem acionar as ações.
-
id
string opcional
Identificador opcional que permite referenciar essa regra.
-
campanha
número opcional
Prioridade opcional desta regra. O padrão é 100.
-
tags
string[] opcional
As tags podem ser usadas para anotar regras e executar 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 ou mais recenteCorresponde se a parte do host do URL é um endereço IP e está contido 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 de host tem o 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 de componentes ("foo.") e corresponder exatamente a componentes ('.foo.'). A correspondência exata e de sufixo para os últimos componentes precisam ser feitas 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 é 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 segmento de consulta e identificador de fragmento corresponde 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
Corresponde se o segmento do caminho do URL contém uma string especificada.
-
pathEquals
string opcional
Corresponde se o segmento do caminho do URL é igual a uma string especificada.
-
pathPrefix
string opcional
Corresponde se o segmento do caminho do URL começa com uma string especificada.
-
pathSuffix
string opcional
Corresponde se o segmento do caminho do URL termina com uma string especificada.
-
ports
(number | number[])[] opcional
Corresponde se a porta do URL está contida em 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 1000-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 é igual a uma string especificada.
-
queryPrefix
string opcional
Corresponde se o segmento de consulta do URL começa com uma string especificada.
-
querySuffix
string opcional
Corresponde se o segmento de consulta do URL termina com uma string especificada.
-
schemes
string[] opcional
Corresponde se o esquema do URL é 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 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) é 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
Corresponde se o URL (sem identificador de fragmento) corresponde 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) termina com uma string especificada. Os números de porta serão removidos do URL se corresponderem ao número de porta padrão.