chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

Descrizione

L'API chrome.declarativeNetRequest viene utilizzata per bloccare o modificare le richieste di rete specificando regole dichiarative. In questo modo, le estensioni possono modificare le richieste di rete senza intercettarle e visualizzarne i contenuti, garantendo così una maggiore privacy.

Autorizzazioni

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

Disponibilità

Chrome 84 e versioni successive

Manifest

Oltre alle autorizzazioni descritte sopra, alcuni tipi di set di regole, in particolare quelli statici, richiedono la dichiarazione della chiave manifest "declarative_net_request", che deve essere un dizionario con una singola chiave denominata "rule_resources". Questa chiave è un array contenente dizionari di tipo Ruleset, come mostrato di seguito. Tieni presente che il nome "Ruleset" non viene visualizzato nel file JSON del manifest, poiché si tratta semplicemente di un array. I ruleset statici sono spiegati più avanti in questo documento.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

Concetti e utilizzo

Per utilizzare questa API, specifica uno o più set di regole. Un set di regole contiene un array di regole. Una singola regola esegue una delle seguenti operazioni:

  • Blocca una richiesta di rete.
  • Esegui l'upgrade dello schema (da http a https).
  • Impedire che una richiesta venga bloccata negando le regole bloccate corrispondenti.
  • Reindirizzare una richiesta di rete.
  • Modificare le intestazioni della richiesta o della risposta.

Esistono tre tipi di set di regole, gestiti in modi leggermente diversi.

Dinamico
Persistono tra le sessioni del browser e gli upgrade delle estensioni e vengono gestiti utilizzando JavaScript mentre un'estensione è in uso.
Sessione
Viene cancellato quando il browser viene chiuso e quando viene installata una nuova versione dell'estensione. Le regole di sessione vengono gestite utilizzando JavaScript mentre un'estensione è in uso.
Statico
Vengono pacchettizzati, installati e aggiornati quando un'estensione viene installata o sottoposta ad upgrade. Le regole statiche vengono archiviate in file di regole in formato JSON ed elencate nel file manifest.

Le sezioni successive spiegano in dettaglio i tipi di set di regole.

Set di regole dinamiche e basate sulle sessioni

I set di regole dinamiche e di sessione vengono gestiti utilizzando JavaScript mentre un'estensione è in uso.

  • Le regole dinamiche vengono mantenute tra le sessioni del browser e gli upgrade delle estensioni.
  • Le regole di sessione vengono cancellate quando il browser viene chiuso e quando viene installata una nuova versione dell'estensione.

Esiste un solo tipo di set di regole. Un'estensione può aggiungere o rimuovere regole in modo dinamico chiamando updateDynamicRules() e updateSessionRules(), a condizione che i limiti delle regole non vengano superati. Per informazioni sui limiti delle regole, consulta Limiti delle regole. Puoi vedere un esempio in Esempi di codice.

Set di regole statiche

A differenza delle regole dinamiche e di sessione, le regole statiche vengono pacchettizzate, installate e aggiornate quando un'estensione viene installata o sottoposta ad upgrade. Vengono memorizzate nei file delle regole in formato JSON, che vengono indicati all'estensione utilizzando le chiavi "declarative_net_request" e "rule_resources" come descritto sopra, nonché uno o più dizionari Ruleset. Un dizionario Ruleset contiene un percorso del file delle regole, un ID per il set di regole contenuto nel file e l'indicazione se il set di regole è abilitato o disabilitato. Gli ultimi due sono importanti quando attivi o disattivi un set di regole in modo programmatico.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Per testare i file delle regole, carica l'estensione non pacchettizzata. Gli errori e gli avvisi relativi a regole statiche non valide vengono visualizzati solo per le estensioni non pacchettizzate. Le regole statiche non valide nelle estensioni pacchettizzate vengono ignorate.

Abilita e disabilita regole e set di regole statici

Sia le singole regole statiche sia i set di regole statiche completi possono essere attivati o disattivati in fase di runtime.

L'insieme di regole e set di regole statici abilitati viene mantenuto tra le sessioni del browser. Nessuna delle due viene mantenuta durante gli aggiornamenti delle estensioni, il che significa che solo le regole che hai scelto di lasciare nei file delle regole sono disponibili dopo un aggiornamento.

Per motivi di prestazioni, esistono anche dei limiti al numero di regole e set di regole che possono essere attivati contemporaneamente. Chiama getAvailableStaticRuleCount() per verificare il numero di regole aggiuntive che possono essere attivate. Per informazioni sui limiti delle regole, consulta Limiti delle regole.

Per attivare o disattivare le regole statiche, chiama updateStaticRules(). Questo metodo accetta un oggetto UpdateStaticRulesOptions, che contiene array di ID delle regole da attivare o disattivare. Gli ID vengono definiti utilizzando la chiave "id" del dizionario Ruleset.

Per attivare o disattivare i ruleset statici, chiama updateEnabledRulesets(). Questo metodo accetta un oggetto UpdateRulesetOptions, che contiene array di ID di set di regole da attivare o disattivare. Gli ID vengono definiti utilizzando la chiave "id" del dizionario Ruleset.

Regole di build

Indipendentemente dal tipo, una regola inizia con quattro campi, come mostrato di seguito. Mentre le chiavi "id" e "priority" accettano un numero, le chiavi "action" e "condition" possono fornire diverse condizioni di blocco e reindirizzamento. La seguente regola blocca tutte le richieste di script provenienti da "foo.com" a qualsiasi URL con "abc" come sottostringa.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

Caratteri di corrispondenza urlFilter

La chiave "condition" di una regola consente a una chiave "urlFilter" di agire sugli URL di un dominio specificato. Puoi creare pattern utilizzando i token di corrispondenza dei pattern. Di seguito, sono riportati alcuni esempi.

urlFilter Corrisponde a Non corrisponde a
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Assegnazione della priorità alle regole

