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 recentesCorresponde 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.