Descripción
El espacio de nombres chrome.events
contiene tipos comunes que usan las APIs que envían eventos para notificarte cuando sucede algo interesante.
Un Event
es un objeto que te permite recibir notificaciones cuando ocurre algo interesante. A continuación, se incluye un ejemplo de cómo usar el evento chrome.alarms.onAlarm
para recibir notificaciones cada vez que transcurra una alarma:
chrome.alarms.onAlarm.addListener(function(alarm) {
appendToLog('alarms.onAlarm --'
+ ' name: ' + alarm.name
+ ' scheduledTime: ' + alarm.scheduledTime);
});
Como se muestra en el ejemplo, te registras para recibir notificaciones con addListener()
. El argumento de addListener()
siempre es una función que defines para controlar el evento, pero los parámetros de la función dependen del evento que controlas. Si verificas la documentación de alarms.onAlarm
, puedes ver que la función tiene un solo parámetro: un objeto alarms.Alarm
que tiene detalles sobre la alarma transcurrida.
Ejemplos de APIs que usan eventos: alarms, i18n, identity y runtime. La mayoría de las APIs de Chrome sí lo hacen.
Controladores de eventos declarativos
Los controladores de eventos declarativos proporcionan un medio para definir reglas que constan de condiciones y acciones declarativas. Las condiciones se evalúan en el navegador en lugar del motor de JavaScript, lo que reduce las latencias de ida y vuelta y permite una eficiencia muy alta.
Los controladores de eventos declarativos se usan, por ejemplo, en la API de declaración web declarativa y la API de contenido declarativo. En esta página, se describen los conceptos subyacentes de todos los controladores de eventos declarativos.
Reglas
La regla más simple posible consta de una o más condiciones y una o más acciones:
var rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Si se cumple alguna de las condiciones, se ejecutan todas las acciones.
Además de las condiciones y acciones, puedes asignar un identificador a cada regla, lo que simplifica la cancelación del registro de las reglas registradas previamente y una prioridad para definir las prioridades entre las reglas. Las prioridades solo se consideran si las reglas entran en conflicto entre ellas o deben ejecutarse en un orden específico. Las acciones se ejecutan en orden descendente según la prioridad de sus reglas.
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
Los objetos de evento pueden admitir reglas. Estos objetos de evento no llaman a una función de devolución de llamada cuando ocurren eventos, sino que prueban si alguna regla registrada tiene al menos una condición cumplida y ejecutan las acciones asociadas con esta regla. Los objetos de eventos que admiten la API declarativa tienen tres métodos relevantes: events.Event.addRules
, events.Event.removeRules
y events.Event.getRules
.
Agrega reglas
Para agregar reglas, llama a la función addRules()
del objeto de evento. Toma un array de instancias de reglas
como su primer parámetro y una función de devolución de llamada a la que se llama cuando finaliza.
var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});
Si las reglas se insertaron correctamente, el parámetro details
contiene un array de reglas insertadas que aparece en el mismo orden que en el objeto rule_list
que se pasó, donde los parámetros opcionales id
y priority
se completaron con los valores generados. Si alguna regla no es válida, p.ej., porque contenía una condición o acción no válida, no se agrega ninguna de las reglas y se establece la variable runtime.lastError cuando se llama a la función de devolución de llamada. Cada regla de rule_list
debe contener un identificador único que no se utilice actualmente en otra regla o que no sea un identificador vacío.
Quitando reglas
Para quitar reglas, llama a la función removeRules()
. Acepta un array opcional de identificadores de reglas
como el primer parámetro y una función de devolución de llamada como el segundo parámetro.
var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});
Si rule_ids
es un arreglo de identificadores, se quitan todas las reglas que tienen identificadores enumerados en el arreglo. Si rule_ids
muestra un identificador, que es desconocido, este se ignora en silencio. Si
rule_ids
es undefined
, se quitan todas las reglas registradas de esta extensión. Se llama a la función callback()
cuando se quitan las reglas.
Recupera reglas
Para recuperar una lista de las reglas registradas, llama a la función getRules()
. Acepta un array opcional de identificadores de reglas con la misma semántica que removeRules
y una función de devolución de llamada.
var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});
El parámetro details
que se pasa a la función callback()
hace referencia a un array de reglas que incluye
parámetros opcionales completados.
Rendimiento
Para lograr el máximo rendimiento, debes tener en cuenta los siguientes lineamientos.
Registra y cancela el registro de reglas de forma masiva. Después de cada registro o anulación de registro, Chrome debe actualizar las estructuras de datos internas. Esta actualización es una operación costosa.
En lugar de esta sintaxis:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
preferir:
var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
Elige la coincidencia de substring en lugar de las expresiones regulares en un events.UrlFilter. La coincidencia basada en subcadenas es extremadamente rápida.
En lugar de esta sintaxis:
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {urlMatches: "example.com/[^?]*foo" } });
preferir:
var match = new chrome.declarativeWebRequest.RequestMatcher({
url: {hostSuffix: "example.com", pathContains: "foo"} });
Si hay muchas reglas que comparten las mismas acciones, combínalas en una sola. Las reglas activan sus acciones en cuanto se cumple una sola condición. Esto acelera las coincidencias y reduce el consumo de memoria de los conjuntos de acciones duplicados.
En lugar de esta sintaxis:
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]);
preferir:
var rule = { conditions: [condition1, condition2],
actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule]);
Eventos filtrados
Los eventos filtrados son un mecanismo que permite a los objetos de escucha especificar un subconjunto de eventos que les interesan. Un objeto de escucha que usa un filtro no se invocará para los eventos que no pasen el filtro, lo que hace que el código de reproducción sea más declarativo y eficiente. No es necesario despertar a un service worker para que controle eventos que no le interesan.
Los eventos filtrados están diseñados para permitir una transición desde un código de filtrado manual como el siguiente:
chrome.webNavigation.onCommitted.addListener(function(e) {
if (hasHostSuffix(e.url, 'google.com') ||
hasHostSuffix(e.url, 'google.com.au')) {
// ...
}
});
en esto:
chrome.webNavigation.onCommitted.addListener(function(e) {
// ...
}, {url: [{hostSuffix: 'google.com'},
{hostSuffix: 'google.com.au'}]});
Los eventos admiten filtros específicos que son significativos para ellos. La lista de filtros que admite un evento aparecerá en la documentación de ese evento en la sección "filtros".
Cuando se hacen coincidir URLs (como en el ejemplo anterior), los filtros de eventos admiten las mismas capacidades de coincidencia de URL que se pueden expresar con un events.UrlFilter
, excepto para la coincidencia de esquema y puerto.
Tipos
Event
Es un objeto que permite agregar y quitar objetos de escucha para un evento de Chrome.
Propiedades
-
addListener
void
Registra una devolución de llamada del objeto de escucha de eventos en un evento.
La función
addListener
se ve de la siguiente manera:(callback: H) => {...}
-
callback
H
Se llama cuando ocurre un evento. Los parámetros de esta función dependen del tipo de evento.
-
-
addRules
void
Registra reglas para controlar eventos.
La función
addRules
se ve de la siguiente manera:(rules: Rule<anyany>[], callback?: function) => {...}
-
reglas
Regla<cualquiera>[]
Las reglas que se deben registrar Estas no reemplazan a las reglas registradas previamente.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(rules: Rule<anyany>[]) => void
-
reglas
Regla<cualquiera>[]
Las reglas que se registraron, los parámetros opcionales se completan con valores.
-
-
-
getRules
void
Devuelve las reglas registradas actualmente.
La función
getRules
se ve de la siguiente manera:(ruleIdentifiers?: string[], callback: function) => {...}
-
ruleIdentifiers
string[] opcional
Si se pasa un array, solo se devuelven las reglas con identificadores contenidos en él.
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(rules: Rule<anyany>[]) => void
-
reglas
Regla<cualquiera>[]
Las reglas que se registraron, los parámetros opcionales se completan con valores.
-
-
-
hasListener
void
La función
hasListener
se ve de la siguiente manera:(callback: H) => {...}
-
callback
H
Objeto de escucha cuyo estado de registro se probará.
-
resultados
boolean
Es verdadero si se registra una devolución de llamada en el evento.
-
-
hasListeners
void
La función
hasListeners
se ve de la siguiente manera:() => {...}
-
resultados
boolean
Es verdadero si se registra algún objeto de escucha de eventos en el evento.
-
-
removeListener
void
Anula el registro de una devolución de llamada del objeto de escucha de eventos de un evento.
La función
removeListener
se ve de la siguiente manera:(callback: H) => {...}
-
callback
H
Objeto de escucha que no se debe registrar.
-
-
removeRules
void
Cancela el registro de las reglas registradas actualmente.
La función
removeRules
se ve de la siguiente manera:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] opcional
Si se pasa un array, solo se anula el registro de las reglas con identificadores contenidos en él.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
-
Rule
Descripción de una regla declarativa para controlar eventos.
Propiedades
-
de solución
cualquiera
Lista de acciones que se activan si se cumple una de las condiciones.
-
conditions
cualquiera
Lista de condiciones que pueden activar las acciones.
-
id
cadena opcional
Identificador opcional que permite hacer referencia a esta regla.
-
priority
número opcional
Prioridad opcional de esta regla. La configuración predeterminada es 100.
-
tags
string[] opcional
Las etiquetas se pueden usar para anotar reglas y realizar operaciones en conjuntos de reglas.
UrlFilter
Filtra las URLs según diversos criterios. Consulta el artículo sobre filtrado de eventos. Todos los criterios distinguen mayúsculas de minúsculas.
Propiedades
-
cidrBlocks
string[] opcional
Chrome 123 y versiones posterioresCoincide si la parte del host de la URL es una dirección IP y está contenida en cualquiera de los bloques CIDR especificados en el array.
-
hostContains
cadena opcional
Coincide si el nombre de host de la URL contiene una cadena especificada. Para probar si un componente de nombre de host tiene un prefijo “foo”, usa hostContains: “.foo”. Coincide con “www.foobar.com” y “foo.com”, porque se agrega un punto implícito al principio del nombre de host. De forma similar, hostContains se puede usar para buscar coincidencias con el sufijo de componente ("foo.") y para buscar coincidencias exactas con componentes (".foo."). La coincidencia exacta y de sufijo de los últimos componentes debe realizarse por separado con hostSuffix, ya que no se agrega ningún punto implícito al final del nombre del host.
-
hostEquals
cadena opcional
Coincide si el nombre de host de la URL es igual a una cadena especificada.
-
hostPrefix
cadena opcional
Coincide si el nombre de host de la URL comienza con una cadena especificada.
-
hostSuffix
cadena opcional
Coincide si el nombre de host de la URL termina con una cadena especificada.
-
originAndPathMatches
cadena opcional
Coincide si la URL sin segmento de consulta ni identificador de fragmentos coincide con una expresión regular especificada. Los números de puerto se quitan de la URL si coinciden con el número de puerto predeterminado. Las expresiones regulares usan la sintaxis RE2.
-
pathContains
cadena opcional
Coincide si el segmento de ruta de la URL contiene una cadena especificada.
-
pathEquals
cadena opcional
Coincide si el segmento de ruta de la URL es igual a una cadena especificada.
-
pathPrefix
cadena opcional
Coincide si el segmento de ruta de la URL comienza con una cadena especificada.
-
pathSuffix
cadena opcional
Coincide si el segmento de ruta de la URL termina con una cadena especificada.
-
ports
(número | número[])[] opcional
Coincide si el puerto de la URL se encuentra en alguna de las listas de puertos especificadas. Por ejemplo,
[80, 443, [1000, 1200]]
coincide con todas las solicitudes en los puertos 80 y 443, y en el rango 1000-1200. -
queryContains
cadena opcional
Coincide si el segmento de búsqueda de la URL contiene una cadena especificada.
-
queryEquals
cadena opcional
Coincide si el segmento de búsqueda de la URL es igual a una cadena especificada.
-
queryPrefix
cadena opcional
Coincide si el segmento de búsqueda de la URL comienza con una cadena especificada.
-
querySuffix
cadena opcional
Coincide si el segmento de consulta de la URL termina en una cadena especificada.
-
schemes
string[] opcional
Coincide si el esquema de la URL es igual a cualquiera de los esquemas especificados en el array.
-
urlContains
cadena opcional
Coincide si la URL (sin identificador de fragmento) contiene una cadena especificada. Los números de puerto se quitan de la URL si coinciden con el número de puerto predeterminado.
-
urlEquals
cadena opcional
Coincide si la URL (sin identificador de fragmento) es igual a una cadena especificada. Los números de puerto se quitan de la URL si coinciden con el número de puerto predeterminado.
-
urlMatches
cadena opcional
Coincide si la URL (sin identificador de fragmento) coincide con una expresión regular especificada. Los números de puerto se quitan de la URL si coinciden con el número de puerto predeterminado. Las expresiones regulares usan la sintaxis RE2.
-
urlPrefix
cadena opcional
Coincide si la URL (sin identificador de fragmento) comienza con una cadena especificada. Los números de puerto se quitan de la URL si coinciden con el número de puerto predeterminado.
-
urlSuffix
cadena opcional
Coincide si la URL (sin identificador de fragmento) termina con una cadena especificada. Los números de puerto se quitan de la URL si coinciden con el número de puerto predeterminado.