Le regole vengono attivate dalle richieste inviate dalle pagine web. Se più regole corrispondono a una determinata richiesta, è necessario assegnare loro una priorità. Questa sezione spiega come viene assegnata la priorità. La definizione delle priorità avviene in due fasi.

  1. La priorità viene determinata per le regole all'interno di un'estensione.
  2. Se più estensioni possono applicare una regola a una richiesta, la priorità viene determinata per tutte le estensioni che corrispondono a una determinata richiesta.

Pensa alla corrispondenza in questo modo: la regola a cui una determinata estensione assegna la priorità verrà poi confrontata con le regole di altre estensioni.

Assegnazione della priorità alle regole all'interno di un'estensione

All'interno di una singola estensione, la definizione delle priorità viene elaborata utilizzando la seguente procedura:

  1. Viene restituita la regola con la priorità più alta definita dallo sviluppatore (ovvero il campo "priority").

  2. Se esiste più di una regola con la priorità più alta definita dallo sviluppatore, alle regole viene assegnata una priorità utilizzando il campo "action", nel seguente ordine:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Se il tipo di azione non è block o redirect, vengono valutate tutte le regole modifyHeaders corrispondenti. Tieni presente che se esistono regole con una priorità definita dallo sviluppatore inferiore a quella specificata per allow e allowAllRequests, queste regole vengono ignorate.

  4. Se più regole modificano la stessa intestazione, la modifica è determinata dal campo "priority" definito dallo sviluppatore e dalle operazioni specificate.

    • Se una regola aggiunge un valore a un'intestazione, le regole con priorità inferiore possono solo aggiungere un valore a quell'intestazione. Le operazioni di impostazione e rimozione non sono consentite.
    • Se una regola imposta un'intestazione, le regole con priorità inferiore possono solo aggiungere valori a quell'intestazione. Non sono consentite altre modifiche.
    • Se una regola rimuove un'intestazione, le regole con priorità inferiore non possono modificarla ulteriormente.

Priorità delle regole tra le estensioni

Se una sola estensione ha una regola che corrisponde a una richiesta, viene applicata quella regola. Tuttavia, se più di un'estensione corrisponde a una richiesta, viene utilizzato il seguente processo:

  1. La priorità delle regole viene assegnata utilizzando il campo "action", nel seguente ordine:

    1. block
    2. redirect o upgradeScheme
    3. allow o allowAllRequests

  2. Se più regole corrispondono, l'estensione installata più di recente ha la priorità.

Limiti delle regole

Il caricamento e la valutazione delle regole nel browser comportano un overhead delle prestazioni, pertanto si applicano alcuni limiti quando si utilizza l'API. I limiti dipendono dal tipo di regola che utilizzi.

Regole statiche

Le regole statiche sono quelle specificate nei file delle regole dichiarati nel file manifest. Un'estensione può specificare fino a 50 ruleset statici come parte della chiave manifest "rule_resources", ma è possibile attivare solo 10 di questi ruleset alla volta. Quest'ultimo è chiamato MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Insieme, questi set di regole garantiscono almeno 30.000 regole. Questo è il GUARANTEED_MINIMUM_STATIC_RULES.

Il numero di regole disponibili successivamente dipende dal numero di regole attivate da tutte le estensioni installate sul browser di un utente. Puoi trovare questo numero in fase di runtime chiamando getAvailableStaticRuleCount(). Puoi vedere un esempio in Esempi di codice.

Regole dinamiche e per le sessioni

I limiti applicati alle regole dinamiche e di sessione sono più semplici di quelli delle regole statiche. Il numero totale di entrambi non può superare 5000. Questo è il MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

Regole che utilizzano espressioni regolari

Tutti i tipi di regole possono utilizzare espressioni regolari, ma il numero totale di regole regex di ogni tipo non può superare 1000. Questo è il valore MAX_NUMBER_OF_REGEX_RULES.

Inoltre, ogni regola deve avere dimensioni inferiori a 2 KB una volta compilata. Questo valore è correlato approssimativamente alla complessità della regola. Se provi a caricare una regola che supera questo limite, verrà visualizzato un avviso simile a quello riportato di seguito e la regola verrà ignorata.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Interazioni con i service worker

Un'API declarativeNetRequest si applica solo alle richieste che raggiungono lo stack di rete. Sono incluse le risposte della cache HTTP, ma potrebbero non essere incluse le risposte che passano attraverso un gestore onfetch di un service worker. declarativeNetRequest non influirà sulle risposte generate dal service worker o recuperate da CacheStorage, ma influirà sulle chiamate a fetch() effettuate in un service worker.

Risorse accessibili dal web

Una regola declarativeNetRequest non può reindirizzare da una richiesta di risorsa pubblica a una risorsa non accessibile dal web. In questo modo viene attivato un errore. Questo vale anche se la risorsa accessibile dal web specificata è di proprietà dell'estensione di reindirizzamento. Per dichiarare le risorse per declarativeNetRequest, utilizza l'array "web_accessible_resources" del manifest.

Esempi

Esempi di codice

Aggiorna le regole dinamiche

L'esempio seguente mostra come chiamare updateDynamicRules(). La procedura per updateSessionRules() è la stessa.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Aggiorna i set di regole statici

L'esempio seguente mostra come attivare e disattivare i set di regole tenendo conto del numero di set di regole statici disponibili e del numero massimo di set di regole statici attivati. Questa operazione è necessaria quando il numero di regole statiche di cui hai bisogno supera il numero consentito. Perché funzioni, alcuni dei tuoi set di regole devono essere installati con alcuni set di regole disattivati (impostando "Enabled" su false nel file manifest).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Esempi di regole

Gli esempi riportati di seguito illustrano in che modo Chrome assegna la priorità alle regole in un'estensione. Durante la revisione, ti consigliamo di aprire le regole di assegnazione della priorità in una finestra separata.

La chiave "priority"

Questi esempi richiedono l'autorizzazione host per *://*.example.com/*.

Per determinare la priorità di un determinato URL, esamina la chiave "priority" (definita dallo sviluppatore), la chiave "action" e la chiave "urlFilter". Questi esempi fanno riferimento al file delle regole di esempio mostrato di seguito.

