browser.events

Descrizione

Lo spazio dei nomi chrome.events contiene tipi comuni utilizzati dalle API che inviano eventi per informarti quando si verifica un evento interessante.

Concetti e utilizzo

Un Event è un oggetto che ti consente di ricevere una notifica quando si verifica un evento interessante. Ecco un esempio di utilizzo dell'evento browser.alarms.onAlarm per ricevere una notifica ogni volta che un allarme è trascorso:

browser.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Come mostrato nell'esempio, ti registri per la notifica utilizzando addListener(). L'argomento di addListener() è sempre una funzione che definisci per gestire l'evento, ma i parametri della funzione dipendono dall'evento che stai gestendo. Se controlli la documentazione di alarms.onAlarm, puoi vedere che la funzione ha un singolo parametro: un oggetto alarms.Alarm che contiene i dettagli dell'allarme trascorso.

Esempi di API che utilizzano gli eventi: alarms, i18n, identity, runtime. La maggior parte delle API di Chrome lo fa.

Gestori di eventi dichiarativi

I gestori di eventi dichiarativi consentono di definire regole costituite da condizioni e azioni dichiarative. Le condizioni vengono valutate nel browser anziché nel motore JavaScript, il che riduce le latenze di roundtrip e consente un'efficienza molto elevata.

I gestori di eventi dichiarativi vengono utilizzati, ad esempio, nell'API Declarative Content. Questa pagina descrive i concetti di base di tutti i gestori di eventi dichiarativi.

Regole

La regola più semplice possibile è costituita da una o più condizioni e da una o più azioni:

const rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Se una delle condizioni è soddisfatta, vengono eseguite tutte le azioni.

Oltre alle condizioni e alle azioni, puoi assegnare a ogni regola un identificatore, che semplifica l'annullamento della registrazione delle regole registrate in precedenza, e una priorità per definire le precedenze tra le regole. Le priorità vengono prese in considerazione solo se le regole sono in conflitto tra loro o devono essere eseguite in un ordine specifico. Le azioni vengono eseguite in ordine decrescente di priorità delle regole.

const rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Oggetti evento

Gli oggetti evento possono supportare le regole. Questi oggetti evento non chiamano una funzione di callback quando si verificano gli eventi, ma verificano se una regola registrata ha almeno una condizione soddisfatta ed eseguono le azioni associate a questa regola. Gli oggetti evento che supportano l'API dichiarativa hanno tre metodi pertinenti: events.Event.addRules(), events.Event.removeRules() e events.Event.getRules().

Aggiungi regole

Per aggiungere regole per gli annunci, chiama la funzione addRules() dell'oggetto evento. Accetta un array di istanze di regole come primo parametro e una funzione di callback che viene chiamata al completamento.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Se le regole sono state inserite correttamente, il parametro details contiene un array di regole inserite che vengono visualizzate nello stesso ordine del rule_list passato, in cui i parametri facoltativi id e priority sono stati compilati con i valori generati. Se una regola non è valida, ad esempio perché contiene una condizione o un'azione non valida, non viene aggiunta nessuna regola e la variabile runtime.lastError viene impostata quando viene chiamata la funzione di callback. Ogni regola in rule_list deve contenere un identificatore univoco non già utilizzato da un'altra regola o un identificatore vuoto.

Rimuovi regole

Per rimuovere le regole, chiama la funzione removeRules(). Accetta un array facoltativo di identificatori di regole come primo parametro e una funzione di callback come secondo parametro.

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

Se rule_ids è un array di identificatori, vengono rimosse tutte le regole con identificatori elencati nell'array. Se rule_ids elenca un identificatore sconosciuto, questo identificatore viene ignorato automaticamente. Se rule_ids è undefined, tutte le regole registrate di questa estensione vengono rimosse. La funzione callback() viene chiamata quando le regole vengono rimosse.

Recupera regole

Per recuperare un elenco di regole registrate, chiama la funzione getRules(). Accetta un array facoltativo di identificatori di regole con la stessa semantica di removeRules() e una funzione di callback.

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

Il parametro details passato alla funzione callback() fa riferimento a un array di regole, inclusi i parametri facoltativi compilati.

Prestazioni

Per ottenere le massime prestazioni, tieni presente le seguenti linee guida.

Registra e annulla la registrazione delle regole collettivamente. Dopo ogni registrazione o annullamento della registrazione, Chrome deve aggiornare le strutture di dati interne. Questo aggiornamento è un'operazione costosa.

