chrome.events

Descripción

Conceptos y uso

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

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

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

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.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (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 (por ejemplo, porque contiene una condición o acción no válida), no se agrega ninguna de ellas 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 en otra regla ni un identificador vacío.

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

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

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.

Recuperar reglas

Para recuperar una lista de 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.

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (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.

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

const rule1 = {...};
const 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.

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

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

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

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

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 el código de filtrado manual.

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

chrome.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {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.