Navigazione verso https://google.com
Questo URL è coperto da due regole: quelle con ID 1 e 4. Viene applicata la regola con ID 1 perché le azioni "block" hanno una priorità più alta rispetto alle azioni "redirect". Le regole rimanenti non vengono applicate perché riguardano URL più lunghi.
Navigazione alla pagina https://google.com/1234
A causa dell'URL più lungo, ora viene trovata una corrispondenza anche con la regola con ID 2, oltre alle regole con ID 1 e 4. Viene applicata la regola con ID 2 perché "allow" ha una priorità più alta rispetto a "block" e "redirect".
Navigazione alla pagina https://google.com/12345
Tutte e quattro le regole corrispondono a questo URL. Viene applicata la regola con ID 3 perché la sua priorità definita dallo sviluppatore è la più alta del gruppo.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

Reindirizzamenti

L'esempio seguente richiede l'autorizzazione host per *://*.example.com/*.

L'esempio seguente mostra come reindirizzare una richiesta da example.com a una pagina all'interno dell'estensione stessa. Il percorso dell'estensione /a.jpg viene risolto in chrome-extension://EXTENSION_ID/a.jpg, dove EXTENSION_ID è l'ID dell'estensione. Affinché ciò funzioni, il manifest deve dichiarare /a.jpg come risorsa accessibile dal web.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "https://www.example.com",
    "resourceTypes": ["main_frame"]
  }
}

Di seguito viene utilizzata la chiave "transform" per reindirizzare a un sottodominio di example.com. Utilizza un'ancora del nome di dominio ("||") per intercettare le richieste con qualsiasi schema da example.com. La chiave "scheme" in "transform" specifica che i reindirizzamenti al sottodominio utilizzeranno sempre "https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com",
    "resourceTypes": ["main_frame"]
  }
}

L'esempio seguente utilizza le espressioni regolari per reindirizzare da https://www.abc.xyz.com/path a https://abc.xyz.com/path. Nella chiave "regexFilter", nota come i punti vengono preceduti da un carattere di escape e che il gruppo Capture seleziona "abc" o "def". La chiave "regexSubstitution" specifica la prima corrispondenza restituita dell'espressione regolare utilizzando "\1". In questo caso, "abc" viene acquisito dall'URL di reindirizzamento e inserito nella sostituzione.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

Intestazioni

L'esempio seguente rimuove tutti i cookie sia da un frame principale sia da eventuali frame secondari.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Tipi

DomainType

Indica se la richiesta è di prima o di terza parte rispetto al frame in cui ha avuto origine. Una richiesta è considerata proprietaria se ha lo stesso dominio (eTLD+1) del frame in cui ha avuto origine.

Enum

"firstParty"
La richiesta di rete è proprietaria del frame in cui ha avuto origine.

"thirdParty"
La richiesta di rete è di terze parti rispetto al frame in cui ha avuto origine.

ExtensionActionOptions

Chrome 88 e versioni successive

Proprietà

  • displayActionCountAsBadgeText

    boolean facoltativo

    Consente di specificare se visualizzare automaticamente il conteggio delle azioni per una pagina come testo del badge dell'estensione. Questa preferenza viene mantenuta tra le sessioni.

  • tabUpdate

    TabActionCountUpdate facoltativo

    Chrome 89 e versioni successive

    Dettagli su come deve essere modificato il conteggio delle azioni della scheda.

GetDisabledRuleIdsOptions

Chrome 111 e versioni successive

Proprietà

  • rulesetId

    stringa

    L'ID corrispondente a un Ruleset statico.

GetRulesFilter

Chrome 111 e versioni successive

Proprietà

  • ruleIds

    number[] facoltativo

    Se specificato, vengono incluse solo le regole con ID corrispondenti.

HeaderInfo

Chrome 128 e versioni successive

Proprietà

  • excludedValues

    string[] facoltativo

    Se specificata, questa condizione non viene soddisfatta se l'intestazione esiste, ma il suo valore contiene almeno un elemento in questo elenco. Utilizza la stessa sintassi del pattern di corrispondenza di values.

  • intestazione

    stringa

    Il nome dell'intestazione. Questa condizione corrisponde al nome solo se non sono specificati né values né excludedValues.

  • valori

    string[] facoltativo

    Se specificata, questa condizione viene soddisfatta se il valore dell'intestazione corrisponde ad almeno un pattern in questo elenco. Supporta la corrispondenza dei valori di intestazione senza distinzione tra maiuscole e minuscole, oltre ai seguenti costrutti:

    "*" : corrisponde a un numero qualsiasi di caratteri.

    "?" : corrisponde a zero o un carattere.

    "*" e "?" possono essere preceduti da una barra rovesciata, ad esempio "\*" e "\?"

HeaderOperation

Chrome 86 e versioni successive

Descrive le possibili operazioni per una regola "modifyHeaders".

Enum

"append"
Aggiunge una nuova voce per l'intestazione specificata. Quando modifichi le intestazioni di una richiesta, questa operazione è supportata solo per intestazioni specifiche.

"set"
Imposta un nuovo valore per l'intestazione specificata, rimuovendo eventuali intestazioni esistenti con lo stesso nome.

"remove"
Rimuove tutte le voci per l'intestazione specificata.

IsRegexSupportedResult

Chrome 87 e versioni successive

Proprietà

  • isSupported

    booleano

  • reason

    UnsupportedRegexReason facoltativo

    Specifica il motivo per cui l'espressione regolare non è supportata. Fornito solo se isSupported è false.

MatchedRule

Proprietà

  • ruleId

    numero

    L'ID di una regola corrispondente.

  • rulesetId

    stringa

    ID della risorsa Ruleset a cui appartiene questa regola. Per una regola proveniente dall'insieme di regole dinamiche, questo valore sarà uguale a DYNAMIC_RULESET_ID.

MatchedRuleInfo

Proprietà

  • regola

    MatchedRule

  • tabId

    numero

    Il tabId della scheda da cui ha avuto origine la richiesta, se la scheda è ancora attiva. In caso contrario, -1.

  • timeStamp

    numero

    L'ora in cui è stata trovata la corrispondenza con la regola. I timestamp corrisponderanno alla convenzione JavaScript per i tempi, ovvero il numero di millisecondi dall'epoca.

