browser.events

Descripción

El espacio de nombres chrome.events contiene tipos comunes que usan las APIs que envían eventos para notificarte cuando ocurre algo interesante.

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 browser.alarms.onAlarm para recibir una notificación cada vez que transcurre una alarma:

browser.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 estés controlando. Si revisas la documentación de alarms.onAlarm, verás 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 lo hacen.

Controladores de eventos declarativos

Los controladores de eventos declarativos proporcionan un medio para definir reglas que consisten en condiciones y acciones declarativas. Las condiciones se evalúan en el navegador, en lugar de en el 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 Declarative Content. 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 reglas registradas anteriormente, y una prioridad para definir precedencias entre las reglas. Las prioridades solo se consideran si las reglas entran en conflicto entre sí 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 evento que admiten la API declarativa tienen tres métodos relevantes: events.Event.addRules(), events.Event.removeRules() y events.Event.getRules().

Agregar reglas

Para agregar reglas, llama a la función addRules() del objeto de evento. Toma un array de instancias de reglas como primer parámetro y una función de devolución de llamada que se llama cuando se completa.

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 aparecen en el mismo orden que en el rule_list pasado, en el que 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 las reglas y se establece la variable runtime.lastError cuando se llama a la función de devolución de llamada. Cada regla en rule_list debe contener un identificador único que no esté en uso por otra regla o un identificador vacío.

Quita reglas

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

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

Si rule_ids es un array de identificadores, se quitan todas las reglas que tengan identificadores incluidos en el array. Si rule_ids enumera un identificador desconocido, este se ignora de forma silenciosa. 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 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 cancelación de registro, Chrome debe actualizar las estructuras de datos internas. Esta actualización es una operación costosa.

En lugar de
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);
Preferir
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Prefiere 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
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Preferir
const match = new browser.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 la coincidencia y reduce el consumo de memoria para los conjuntos de acciones duplicados.

En lugar de
const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
Preferir
const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.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. No se invocará un objeto de escucha que use un filtro para los eventos que no pasen el filtro, lo que hace que el código de escucha sea más declarativo y eficiente. No es necesario activar un service worker para controlar eventos que no le interesan.

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

En lugar de
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Preferir
browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Los eventos admiten filtros específicos que son significativos para ese evento. La lista de filtros que admite un evento se incluirá en la documentación de ese evento en la sección "filtros".

Cuando se buscan coincidencias de URLs (como en el ejemplo anterior), los filtros de eventos admiten las mismas capacidades de coincidencia de URLs que se pueden expresar con un events.UrlFilter, excepto 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 se produce 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<anyany>[]

      Son las reglas que se registrarán. Estas no reemplazan las reglas registradas anteriormente.

    • callback

      función opcional

      El parámetro callback se ve de la siguiente manera: 

      (rules: Rule<anyany>[]) => void

      • reglas

        Regla<anyany>[]

        Reglas que se registraron, los parámetros opcionales se completan con valores.

  • getRules

    void

    Muestra 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 este array.

    • callback

      función

      El parámetro callback se ve de la siguiente manera: 

      (rules: Rule<anyany>[]) => void

      • reglas

        Regla<anyany>[]

        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

      Es el objeto de escucha cuyo estado de registro se probará.

    • muestra

      booleano

      Es verdadero si la devolución de llamada está registrada en el evento.

  • hasListeners

    void

    La función hasListeners se ve de la siguiente manera: 

    () => {...}

    • muestra

      booleano

      Es verdadero si hay algún objeto de escucha de eventos registrado para 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

      Es el objeto de escucha cuyo registro se cancelará.

  • removeRules

    void

    Anula 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 cancelará el registro de las reglas con identificadores contenidos en este array.

    • 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

  • acciones

    any[]

    Es la lista de acciones que se activan si se cumple una de las condiciones.

  • condiciones

    any[]

    Es una lista de condiciones que pueden activar las acciones.

  • id

    string opcional

    Es un identificador opcional que permite hacer referencia a esta regla.

  • priority

    number opcional

    Es la 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 varios criterios. Consulta Filtrado de eventos. Todos los criterios distinguen mayúsculas de minúsculas.

Propiedades

  • cidrBlocks

    string[] opcional

    Chrome 123 y versiones posteriores browser.* desde Chrome 148

    Coincide 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

    string 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". Esto coincide con "www.foobar.com" y "foo.com", porque se agrega un punto implícito al principio del nombre de host. De manera similar, hostContains se puede usar para que coincida con el sufijo del componente ('foo.') y para que coincida exactamente con los componentes ('.foo.'). La coincidencia exacta y de sufijo para los últimos componentes se debe realizar por separado con hostSuffix, ya que no se agrega ningún punto implícito al final del nombre de host.

  • hostEquals

    string opcional

    Coincide si el nombre de host de la URL es igual a una cadena especificada.

  • hostPrefix

    string opcional

    Coincide si el nombre de host de la URL comienza con una cadena especificada.

  • hostSuffix

    string opcional

    Coincide si el nombre de host de la URL termina con una cadena especificada.

  • originAndPathMatches

    string opcional

    Coincide si la URL sin el segmento de consulta ni el 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.

  • pathContains

    string opcional

    Coincide si el segmento de ruta de acceso de la URL contiene una cadena especificada.

  • pathEquals

    string opcional

    Coincide si el segmento de ruta de acceso de la URL es igual a una cadena especificada.

  • pathPrefix

    string opcional

    Coincide si el segmento de ruta de acceso de la URL comienza con una cadena especificada.

  • pathSuffix

    string opcional

    Coincide si el segmento de ruta de acceso de la URL termina con una cadena especificada.

  • puertos

    (number | number[])[] opcional

    Coincide si el puerto de la URL está incluido 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 de 1000 a 1200.

  • queryContains

    string opcional

    Coincide si el segmento de consulta de la URL contiene una cadena especificada.

  • queryEquals

    string opcional

    Coincide si el segmento de consulta de la URL es igual a una cadena especificada.

  • queryPrefix

    string opcional

    Coincide si el segmento de consulta de la URL comienza con una cadena especificada.

  • querySuffix

    string opcional

    Coincide si el segmento de consulta de la URL termina con una cadena especificada.

  • esquemas

    string[] opcional

    Coincide si el esquema de la URL es igual a cualquiera de los esquemas especificados en el array.

  • urlContains

    string 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

    string 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

    string 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

    string 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

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