chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.declarativeContent per intraprendere azioni in base ai contenuti di una pagina, senza richiedere l'autorizzazione per leggere i contenuti della pagina.

Autorizzazioni

declarativeContent

Utilizzo

L'API Declarative Content ti consente di attivare l'azione dell'estensione in base all'URL di una pagina web o se un selettore CSS corrisponde a un elemento della pagina, senza dover aggiungere autorizzazioni host o inserire uno script di contenuti.

Utilizza l'autorizzazione activeTab per interagire con una pagina dopo che l'utente ha fatto clic sull'azione dell'estensione.

Regole

Le regole sono costituite da condizioni e azioni. Se una delle condizioni è soddisfatta, vengono eseguite tutte le azioni. Le azioni sono setIcon e showAction.

PageStateMatcher corrisponde alle pagine web se e solo se vengono soddisfatti tutti i criteri elencati. Può corrispondere a un URL di pagina, a un selettore CSS composto o allo stato dei preferiti di una pagina. La seguente regola attiva l'azione dell'estensione sulle pagine Google quando è presente un campo password:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Per attivare l'azione dell'estensione anche per i siti Google con un video, puoi aggiungere una seconda condizione, poiché ogni condizione è sufficiente per attivare tutte le azioni specificate:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

L'evento onPageChanged verifica se una regola ha almeno una condizione soddisfatta ed esegue le azioni. Le regole persistono tra le sessioni di navigazione; pertanto, durante l'installazione dell'estensione, devi prima utilizzare removeRules per cancellare le regole installate in precedenza e poi utilizzare addRules per registrarne di nuove.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Con l'autorizzazione activeTab, l'estensione non mostrerà alcun avviso di autorizzazione e, quando l'utente fa clic sull'azione dell'estensione, verrà eseguita solo sulle pagine pertinenti.

Corrispondenza URL pagina

PageStateMatcher.pageurl corrisponde quando i criteri dell'URL sono soddisfatti. I criteri più comuni sono una concatenazione di host, percorso o URL, seguita da Contiene, Uguale a, Prefisso o Suffisso. La tabella seguente contiene alcuni esempi:

Criteri Corrisponde a
{ hostSuffix: 'google.com' } Tutti gli URL di Google
{ pathPrefix: '/docs/extensions' } URL dei documenti dell'estensione
{ urlContains: 'developer.chrome.com' } Tutti gli URL della documentazione per gli sviluppatori di Chrome

Tutti i criteri sono sensibili alle maiuscole. Per un elenco completo dei criteri, consulta UrlFilter.

Corrispondenza CSS

Le condizioni PageStateMatcher.css devono essere selettori composti, il che significa che non puoi includere combinatori come spazi vuoti o ">" nei selettori. In questo modo, Chrome può abbinare i selettori in modo più efficiente.

Selettori composti (OK) Selettori complessi (non OK)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

Le condizioni CSS corrispondono solo agli elementi visualizzati: se un elemento che corrisponde al selettore è display:none o uno dei suoi elementi principali è display:none, la condizione non corrisponde. Gli elementi con stile visibility:hidden, posizionati fuori schermo o nascosti da altri elementi possono comunque corrispondere alla condizione.

Corrispondenza dello stato dei preferiti

La condizione PageStateMatcher.isBookmarked consente di trovare una corrispondenza con lo stato dei preferiti dell'URL corrente nel profilo dell'utente. Per utilizzare questa condizione, l'autorizzazione "bookmarks" deve essere dichiarata nel manifest dell'estensione.

Tipi

Tipo

ImageData

PageStateMatcher

Corrisponde allo stato di una pagina web in base a vari criteri.

Proprietà

  • constructor

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: PageStateMatcher) => {...}

  • css

    string[] facoltativo

    Corrisponde se tutti i selettori CSS nell'array corrispondono agli elementi visualizzati in un frame con la stessa origine del frame principale della pagina. Tutti i selettori in questo array devono essere selettori composti per velocizzare la corrispondenza. Nota: l'elenco di centinaia di selettori CSS o di selettori CSS che corrispondono a centinaia di volte per pagina può rallentare i siti web.

  • isBookmarked

    boolean facoltativo

    Chrome 45 e versioni successive

    Trova la corrispondenza se lo stato dei preferiti della pagina è uguale al valore specificato. Richiede l'autorizzazione per i preferiti.

  • pageUrl

    UrlFilter facoltativo

    Trova la corrispondenza se le condizioni di UrlFilter sono soddisfatte per l'URL di primo livello della pagina.