MatchedRuleInfoDebug

Proprietà

  • richiesta

    RequestDetails

    Dettagli sulla richiesta per cui è stata trovata una corrispondenza con la regola.

  • regola

    MatchedRule

MatchedRulesFilter

Proprietà

  • minTimeStamp

    number optional

    Se specificato, corrisponde alle regole solo dopo il timestamp specificato.

  • tabId

    number optional

    Se specificato, corrisponde solo alle regole per la scheda specificata. Se impostato su -1, corrisponde alle regole non associate ad alcuna scheda attiva.

ModifyHeaderInfo

Chrome 86 e versioni successive

Proprietà

  • intestazione

    stringa

    Il nome dell'intestazione da modificare.

  • operazione

    HeaderOperation

    L'operazione da eseguire su un'intestazione.

  • valore

    stringa facoltativa

    Il nuovo valore dell'intestazione. Deve essere specificato per le operazioni append e set.

QueryKeyValue

Proprietà

  • chiave

    stringa

  • replaceOnly

    boolean facoltativo

    Chrome 94 e versioni successive

    Se true, la chiave di query viene sostituita solo se è già presente. In caso contrario, la chiave viene aggiunta anche se non è presente. Il valore predefinito è false.

  • valore

    stringa

QueryTransform

Proprietà

  • addOrReplaceParams

    QueryKeyValue[] facoltativo

    L'elenco di coppie chiave-valore della query da aggiungere o sostituire.

  • removeParams

    string[] facoltativo

    L'elenco delle chiavi di query da rimuovere.

Redirect

Proprietà

  • extensionPath

    stringa facoltativa

    Percorso relativo alla directory dell'estensione. Deve iniziare con "/".

  • regexSubstitution

    stringa facoltativa

    Pattern di sostituzione per le regole che specificano un regexFilter. La prima corrispondenza di regexFilter all'interno dell'URL verrà sostituita con questo pattern. All'interno di regexSubstitution, è possibile utilizzare cifre con una barra rovesciata come carattere di escape (da \1 a \9) per inserire i gruppi Capture corrispondenti. \0 fa riferimento all'intero testo corrispondente.

  • trasformazione

    URLTransform facoltativo

    Trasformazioni degli URL da eseguire.

  • url

    stringa facoltativa

    L'URL di reindirizzamento. I reindirizzamenti agli URL JavaScript non sono consentiti.

RegexOptions

Chrome 87 e versioni successive

Proprietà

  • isCaseSensitive

    boolean facoltativo

    Indica se il valore regex specificato è sensibile alle maiuscole. Il valore predefinito è true.

  • regex

    stringa

    L'espressione regolare da controllare.

  • requireCapturing

    boolean facoltativo

    Indica se il regex specificato richiede l'acquisizione. L'acquisizione è obbligatoria solo per le regole di reindirizzamento che specificano un'azione regexSubstition. Il valore predefinito è false.

RequestDetails

Proprietà

  • documentId

    stringa facoltativa

    Chrome 106 e versioni successive

    L'identificatore univoco del documento del frame, se la richiesta riguarda un frame.

  • documentLifecycle

    DocumentLifecycle facoltativo

    Chrome 106 e versioni successive

    Il ciclo di vita del documento del frame, se la richiesta riguarda un frame.

  • frameId

    numero

    Il valore 0 indica che la richiesta avviene nel frame principale; un valore positivo indica l'ID di un frame secondario in cui avviene la richiesta. Se viene caricato il documento di un (sub)frame (type è main_frame o sub_frame), frameId indica l'ID di questo frame, non l'ID del frame esterno. Gli ID frame sono univoci all'interno di una scheda.

  • frameType

    FrameType facoltativo

    Chrome 106 e versioni successive

    Il tipo di frame, se la richiesta riguarda un frame.

  • initiator

    stringa facoltativa

    L'origine da cui è stata avviata la richiesta. Questo non cambia tramite i reindirizzamenti. Se si tratta di un'origine opaca, verrà utilizzata la stringa "null".

  • method

    stringa

    Metodo HTTP standard.

  • parentDocumentId

    stringa facoltativa

    Chrome 106 e versioni successive

    L'identificatore univoco del documento principale del frame, se questa richiesta riguarda un frame e ha un elemento principale.

  • parentFrameId

    numero

    ID del frame che racchiude il frame che ha inviato la richiesta. Imposta su -1 se non esiste un frame principale.

  • requestId

    stringa

    L'ID della richiesta. Gli ID richiesta sono univoci all'interno di una sessione del browser.

  • tabId

    numero

    L'ID della scheda in cui viene eseguita la richiesta. Impostato su -1 se la richiesta non è correlata a una scheda.

  • Il tipo di risorsa della richiesta.

  • url

    stringa

    L'URL della richiesta.

RequestMethod

Chrome 91 e versioni successive

Descrive il metodo di richiesta HTTP di una richiesta di rete.

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Descrive il tipo di risorsa della richiesta di rete.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Proprietà

  • azione

    RuleAction

    L'azione da intraprendere se viene trovata una corrispondenza con questa regola.

  • condizione

    RuleCondition

    La condizione in base alla quale viene attivata questa regola.

  • id

    numero

    Un ID che identifica in modo univoco una regola. Obbligatorio e deve essere >= 1.

  • priorità

    number optional

    Priorità della regola. Il valore predefinito è 1. Se specificato, deve essere >= 1.

RuleAction

Proprietà

  • reindirizzamento

    Redirect facoltativo

    Descrive come deve essere eseguito il reindirizzamento. Valido solo per le regole di reindirizzamento.

  • requestHeaders

    ModifyHeaderInfo[] facoltativo

    Chrome 86 e versioni successive

    Le intestazioni della richiesta da modificare per la richiesta. Valido solo se RuleActionType è "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] facoltativo

    Chrome 86 e versioni successive

    Le intestazioni della risposta da modificare per la richiesta. Valido solo se RuleActionType è "modifyHeaders".

  • Il tipo di azione da eseguire.

RuleActionType

