chrome.events

Descrizione

Lo spazio dei nomi chrome.events contiene tipi comuni utilizzati dagli eventi di invio delle API per avvisarti quando succede qualcosa di interessante.

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 le notifiche utilizzando addListener(). L'argomento di addListener() è sempre una funzione che definisci per gestire l'evento, ma i parametri dipendono dall'evento che gestisci. Controllo della documentazione per alarms.onAlarm in corso... puoi vedere che la funzione ha un singolo parametro: un oggetto alarms.Alarm con dettagli sulla sveglia scaduta.

API di esempio che utilizzano gli eventi: alarms, i18n, identity, runtime. La maggior parte di Chrome le API.

Gestori di eventi dichiarativi

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

I gestori di eventi dichiarativi vengono utilizzati, ad esempio, nel API dichiarativa dei contenuti. In questa pagina vengono descritti i concetti di base di tutti gli eventi dichiarativi e i gestori di rete.

Regole

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

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

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

Oltre alle condizioni e alle azioni, puoi assegnare a ogni regola un identificatore, per semplificare l'annullamento della registrazione di regole registrate in precedenza e una priorità per definire le precedenti 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. Le azioni vengono eseguite in ordine decrescente in base alla priorità delle relative 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 regole. Questi oggetti evento non chiamano una funzione di callback quando si verificano, ma verifica se una qualsiasi regola registrata ha almeno una condizione soddisfatta ed esegui 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. Prende un array di istanze di regola 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 visualizzato nello stesso ordine di quello passato in rule_list, dove i parametri facoltativi id e priority sono stati compilati con i valori generati. Se una qualsiasi regola non è valida, ad esempio perché conteneva una condizione o un'azione non valida, non viene aggiunta alcuna regola e viene utilizzata la variabile runtime.lastError è impostata quando viene richiamata la funzione di callback. Ogni regola in rule_list deve contenere un indirizzo univoco non ancora utilizzato da un'altra regola o da un identificatore vuoto.

Rimuovi regole

Per rimuovere le regole, chiama la funzione removeRules(). 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 che hanno identificatori elencati nell'array vengono rimosso. Se rule_ids elenca un identificatore sconosciuto, questo identificatore viene ignorato automaticamente. Se rule_ids è undefined, tutte le regole registrate di questa estensione sono state rimosse. callback() viene richiamata quando le regole sono state rimosse.

Regole di recupero

Per recuperare un elenco di regole registrate, richiama la funzione getRules(). Accetta 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, tra cui compilati con parametri facoltativi.

Prestazioni

Per ottenere il massimo rendimento, tieni presente 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 dei dati interni. Questo aggiornamento è un'operazione costosa.

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

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

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

Se esistono più regole che condividono le stesse azioni, uniscile in un'unica regola. Le regole attivano le relative azioni non appena viene soddisfatta una singola condizione. Questo accelera la corrispondenza dei dati e riduce il consumo di memoria per gli insiemi di azioni duplicati.

anziché
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]);
Preferenza
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 che ti interessa. Un listener che utilizza un filtro non verrà richiamato per gli eventi che non trasmettono che rende il codice di ascolto più dichiarativo ed efficiente. Un service worker ha bisogno non essere svegliato per gestire eventi che non gli interessano.

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

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

Gli eventi supportano filtri specifici significativi per quell'evento. L'elenco di filtri utilizzati da un evento verranno elencati nella documentazione di quell'evento nella sezione "filtri" .

Nella corrispondenza degli URL (come nell'esempio sopra), i filtri di eventi supportano la stessa corrispondenza degli URL esprimibili con una events.UrlFilter, fatta eccezione per la 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

    null

    Registra un callback del listener di eventi a un evento.

    La funzione addListener ha questo aspetto:

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

    • callback

      H

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

  • addRules

    null

    Registra le regole per gestire gli eventi.

    La funzione addRules ha questo aspetto:

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

    • regole

      Regola<anyany>[]

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

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto:

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

      • regole

        Regola<anyany>[]

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

  • getRules

    null

    Restituisce le regole attualmente registrate.

    La funzione getRules ha questo 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

        Regola<anyany>[]

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

  • hasListener

    null

    La funzione hasListener ha questo aspetto:

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

    • callback

      H

      Listener il cui stato di registrazione deve essere testato.

    • returns

      booleano

      True se il callback è registrato all'evento.

  • hasListeners

    null

    La funzione hasListeners ha questo aspetto:

    () => {...}

    • returns

      booleano

      True se all'evento sono registrati listener di eventi.

  • removeListener

    null

    Consente di annullare la registrazione di un callback del listener di eventi da un evento.

    La funzione removeListener ha questo aspetto:

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

    • callback

      H

      Listener di cui verrà annullata la registrazione.

  • removeRules

    null

    Annulla la registrazione delle regole attualmente registrate.

    La funzione removeRules ha questo aspetto:

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

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

      () => void

Rule

Descrizione di una regola dichiarativa per la gestione degli eventi.

Proprietà

  • di correzione

    qualsiasi[]

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

  • condizioni

    qualsiasi[]

    Elenco delle condizioni che possono attivare le azioni.

  • id

    stringa facoltativo

    Identificatore facoltativo che consente di fare riferimento a questa regola.

  • priorità

    numero facoltativo

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

  • tag

    string[] facoltativo

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

UrlFilter

Filtra gli URL in base a diversi criteri. Consulta la pagina relativa ai filtri degli eventi. Tutti i criteri sono sensibili alle maiuscole.

Proprietà

  • cidrBlocks

    string[] facoltativo

    Chrome 123 e versioni successive .

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

  • hostContains

    stringa facoltativo

    Corrisponde se il nome host dell'URL contiene una stringa specificata. Per verificare se il componente del nome host ha il prefisso "foo", utilizza hostContains: ".foo". Ciò 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 trovare corrispondenze con il suffisso dei componenti ("foo.") e per trovare corrispondenze esatte con i componenti (".foo."). La corrispondenza esatta e quella degli ultimi componenti devono essere eseguite separatamente utilizzando hostSuffix, perché alla fine del nome host non viene aggiunto alcun punto implicito.

  • hostEquals

    stringa facoltativo

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

  • hostPrefix

    stringa facoltativo

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

  • hostSuffix

    stringa facoltativo

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

  • originAndPathMatches

    stringa facoltativo

    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 facoltativo

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

  • pathEquals

    stringa facoltativo

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

  • pathPrefix

    stringa facoltativo

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

  • pathSuffix

    stringa facoltativo

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

  • ports

    (numero | numero[])[] facoltativo

    Corrisponde a 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 facoltativo

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

  • queryEquals

    stringa facoltativo

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

  • queryPrefix

    stringa facoltativo

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

  • querySuffix

    stringa facoltativo

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

  • schemi

    string[] facoltativo

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

  • urlContains

    stringa facoltativo

    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 facoltativo

    Corrisponde a 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 facoltativo

    Corrisponde a 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 facoltativo

    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 facoltativo

    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.