chrome.events

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.

Conceptos y uso

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((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 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:

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

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 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()

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

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (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, por ejemplo, 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 o un identificador vacío que no utilice otra regla.

Nota: Las reglas son persistentes en todas las sesiones de navegación. Por lo tanto, debes instalar reglas durante tiempo de instalación de la extensión a través del evento runtime.onInstalled. Ten en cuenta que este evento es también se activa cuando se actualiza una extensión. Por lo tanto, primero debes borrar los elementos instalados y, luego, registrar reglas nuevas.

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

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

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.

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

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

Preferencias

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

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

Preferencias

const 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

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

Preferencias

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

En lugar de

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

Preferencias

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

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 de 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 las reglas para manejar eventos.

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

  (rules: Rule<anyany>[], callback?: function) => {...}

  • reglas

    Regla<cualquiera>

    Reglas para registrar. 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<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 muestran las reglas con identificadores que este contiene.

  • callback

    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 debe probar.

  • muestra

    boolean

    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

    boolean

    Es verdadero si los objetos de escucha de eventos están registrados en el evento.

• removeListener

  void

  Anula el registro de la devolución de llamada de un 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 debe registrarse.

• 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 anulará 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.

• condiciones

  cualquiera

  Lista de condiciones que pueden activar las acciones.

• id

  string 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 en función de diversos criterios. Consulta el filtrado de eventos. Todos los criterios distinguen mayúsculas de minúsculas.

Propiedades

• cidrBlocks

  string[] opcional

  Chrome 123 y versiones posteriores

  Coincide si la parte del host de la URL es una dirección IP y se encuentra en alguno 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 comprobar 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. Asimismo, hostContains se puede usar para buscar coincidencias con el sufijo de componente (“foo.”) y para que coincida exactamente con componentes (“.foo.”). La coincidencia exacta del sufijo y la coincidencia exacta de los últimos componentes deben realizarse por separado usando 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 un segmento de consulta ni 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 la ruta de acceso de la URL contiene una string especificada.

• pathEquals

  string opcional

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

• pathPrefix

  string opcional

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

• pathSuffix

  string opcional

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

• ports

  (número | número[])[] 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 el puerto 80, 443 y en el rango de 1,000 a 1,200.

• 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 búsqueda de la URL comienza con una cadena especificada.

• querySuffix

  string opcional

  Coincide si el segmento de búsqueda 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 string 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.