Descrive il tipo di azione da intraprendere se una determinata RuleCondition corrisponde.

Enum

"block"
Blocca la richiesta di rete.

"redirect"
Reindirizza la richiesta di rete.

"allow"
Consente la richiesta di rete. La richiesta non verrà intercettata se esiste una regola di autorizzazione corrispondente.

"upgradeScheme"
Esegui l'upgrade dello schema dell'URL della richiesta di rete a https se la richiesta è http o ftp.

"modifyHeaders"
Modifica le intestazioni della richiesta/risposta dalla richiesta di rete.

"allowAllRequests"
Consente tutte le richieste all'interno di una gerarchia di frame, inclusa la richiesta di frame stessa.

RuleCondition

Proprietà

  • domainType

    DomainType facoltativo

    Specifica se la richiesta di rete è proprietaria o di terze parti rispetto al dominio da cui ha avuto origine. Se omesso, vengono accettate tutte le richieste.

  • domini

    string[] facoltativo

    Ritirato da Chrome 101

    Usa invece initiatorDomains

    La regola corrisponderà solo alle richieste di rete provenienti dall'elenco di domains.

  • excludedDomains

    string[] facoltativo

    Ritirato da Chrome 101

    Usa invece excludedInitiatorDomains

    La regola non corrisponderà alle richieste di rete provenienti dall'elenco di excludedDomains.

  • excludedInitiatorDomains

    string[] facoltativo

    Chrome 101 e versioni successive

    La regola non corrisponderà alle richieste di rete provenienti dall'elenco di excludedInitiatorDomains. Se l'elenco è vuoto o viene omesso, non vengono esclusi domini. Questa impostazione ha la precedenza su initiatorDomains.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Questo corrisponde all'iniziatore della richiesta e non all'URL della richiesta.
    • Anche i sottodomini dei domini elencati sono esclusi.
  • excludedRequestDomains

    string[] facoltativo

    Chrome 101 e versioni successive

    La regola non corrisponderà alle richieste di rete quando i domini corrispondono a uno dell'elenco di excludedRequestDomains. Se l'elenco è vuoto o viene omesso, non vengono esclusi domini. Questa impostazione ha la precedenza su requestDomains.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Anche i sottodomini dei domini elencati sono esclusi.
  • excludedRequestMethods

    RequestMethod[] facoltativo

    Chrome 91 e versioni successive

    Elenco dei metodi di richiesta per i quali la regola non troverà corrispondenze. È necessario specificare un solo elemento (requestMethods o excludedRequestMethods). Se non viene specificato nessuno dei due, vengono trovate corrispondenze per tutti i metodi di richiesta.

  • excludedResourceTypes

    ResourceType[] facoltativo

    Elenco dei tipi di risorse che non corrispondono alla regola. È necessario specificare un solo elemento (resourceTypes o excludedResourceTypes). Se non viene specificato nessuno dei due, vengono bloccati tutti i tipi di risorse, ad eccezione di "main_frame".

  • excludedResponseHeaders

    HeaderInfo[] facoltativo

    Chrome 128 e versioni successive

    La regola non corrisponde se la richiesta corrisponde a una condizione dell'intestazione della risposta in questo elenco (se specificato). Se vengono specificate entrambe le proprietà excludedResponseHeaders e responseHeaders, la proprietà excludedResponseHeaders ha la precedenza.

  • excludedTabIds

    number[] facoltativo

    Chrome 92 e versioni successive

    Elenco di tabs.Tab.id per cui la regola non deve trovare corrispondenze. Un ID di tabs.TAB_ID_NONE esclude le richieste che non provengono da una scheda. Supportato solo per le regole con ambito sessione.

  • excludedTopDomains

    string[] facoltativo

    Chrome 145+

    La regola non corrisponderà alle richieste di rete quando il dominio del frame di primo livello associato corrisponde a uno dell'elenco di excludedTopDomains. Se l'elenco è vuoto o viene omesso, non vengono esclusi domini. Questa impostazione ha la precedenza su topDomains.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Anche i sottodomini dei domini elencati sono esclusi.
    • Per le richieste senza frame di primo livello associato (ad es. richieste avviate da ServiceWorker), viene considerato il dominio dell'iniziatore della richiesta.
  • initiatorDomains

    string[] facoltativo

    Chrome 101 e versioni successive

    La regola corrisponderà solo alle richieste di rete provenienti dall'elenco di initiatorDomains. Se l'elenco viene omesso, la regola viene applicata alle richieste provenienti da tutti i domini. Non è consentito utilizzare un elenco vuoto.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Questo corrisponde all'iniziatore della richiesta e non all'URL della richiesta.
    • Anche i sottodomini dei domini elencati corrispondono.
  • isUrlFilterCaseSensitive

    boolean facoltativo

    Indica se urlFilter o regexFilter (a seconda di quale viene specificato) è sensibile alle maiuscole. Il valore predefinito è false.

  • regexFilter

    stringa facoltativa

    Espressione regolare da confrontare con l'URL della richiesta di rete. Segue la sintassi RE2.

    Nota: è possibile specificare solo uno dei due valori: urlFilter o regexFilter.

    Nota: regexFilter deve essere composto solo da caratteri ASCII. Questo viene abbinato a un URL in cui l'host è codificato nel formato punycode (nel caso di domini internazionalizzati) e tutti gli altri caratteri non ASCII sono codificati nell'URL in UTF-8.

  • requestDomains

    string[] facoltativo

    Chrome 101 e versioni successive

    La regola corrisponderà alle richieste di rete solo quando il dominio corrisponde a uno dell'elenco di requestDomains. Se l'elenco viene omesso, la regola viene applicata alle richieste provenienti da tutti i domini. Non è consentito utilizzare un elenco vuoto.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Anche i sottodomini dei domini elencati corrispondono.
  • requestMethods

    RequestMethod[] facoltativo

    Chrome 91 e versioni successive

    Elenco dei metodi di richiesta HTTP che la regola può trovare. Non è consentito utilizzare un elenco vuoto.

    Nota: se specifichi una condizione della regola requestMethods, verranno escluse anche le richieste non HTTP(S), mentre se specifichi excludedRequestMethods, non verranno escluse.

  • resourceTypes

    ResourceType[] facoltativo

    Elenco dei tipi di risorse che la regola può trovare. Non è consentito utilizzare un elenco vuoto.

    Nota: questo valore deve essere specificato per le regole allowAllRequests e può includere solo i tipi di risorse sub_frame e main_frame.

  • responseHeaders

    HeaderInfo[] facoltativo

    Chrome 128 e versioni successive

    La regola corrisponde se la richiesta corrisponde a una qualsiasi condizione dell'intestazione della risposta in questo elenco (se specificato).

  • tabIds

    number[] facoltativo

    Chrome 92 e versioni successive

    Elenco di tabs.Tab.id che la regola deve corrispondere. Un ID di tabs.TAB_ID_NONE corrisponde alle richieste che non provengono da una scheda. Non è consentito utilizzare un elenco vuoto. Supportato solo per le regole con ambito sessione.

  • topDomains

    string[] facoltativo

    Chrome 145+

    La regola corrisponderà alle richieste di rete solo quando il dominio del frame di primo livello associato corrisponde a uno dell'elenco di topDomains. Se l'elenco viene omesso, la regola viene applicata alle richieste associate a tutti i domini dei frame di primo livello. Non è consentito utilizzare un elenco vuoto.

    Note:

    • Sono consentiti anche i sottodomini come "a.example.com".
    • Le voci devono essere composte solo da caratteri ASCII.
    • Utilizza la codifica Punycode per i domini internazionalizzati.
    • Anche i sottodomini dei domini elencati corrispondono.
    • Per le richieste senza frame di primo livello associato (ad es. richieste avviate da ServiceWorker), viene considerato il dominio dell'iniziatore della richiesta.
  • urlFilter

    stringa facoltativa

    Il pattern che viene confrontato con l'URL della richiesta di rete. Costrutti supportati:

    "*": carattere jolly. Corrisponde a un numero qualsiasi di caratteri.

    "|": ancora sinistra/destra. Se utilizzato a una delle estremità del pattern, specifica rispettivamente l'inizio/la fine dell'URL.

    '||': ancora del nome di dominio. Se utilizzato all'inizio del pattern, specifica l'inizio di un (sotto)dominio dell'URL.

    '^': carattere separatore. Corrisponde a qualsiasi carattere, ad eccezione di una lettera, una cifra o uno dei seguenti: _, -, . o %. Questo corrisponde anche alla fine dell'URL.

    Pertanto, urlFilter è composto dalle seguenti parti: (ancoraggio del nome di dominio/sinistro facoltativo) + pattern + (ancoraggio destro facoltativo).

    Se omesso, viene eseguita la corrispondenza di tutti gli URL. Non è consentito utilizzare una stringa vuota.

    Un pattern che inizia con ||* non è consentito. Utilizza invece *.

    Nota: è possibile specificare solo uno dei due valori: urlFilter o regexFilter.

    Nota: urlFilter deve essere composto solo da caratteri ASCII. Questo viene abbinato a un URL in cui l'host è codificato nel formato punycode (nel caso di domini internazionalizzati) e tutti gli altri caratteri non ASCII sono codificati nell'URL in UTF-8. Ad esempio, se l'URL della richiesta è http://abc.рф?q=ф, urlFilter verrà confrontato con l'URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145+

