browser.events

Descrizione

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 è trascorso il tempo di una sveglia:

browser.alarms.onAlarm.addListener((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.

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 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 Content dichiarativa. 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:

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

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

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

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 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 che non sia già utilizzato da un'altra regola o un identificatore vuoto.

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

Recuperare le 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() si riferisce a un array di regole che include parametri facoltativi compilati.

Prestazioni

Per ottenere il massimo rendimento, tieni presente le seguenti linee guida.

Registrare e annullare 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.

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

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

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

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

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

Se ci sono molte regole che 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.

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

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

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

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

Gli eventi supportano filtri specifici significativi per l'evento in questione. 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.