chrome.events

Descrizione

Concetti e utilizzo

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 una sveglia è trascorsa:

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

Come mostrato nell'esempio, ti registri per ricevere le notifiche utilizzando addListener(). L'argomento per addListener() è sempre una funzione che definisci per gestire l'evento, ma i parametri della funzione dipendono dall'evento gestito. Consultando la documentazione relativa a alarms.onAlarm, potrai vedere che la funzione ha un singolo parametro: un oggetto alarms.Alarm contenente i dettagli dell'allarme trascorso.

Esempi di API che utilizzano Eventi: alarms, i18n, identity, runtime. La maggior parte delle API di Chrome sì.

Gestori di eventi dichiarativi

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

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

Regole

La regola più semplice possibile consiste in 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 di regole registrate in precedenza e una priorità per definire le priorità 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 in base alla 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 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().

Aggiungere regole

Per aggiungere regole, chiama la funzione addRules() dell'oggetto evento. Prende un array di istanze di regola come primo parametro e una funzione di callback che viene richiamata 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 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é conteneva una condizione o un'azione non valida, non viene aggiunta nessuna regola e la variabile runtime.lastError viene impostata quando viene richiamata la funzione di callback. Ogni regola in rule_list deve contenere un identificatore univoco non ancora utilizzato da un'altra regola o un identificatore vuoto.

Rimuovi regole

Per rimuovere le regole, chiama la funzione removeRules(). che accetta un array facoltativo di identificatori di regola 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, tutte le regole con identificatori elencati nell'array vengono rimosse. 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 richiamata quando le regole sono state rimosse.

Recupero delle 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 che include i parametri facoltativi compilati.

Esibizione

Per ottenere il massimo rendimento, dovresti tenere a mente le seguenti linee guida.

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

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

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

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

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

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

Se più regole condividono le stesse azioni, uniscile in una sola. Le regole attivano le azioni non appena viene soddisfatta una singola condizione. Ciò accelera la corrispondenza e riduce il consumo di memoria per gli insiemi di azioni duplicati.

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

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

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 necessariamente essere svegliato per gestire eventi che non gli interessano.

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

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

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

Gli eventi supportano filtri specifici che siano significativi per quell'evento. L'elenco dei filtri supportati da un evento sarà elencato nella documentazione per quell'evento nella sezione "Filtri".

Quando vengono corrispondenti degli URL (come nell'esempio sopra), i filtri di eventi supportano le stesse funzionalità di corrispondenza degli URL esprimebili con un elemento events.UrlFilter, ad eccezione della corrispondenza di schemi e porte.