Enum

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Proprietà

  • attivato

    booleano

    Indica se il set di regole è abilitato per impostazione predefinita.

  • id

    stringa

    Una stringa non vuota che identifica in modo univoco il set di regole. Gli ID che iniziano con "_" sono riservati per uso interno.

  • percorso

    stringa

    Il percorso del set di regole JSON relativo alla directory dell'estensione.

RulesMatchedDetails

Proprietà

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Regole corrispondenti al filtro specificato.

TabActionCountUpdate

Chrome 89 e versioni successive

Proprietà

  • aumenta

    numero

    L'importo di cui incrementare il conteggio delle azioni della scheda. I valori negativi ridurranno il conteggio.

  • tabId

    numero

    La scheda per cui aggiornare il conteggio delle azioni.

TestMatchOutcomeResult

Chrome 103 e versioni successive

Proprietà

  • matchedRules

    MatchedRule[]

    Le regole (se presenti) che corrispondono alla richiesta ipotetica.

TestMatchRequestDetails

Chrome 103 e versioni successive

Proprietà

  • initiator

    stringa facoltativa

    L'URL dell'attivatore (se presente) per la richiesta ipotetica.

  • method

    RequestMethod facoltativo

    Metodo HTTP standard della richiesta ipotetica. Il valore predefinito è "get" per le richieste HTTP e viene ignorato per le richieste non HTTP.

  • responseHeaders

    object facoltativo

    Chrome 129 e versioni successive

    Le intestazioni fornite da una risposta ipotetica se la richiesta non viene bloccata o reindirizzata prima di essere inviata. Rappresentato come un oggetto che mappa un nome di intestazione a un elenco di valori di stringa. Se non specificato, la risposta ipotetica restituirà intestazioni della risposta vuote, che possono corrispondere a regole che corrispondono alla non esistenza di intestazioni. Ad esempio {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number optional

    L'ID della scheda in cui viene effettuata la richiesta ipotetica. Non deve necessariamente corrispondere a un ID scheda reale. Il valore predefinito è -1, il che significa che la richiesta non è correlata a una scheda.

  • topUrl

    stringa facoltativa

    Chrome 145+

    L'URL del frame di primo livello associato (se presente) per la richiesta.

  • Il tipo di risorsa della richiesta ipotetica.

  • url

    stringa

    L'URL della richiesta ipotetica.

UnsupportedRegexReason

Chrome 87 e versioni successive

Descrive il motivo per cui una determinata espressione regolare non è supportata.

Enum

"syntaxError"
L'espressione regolare non è sintatticamente corretta o utilizza funzionalità non disponibili nella sintassi RE2.

"memoryLimitExceeded"
L'espressione regolare supera il limite di memoria.

UpdateRuleOptions

Chrome 87 e versioni successive

Proprietà

  • addRules

    Rule[] facoltativo

    Regole da aggiungere.

  • removeRuleIds

    number[] facoltativo

    ID delle regole da rimuovere. Gli ID non validi verranno ignorati.

UpdateRulesetOptions

Chrome 87 e versioni successive

Proprietà

  • disableRulesetIds

    string[] facoltativo

    L'insieme di ID corrispondenti a un Ruleset statico che deve essere disattivato.

  • enableRulesetIds

    string[] facoltativo

    L'insieme di ID corrispondenti a un Ruleset statico che deve essere attivato.

UpdateStaticRulesOptions

Chrome 111 e versioni successive

Proprietà

  • disableRuleIds

    number[] facoltativo

    Insieme di ID corrispondenti alle regole in Ruleset da disattivare.

  • enableRuleIds

    number[] facoltativo

    Insieme di ID corrispondenti alle regole in Ruleset da attivare.

  • rulesetId

    stringa

    L'ID corrispondente a un Ruleset statico.

URLTransform

Proprietà

  • frammento

    stringa facoltativa

    Il nuovo frammento per la richiesta. Deve essere vuoto, nel qual caso il frammento esistente viene cancellato, oppure deve iniziare con "#".

  • host

    stringa facoltativa

    Il nuovo host per la richiesta.

  • password

    stringa facoltativa

    La nuova password per la richiesta.

  • percorso

    stringa facoltativa

    Il nuovo percorso della richiesta. Se il campo è vuoto, il percorso esistente viene cancellato.

  • porta

    stringa facoltativa

    La nuova porta per la richiesta. Se il campo è vuoto, la porta esistente viene cancellata.

  • query

    stringa facoltativa

    La nuova query per la richiesta. Deve essere vuoto, nel qual caso la query esistente viene cancellata, oppure deve iniziare con "?".

  • queryTransform

    QueryTransform facoltativo

    Aggiungi, rimuovi o sostituisci le coppie chiave-valore della query.

  • schema

    stringa facoltativa

    Il nuovo schema per la richiesta. I valori consentiti sono "http", "https", "ftp" e "chrome-extension".

  • nome utente

    stringa facoltativa

    Il nuovo nome utente per la richiesta.

Proprietà

DYNAMIC_RULESET_ID

ID del set di regole per le regole dinamiche aggiunte dall'estensione.

Valore

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Intervallo di tempo entro il quale è possibile effettuare chiamate MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, specificato in minuti. Le chiamate aggiuntive non andranno a buon fine immediatamente e imposteranno runtime.lastError. Nota: le chiamate getMatchedRules associate a un'attivazione dall'utente sono esenti dalla quota.

Valore

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 e versioni successive

Il numero minimo di regole statiche garantite a un'estensione nei relativi set di regole statiche abilitati. Eventuali regole che superano questo limite verranno conteggiate ai fini del limite globale delle regole statiche.

Valore

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Il numero di volte in cui getMatchedRules può essere chiamato in un periodo di GETMATCHEDRULES_QUOTA_INTERVAL.

Valore

20

MAX_NUMBER_OF_DYNAMIC_RULES

Il numero massimo di regole dinamiche che un'estensione può aggiungere.

Valore

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 e versioni successive

Il numero massimo di Rulesets statiche che un'estensione può attivare contemporaneamente.

Valore

50

MAX_NUMBER_OF_REGEX_RULES

Il numero massimo di regole con espressioni regolari che un'estensione può aggiungere. Questo limite viene valutato separatamente per l'insieme di regole dinamiche e per quelle specificate nel file delle risorse delle regole.

Valore

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 e versioni successive

Il numero massimo di regole con ambito di sessione che un'estensione può aggiungere.

Valore

5000

MAX_NUMBER_OF_STATIC_RULESETS

Il numero massimo di Rulesets statici che un'estensione può specificare come parte della chiave manifest "rule_resources".

Valore

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 e versioni successive

Il numero massimo di regole dinamiche "non sicure" che un'estensione può aggiungere.

Valore

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 e versioni successive

Il numero massimo di regole con ambito di sessione "non sicure" che un'estensione può aggiungere.

Valore

5000

SESSION_RULESET_ID

Chrome 90 e versioni successive

ID del set di regole per le regole con ambito sessione aggiunte dall'estensione.

Valore

"_session"

Metodi

getAvailableStaticRuleCount()

Promise Chrome 89 e versioni successive 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

Restituisce il numero di regole statiche che un'estensione può attivare prima che venga raggiunto il limite di regole statiche globali.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (count: number) => void

    • conteggio

      numero

Resi

  • Promise<number>

    Chrome 91 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getDisabledRuleIds()

Promise Chrome 111+ 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): Promise<number[]>

