chrome.events

Descripción

Un Event es un objeto que te permite recibir notificaciones cuando sucede algo interesante. Este es un Ejemplo del uso del evento chrome.alarms.onAlarm para recibir notificaciones cada vez que haya transcurrido 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 para addListener() siempre es una función que defines para controlar el evento, pero los parámetros dependen del evento que estés manejando. Verificar la documentación de alarms.onAlarm. puedes ver que la función tiene un solo parámetro: un objeto alarms.Alarm con detalles sobre la alarma transcurrida.

APIs de ejemplo que usan eventos: alarmas, i18n, identidad y entorno de ejecución. Más de Chrome las APIs.

Controladores de eventos declarativos

Los controladores de eventos declarativos proporcionan un medio para definir reglas que consisten en condiciones declarativas y acciones. Las condiciones se evalúan en el navegador y no en el motor de JavaScript, lo que reduce latencias de ida y vuelta y permite una eficiencia muy alta.

Los controladores de eventos declarativos se usan, por ejemplo, en la API de solicitud web declarativa y Declarative Content API. En esta página, se describen los conceptos subyacentes de todos los eventos declarativos controladores.

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 las acciones, puedes asignar un identificador a cada regla, lo que simplifica cancelar el registro de reglas registradas previamente y una prioridad para definir prioridades entre las reglas. Las prioridades solo se consideran si las reglas entran en conflicto entre sí o si deben ejecutarse en un en el orden personalizado. Las acciones se ejecutan en orden descendente de 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 eventos ocurren, pero prueba si alguna regla registrada tiene, al menos, una condición cumplida y ejecuta las acciones asociadas con esta regla. Los objetos de evento 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. Se necesita un array de instancias de reglas como su primer parámetro y una función de devolución de llamada que se llama al finalizar.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

Si las reglas se insertaron correctamente, el parámetro details contendrá un array de reglas insertadas. aparecen en el mismo orden que en el rule_list pasado, donde los parámetros opcionales id y Se completaron priority 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 ni la variable runtime.lastError se establece cuando se llama a la función de devolución de llamada. Cada regla en rule_list debe contener un que no se usa actualmente en otra regla o con un identificador vacío.

Quitando reglas

Para quitar reglas, llama a la función removeRules(). Acepta un array opcional de identificadores de reglas. como su primer parámetro y una función de devolución de llamada como su segundo parámetro.

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

Si rule_ids es un array de identificadores, todas las reglas que tengan identificadores enumerados en el array o quitarse. Si rule_ids muestra un identificador, que se desconoce, este identificador se ignora en silencio. Si rule_ids es undefined. Se quitaron todas las reglas registradas de esta extensión. El callback() se llama a la función cuando se quitaron las reglas.

Recuperando reglas

Para recuperar una lista de reglas registradas actualmente, 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 pasado a la función callback() hace referencia a un array de reglas, que incluye lo siguiente: 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 cancelación de registro, Chrome debe hacer lo siguiente: actualizar las estructuras internas de datos. 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]);

prefiero:

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

Prioriza la coincidencia de subcadenas 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" } });

prefiero:

var match = new chrome.declarativeWebRequest.RequestMatcher({
    url: {hostSuffix: "example.com", pathContains: "foo"} });

Si hay muchas reglas que comparten las mismas acciones, fusiona las reglas en una. Las reglas activan sus acciones en cuanto se cumple una sola condición. Esto acelera la 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]);

prefiero:

  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 que los objetos de escucha especifiquen un subconjunto de eventos les interesa. Un objeto de escucha que usa un filtro no se invocará para los eventos que no pasen la filtro, lo que hace que el código de escucha sea más declarativo y eficiente. Una necesidad de un service worker no se despierta para manejar eventos que no le interesan.

Los eventos filtrados están diseñados para permitir una transición desde código de filtrado manual como este:

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 ese evento. Lista de filtros que un evento se incluirá en la documentación de ese evento en la sección de filtros sección.

Cuando se buscan coincidencias de URLs (como en el ejemplo anterior), los filtros de eventos admiten la misma coincidencia de URL. capacidades que se puedan expresar con un events.UrlFilter, excepto en el caso de la coincidencia de esquemas y puertos.