RequestContentScript

Azione evento dichiarativa che inserisce uno script di contenuti.

ATTENZIONE: questa azione è ancora sperimentale e non è supportata nelle build stabili di Chrome.

Proprietà

  • constructor

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: RequestContentScript) => {...}

  • allFrames

    boolean facoltativo

    Indica se lo script dei contenuti viene eseguito in tutti i frame della pagina corrispondente o solo nel frame superiore. Il valore predefinito è false.

  • css

    string[] facoltativo

    Nomi dei file CSS da inserire come parte dello script dei contenuti.

  • js

    string[] facoltativo

    Nomi dei file JavaScript da inserire come parte dello script di contenuti.

  • matchAboutBlank

    boolean facoltativo

    Se inserire lo script dei contenuti in about:blank e about:srcdoc. Il valore predefinito è false.

SetIcon

Azione evento dichiarativa che imposta l'icona quadrata n-dip per l'azione pagina o l'azione browser dell'estensione quando vengono soddisfatte le condizioni corrispondenti. Questa azione può essere utilizzata senza autorizzazioni host, ma l'estensione deve avere un'azione di pagina o del browser.

È necessario specificare esattamente uno dei due valori: imageData o path. Entrambi sono dizionari che mappano un numero di pixel a una rappresentazione dell'immagine. La rappresentazione dell'immagine in imageData è un oggetto ImageData, ad esempio da un elemento canvas, mentre la rappresentazione dell'immagine in path è il percorso di un file immagine relativo al manifest dell'estensione. Se scale pixel dello schermo rientrano in un pixel indipendente dal dispositivo, viene utilizzata l'icona scale * n. Se questa scala non è presente, un'altra immagine viene ridimensionata alle dimensioni richieste.

Proprietà

  • constructor

    void

    La funzione constructor ha il seguente aspetto: 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | oggetto facoltativo

    Un oggetto ImageData o un dizionario {size -> ImageData} che rappresenta un'icona da impostare. Se l'icona è specificata come dizionario, l'immagine utilizzata viene scelta in base alla densità dei pixel dello schermo. Se il numero di pixel immagine che rientrano in un'unità di spazio sullo schermo è pari a scale, viene selezionata un'immagine con dimensioni scale * n, dove n è la dimensione dell'icona nella UI. È necessario specificare almeno un'immagine. Tieni presente che details.imageData = foo equivale a details.imageData = {'16': foo}.

ShowAction

Chrome 97 e versioni successive

Un'azione evento dichiarativa che imposta l'azione della barra degli strumenti dell'estensione su uno stato attivato mentre le condizioni corrispondenti sono soddisfatte. Questa azione può essere utilizzata senza autorizzazioni host. Se l'estensione dispone dell'autorizzazione activeTab, facendo clic sull'azione della pagina viene concesso l'accesso alla scheda attiva.

Nelle pagine in cui le condizioni non sono soddisfatte, l'azione della barra degli strumenti dell'estensione sarà in scala di grigi e, se fai clic, si aprirà il menu contestuale anziché attivare l'azione.

Proprietà

ShowPageAction

Ritirato da Chrome 97

Utilizza declarativeContent.ShowAction.

Un'azione evento dichiarativa che imposta l'azione pagina dell'estensione su uno stato attivato quando vengono soddisfatte le condizioni corrispondenti. Questa azione può essere utilizzata senza autorizzazioni host, ma l'estensione deve avere un'azione di pagina. Se l'estensione dispone dell'autorizzazione activeTab, facendo clic sull'azione della pagina viene concesso l'accesso alla scheda attiva.

Nelle pagine in cui le condizioni non sono soddisfatte, l'azione della barra degli strumenti dell'estensione sarà in scala di grigi e, se fai clic, si aprirà il menu contestuale anziché attivare l'azione.

Proprietà

Eventi

onPageChanged

Fornisce l'API Declarative Event composta da addRules, removeRules e getRules.

Condizioni

PageStateMatcher

Azioni

RequestContentScript

SetIcon

ShowPageAction

ShowAction