Restituisce l'elenco delle regole statiche nel Ruleset specificato che sono attualmente disattivate.

Parametri

  • Specifica il set di regole su cui eseguire la query.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Resi

  • Promise<number[]>

    Promise che si risolve con un elenco di ID corrispondenti alle regole disattivate in quel set di regole.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Restituisce l'insieme corrente di regole dinamiche per l'estensione. I chiamanti possono facoltativamente filtrare l'elenco delle regole recuperate specificando un filter.

Parametri

  • filtro

    GetRulesFilter facoltativo

    Chrome 111 e versioni successive

    Un oggetto per filtrare l'elenco delle regole recuperate.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (rules: Rule[]) => void

Resi

  • Promise<Rule[]>

    Chrome 91 e versioni successive

    Promise che si risolve con l'insieme di regole dinamiche. La Promise potrebbe essere rifiutata in caso di errori interni temporanei.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

Restituisce gli ID dell'insieme corrente di set di regole statiche abilitati.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

Resi

  • Promise<string[]>

    Chrome 91 e versioni successive

    Promise che si risolve con un elenco di ID, in cui ogni ID corrisponde a un Ruleset statico abilitato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getMatchedRules()

Promise 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
): Promise<RulesMatchedDetails>

Restituisce tutte le regole corrispondenti per l'estensione. I chiamanti possono facoltativamente filtrare l'elenco delle regole corrispondenti specificando un filter. Questo metodo è disponibile solo per le estensioni con l'autorizzazione "declarativeNetRequestFeedback" o con l'autorizzazione "activeTab" concessa per tabId specificato in filter. Nota: le regole non associate a un documento attivo che sono state abbinate più di cinque minuti fa non verranno restituite.

