chrome.events

refresh date: 2026-09-25 robots: noindex

Descrizione

Lo spazio dei nomi chrome.events contiene tipi comuni utilizzati dalle API che inviano eventi per avvisarti quando si verifica qualcosa di interessante.

Un Event è un oggetto che ti consente di ricevere una notifica quando succede qualcosa di interessante. Ecco un esempio di utilizzo dell'evento chrome.alarms.onAlarm per ricevere una notifica ogni volta che scade una sveglia:

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

Come mostrato nell'esempio, la registrazione per la notifica avviene tramite 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. Consultando la documentazione relativa a alarms.onAlarm, puoi notare che la funzione ha un solo parametro: un oggetto alarms.Alarm che contiene i dettagli dell'allarme trascorso.

API di esempio 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 forniscono un mezzo per definire regole costituite da condizioni e azioni dichiarative. Le condizioni vengono valutate nel browser anziché nel motore JavaScript, il che riduce le latenze di andata e ritorno e consente un'efficienza molto elevata.

I gestori di eventi dichiarativi vengono utilizzati, ad esempio, nell'API Declarative Web Request e 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 una o più azioni:

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

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

Oltre a condizioni e 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.

var 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 potrebbero supportare le regole. Questi oggetti evento non chiamano una funzione di callback quando si verificano 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.

Aggiunta di regole

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

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

Se le regole sono state inserite correttamente, il parametro details contiene un array di regole inserite che appaiono nello stesso ordine di rule_list, dove 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, nessuna delle regole viene aggiunta 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 attualmente utilizzato da un'altra regola o un identificatore vuoto.

Nota:Nota:le regole sono persistenti nelle sessioni di navigazione. Pertanto, devi installare le regole durante l'installazione dell'estensione utilizzando l'evento runtime.onInstalled. Tieni presente che questo evento viene attivato anche quando viene aggiornata un'estensione. Pertanto, devi prima cancellare le regole installate in precedenza e poi registrarne di nuove.

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

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

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

Recupero delle regole in corso…

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

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

Il parametro details passato alla funzione callback() si riferisce a un array di regole che include parametri facoltativi compilati.

Prestazioni

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

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

Invece di:

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

preferisci:

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

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

Invece di:

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

preferisci:

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

Se molte regole condividono le stesse azioni, uniscile in una sola. Le regole attivano le azioni non appena viene soddisfatta una singola condizione. Ciò velocizza la corrispondenza e riduce il consumo di memoria per i set di azioni duplicati.

Invece di:

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

preferisci:

  var rule = { conditions: [condition1, condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]};
  chrome.declarativeWebRequest.onRequest.addRules([rule]);

Eventi filtrati

Gli eventi filtrati sono un meccanismo che consente ai listener di specificare un sottoinsieme di eventi a cui sono interessati. 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 riattivato per gestire eventi che non lo riguardano.

Gli eventi filtrati hanno lo scopo di consentire una transizione dal codice di filtro manuale come questo:

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

in questo modo:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

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

Quando corrispondono agli URL (come nell'esempio precedente), i filtri degli eventi supportano le stesse funzionalità di corrispondenza degli URL che possono essere espresse 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 questo aspetto:

  (callback: H) =& gt;{...}

  • callback

    H

    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 questo aspetto:

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

  • regole

    Rule<anyany>[]

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

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto:

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

    • regole

      Rule<anyany>[]

      Le regole registrate, i parametri facoltativi vengono compilati con i valori.

• getRules

  void

  Restituisce le regole attualmente registrate.

  La funzione getRules ha questo aspetto:

  (ruleIdentifiers?: string[], callback: function) =& gt;{...}

  • 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>[]) =& gt;void

    • regole

      Rule<anyany>[]

      Le regole registrate, i parametri facoltativi vengono compilati con i valori.

• hasListener

  void

  La funzione hasListener ha questo aspetto:

  (callback: H) =& gt;{...}

  • callback

    H

    Ascoltatore il cui stato di registrazione deve essere testato.

  • returns

    booleano

    True se il callback è registrato per l'evento.

• hasListeners

  void

  La funzione hasListeners ha questo aspetto:

  () =& gt;{...}

  • 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 questo aspetto:

  (callback: H) =& gt;{...}

  • callback

    H

    Listener da annullare.

• removeRules

  void

  Annulla la registrazione delle regole attualmente registrate.

  La funzione removeRules ha questo aspetto:

  (ruleIdentifiers?: string[], callback?: function) =& gt;{...}

  • ruleIdentifiers

    string[] facoltativo

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

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto:

    () =& gt;void

Rule

Descrizione di una regola dichiarativa per la gestione degli eventi.

Proprietà

• di correzione

  any[]

  Elenco delle azioni attivate se una delle condizioni viene soddisfatta.

• condizioni

  any[]

  Elenco delle condizioni che possono attivare le azioni.

• id

  stringa facoltativa

  Identificatore facoltativo che consente di fare riferimento a questa regola.

• priorità

  number optional

  (Facoltativo) Priorità 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. Vedi Filtro degli eventi. Tutti i criteri sono sensibili alle maiuscole.

Proprietà

• cidrBlocks

  string[] facoltativo

  Chrome 123+

  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". Corrisponde a "www.foobar.com" e "foo.com", perché all'inizio del nome host viene aggiunto un punto implicito. Allo stesso modo, hostContains può essere utilizzato per la corrispondenza con il suffisso del componente ("foo.") e per la corrispondenza esatta con i componenti (".foo."). La corrispondenza esatta e con 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 di percorso dell'URL contiene una stringa specificata.

• pathEquals

  stringa facoltativa

  Corrisponde se il segmento di 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 sulle porte 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.