anziché
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);
Preferenza
const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Preferisci la corrispondenza delle sottostringhe alle espressioni regolari in un events.UrlFilter. La corrispondenza basata su sottostringhe è estremamente veloce.

anziché
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});
Preferenza
const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {hostSuffix: "example.com", pathContains: "foo"}
});

Se sono presenti molte regole che condividono le stesse azioni, uniscile in un'unica regola. Le regole attivano le azioni non appena viene soddisfatta una singola condizione. In questo modo, la corrispondenza viene velocizzata e il consumo di memoria per i set di azioni duplicati viene ridotto.

anziché
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]);
Preferenza
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]);

Eventi filtrati

Gli eventi filtrati sono un meccanismo che consente ai listener di specificare un sottoinsieme di eventi di loro interesse. Un listener che utilizza un filtro non verrà richiamato per gli eventi che non superano il filtro, il che rende il codice di ascolto più dichiarativo ed efficiente. Un service worker non deve essere attivato per gestire eventi che non lo riguardano.

Gli eventi filtrati hanno lo scopo di consentire una transizione dal codice di filtro manuale.

anziché
browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});
Preferenza
browser.webNavigation.onCommitted.addListener((event) => {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

Gli eventi supportano filtri specifici che sono significativi per l'evento. L'elenco dei filtri supportati da un evento verrà elencato nella documentazione relativa all'evento nella sezione "Filtri".

Quando si abbinano gli URL (come nell'esempio precedente), i filtri degli eventi supportano le stesse funzionalità di corrispondenza degli URL esprimibili con un events.UrlFilter, ad eccezione della corrispondenza di schema e porta.

Tipi

Event

Un oggetto che consente l'aggiunta e la rimozione di listener per un evento di Chrome.

Proprietà

  • addListener

    void

    Registra un callback del listener di eventi per un evento.

    La funzione addListener ha il seguente aspetto: 

    (callback: H) => {...}

    • callback

      H

      Viene chiamato quando si verifica un evento. I parametri di questa funzione dipendono dal tipo di evento.

  • addRules

    void

    Registra le regole per gestire gli eventi.

    La funzione addRules ha il seguente aspetto: 

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

    • regole

      Rule<anyany>[]

      Regole da registrare. Queste non sostituiscono le regole registrate in precedenza.

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

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

      • regole

        Rule<anyany>[]

        Regole registrate, i parametri facoltativi vengono compilati con i valori.

  • getRules

    void

    Restituisce le regole attualmente registrate.

    La funzione getRules ha il seguente aspetto: 

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

      string[] facoltativo

      Se viene passato un array, vengono restituite solo le regole con identificatori contenuti in questo array.

    • callback

      funzione

      Il parametro callback ha il seguente aspetto: 

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

      • regole

        Rule<anyany>[]

        Regole registrate, i parametri facoltativi vengono compilati con i valori.

  • hasListener

    void

    La funzione hasListener ha il seguente aspetto: 

    (callback: H) => {...}

    • callback

      H

      Listener di cui deve essere testato lo stato della registrazione.

    • returns

      booleano

      True se il callback è registrato per l'evento.

  • hasListeners

    void

    La funzione hasListeners ha il seguente aspetto: 

    () => {...}

    • returns

      booleano

      True se sono registrati listener di eventi per l'evento.

  • removeListener

    void

    Annulla la registrazione di un callback del listener di eventi da un evento.

    La funzione removeListener ha il seguente aspetto: 

    (callback: H) => {...}

    • callback

      H

      Listener di cui annullare la registrazione.

  • removeRules

    void

    Annulla la registrazione delle regole attualmente registrate.

    La funzione removeRules ha il seguente aspetto: 

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • ruleIdentifiers

      string[] facoltativo

      Se viene passato un array, viene annullata la registrazione solo delle regole con identificatori contenuti in questo array.

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

      () => void

Rule

Descrizione di una regola dichiarativa per la gestione degli eventi.

Proprietà

  • di correzione

    any[]

    Elenco di azioni che vengono attivate se una delle condizioni è soddisfatta.

  • condizioni

    any[]

    Elenco di condizioni che possono attivare le azioni.

  • id

    stringa facoltativa

    Identificatore facoltativo che consente di fare riferimento a questa regola.

  • priorità

    number optional

    Priorità facoltativa di questa regola. Il valore predefinito è 100.

  • Tag

    string[] facoltativo

    I tag possono essere utilizzati per annotare le regole ed eseguire operazioni su insiemi di regole.

UrlFilter

Filtra gli URL in base a vari criteri. Consulta la sezione Filtro degli eventi. Tutti i criteri sono sensibili alle maiuscole.

Proprietà

  • cidrBlocks

    string[] facoltativo

    Chrome 123 e versioni successive browser.* da Chrome 148

    Corrisponde se la parte host dell'URL è un indirizzo IP ed è contenuta in uno dei blocchi CIDR specificati nell'array.

  • hostContains

    stringa facoltativa

    Corrisponde se il nome host dell'URL contiene una stringa specificata. Per verificare se un componente del nome host ha il prefisso "foo", utilizza hostContains: ".foo". Questo corrisponde a "www.foobar.com" e "foo.com", perché all'inizio del nome host viene aggiunto un punto implicito. Analogamente, hostContains può essere utilizzato per trovare corrispondenze con il suffisso del componente ("foo.") e per trovare corrispondenze esatte con i componenti (".foo."). La corrispondenza esatta e del suffisso per gli ultimi componenti deve essere eseguita separatamente utilizzando hostSuffix, perché alla fine del nome host non viene aggiunto alcun punto implicito.

  • hostEquals

    stringa facoltativa

    Corrisponde se il nome host dell'URL è uguale a una stringa specificata.

  • hostPrefix

    stringa facoltativa

    Corrisponde se il nome host dell'URL inizia con una stringa specificata.

  • hostSuffix

    stringa facoltativa

    Corrisponde se il nome host dell'URL termina con una stringa specificata.

  • originAndPathMatches

    stringa facoltativa

    Corrisponde se l'URL senza segmento di query e identificatore di frammento corrisponde a un'espressione regolare specificata. I numeri di porta vengono rimossi dall'URL se corrispondono al numero di porta predefinito. Le espressioni regolari utilizzano la sintassi RE2.

  • pathContains

    stringa facoltativa

    Corrisponde se il segmento del percorso dell'URL contiene una stringa specificata.

  • pathEquals

    stringa facoltativa

    Corrisponde se il segmento del percorso dell'URL è uguale a una stringa specificata.

  • pathPrefix

    stringa facoltativa

    Corrisponde se il segmento del percorso dell'URL inizia con una stringa specificata.

  • pathSuffix

    stringa facoltativa

    Corrisponde se il segmento del percorso dell'URL termina con una stringa specificata.

  • ports

    (number | number[])[] facoltativo

    Corrisponde se la porta dell'URL è contenuta in uno degli elenchi di porte specificati. Ad esempio, [80, 443, [1000, 1200]] corrisponde a tutte le richieste sulla porta 80, 443 e nell'intervallo 1000-1200.

  • queryContains

    stringa facoltativa

    Corrisponde se il segmento di query dell'URL contiene una stringa specificata.

  • queryEquals

    stringa facoltativa

    Corrisponde se il segmento di query dell'URL è uguale a una stringa specificata.

  • queryPrefix

    stringa facoltativa

    Corrisponde se il segmento di query dell'URL inizia con una stringa specificata.

  • querySuffix

    stringa facoltativa

    Corrisponde se il segmento di query dell'URL termina con una stringa specificata.

  • schemi

    string[] facoltativo

    Corrisponde se lo schema dell'URL è uguale a uno degli schemi specificati nell'array.

  • urlContains

    stringa facoltativa

    Corrisponde se l'URL (senza identificatore di frammento) contiene una stringa specificata. I numeri di porta vengono rimossi dall'URL se corrispondono al numero di porta predefinito.

  • urlEquals

    stringa facoltativa

    Corrisponde se l'URL (senza identificatore di frammento) è uguale a una stringa specificata. I numeri di porta vengono rimossi dall'URL se corrispondono al numero di porta predefinito.

  • urlMatches

    stringa facoltativa

    Corrisponde se l'URL (senza identificatore di frammento) corrisponde a un'espressione regolare specificata. I numeri di porta vengono rimossi dall'URL se corrispondono al numero di porta predefinito. Le espressioni regolari utilizzano la sintassi RE2.

  • urlPrefix

    stringa facoltativa

    Corrisponde se l'URL (senza identificatore di frammento) inizia con una stringa specificata. I numeri di porta vengono rimossi dall'URL se corrispondono al numero di porta predefinito.

  • urlSuffix

    stringa facoltativa

    Corrisponde se l'URL (senza identificatore di frammento) termina con una stringa specificata. I numeri di porta vengono rimossi dall'URL se corrispondono al numero di porta predefinito.