Parametri

Resi

  • Chrome 91 e versioni successive

    Promise che si risolve una volta recuperato l'elenco delle regole corrispondenti. In caso di errore, la Promise verrà rifiutata. Questo può accadere per diversi motivi, ad esempio autorizzazioni insufficienti o superamento della quota.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getSessionRules()

Promise Chrome 90+ 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Restituisce l'insieme corrente di regole con ambito di sessione per l'estensione. I chiamanti possono facoltativamente filtrare l'elenco delle regole recuperate specificando un filter.

Parametri

  • filtro

    GetRulesFilter facoltativo

    Chrome 111 e versioni successive

    Un oggetto per filtrare l'elenco delle regole recuperate.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (rules: Rule[]) => void

Resi

  • Promise<Rule[]>

    Chrome 91 e versioni successive

    Promise che si risolve con l'insieme di regole con ambito di sessione.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

isRegexSupported()

Promise Chrome 87 e versioni successive 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

Controlla se l'espressione regolare specificata sarà supportata come condizione della regola regexFilter.

Parametri

Resi

  • Chrome 91 e versioni successive

    Promise che si risolve con i dettagli relativi al fatto che l'espressione regolare sia supportata o meno e, in caso negativo, il motivo.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

setExtensionActionOptions()

Promise Chrome 88 e versioni successive 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): Promise<void>

Configura se il conteggio delle azioni per le schede deve essere visualizzato come testo del badge dell'azione dell'estensione e fornisce un modo per incrementare il conteggio delle azioni.

Parametri

  • callback

    funzione elemento facoltativo

    Chrome 89 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 91 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

testMatchOutcome()

Promise Chrome 103+ 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

Controlla se una delle regole declarativeNetRequest dell'estensione corrisponde a una richiesta ipotetica. Nota: disponibile solo per le estensioni non pacchettizzate, in quanto è destinata a essere utilizzata solo durante lo sviluppo delle estensioni.

Parametri

Resi

  • Promise che si risolve con i dettagli delle regole corrispondenti.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

Modifica l'insieme corrente di regole dinamiche per l'estensione. Le regole con gli ID elencati in options.removeRuleIds vengono prima rimosse, poi vengono aggiunte le regole indicate in options.addRules. Note:

  • Questo aggiornamento avviene come singola operazione atomica: vengono aggiunte e rimosse tutte le regole specificate oppure viene restituito un errore.
  • Queste regole vengono mantenute tra le sessioni del browser e tra gli aggiornamenti delle estensioni.
  • Le regole statiche specificate nel pacchetto di estensioni non possono essere rimosse utilizzando questa funzione.
  • MAX_NUMBER_OF_DYNAMIC_RULES è il numero massimo di regole dinamiche che un'estensione può aggiungere. Il numero di regole non sicure non deve superare MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Parametri

  • Chrome 87 e versioni successive
  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 91 e versioni successive

    Promessa che viene risolta una volta completato l'aggiornamento. In caso di errore, la promise verrà rifiutata e non verrà apportata alcuna modifica al set di regole. Ciò può accadere per diversi motivi, ad esempio formato della regola non valido, ID regola duplicato, limite del numero di regole superato, errori interni e altri.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

updateEnabledRulesets()

Promise 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
): Promise<void>

Aggiorna l'insieme di set di regole statiche attivati per l'estensione. I set di regole con gli ID elencati in options.disableRulesetIds vengono prima rimossi, poi vengono aggiunti i set di regole elencati in options.enableRulesetIds. Tieni presente che l'insieme di set di regole statiche attivati viene mantenuto tra le sessioni, ma non tra gli aggiornamenti delle estensioni, ovvero la chiave manifest rule_resources determinerà l'insieme di set di regole statiche attivati per ogni aggiornamento delle estensioni.

Parametri

  • Chrome 87 e versioni successive
  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 91 e versioni successive

    Promessa che viene risolta una volta completato l'aggiornamento. In caso di errore, la promise verrà rifiutata e non verrà apportata alcuna modifica all'insieme di set di regole attivati. Ciò può accadere per diversi motivi, ad esempio ID di set di regole non validi, superamento del limite di conteggio delle regole o errori interni.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

updateSessionRules()

Promise Chrome 90+ 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

Modifica l'insieme corrente di regole con ambito di sessione per l'estensione. Le regole con gli ID elencati in options.removeRuleIds vengono prima rimosse, poi vengono aggiunte le regole indicate in options.addRules. Note:

  • Questo aggiornamento avviene come singola operazione atomica: vengono aggiunte e rimosse tutte le regole specificate oppure viene restituito un errore.
  • Queste regole non vengono mantenute tra le sessioni e vengono memorizzate nella memoria.
  • MAX_NUMBER_OF_SESSION_RULES è il numero massimo di regole di sessione che un'estensione può aggiungere.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 91 e versioni successive

    Promessa che viene risolta una volta completato l'aggiornamento. In caso di errore, la promise verrà rifiutata e non verrà apportata alcuna modifica al set di regole. Ciò può accadere per diversi motivi, ad esempio formato della regola non valido, ID regola duplicato, limite del numero di regole superato e altri.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

updateStaticRules()

Promise Chrome 111+ 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): Promise<void>

Disattiva e attiva singole regole statiche in un Ruleset. Le modifiche alle regole appartenenti a un Ruleset disattivato verranno applicate alla successiva attivazione.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Promessa che viene risolta al termine dell'aggiornamento. In caso di errore, la promise verrà rifiutata e non verrà apportata alcuna modifica alle regole statiche attivate.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

Attivato quando una regola corrisponde a una richiesta. Disponibile solo per le estensioni non pacchettizzate con l'autorizzazione "declarativeNetRequestFeedback", in quanto è destinata esclusivamente al debug.

Parametri