chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.declarativeContent per eseguire azioni a seconda dei contenuti di una pagina, senza richiedere l'autorizzazione a leggere i contenuti della pagina.

Autorizzazioni

declarativeContent

Utilizzo

L'API Declarative Content ti consente di attivare l'azione della tua estensione a seconda dell'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 dei 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, tutte le azioni vengono eseguite. 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 composto CSS 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, in quanto 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 vengono mantenute nelle 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, la tua estensione non mostrerà avvisi relativi alle autorizzazioni e, quando l'utente fa clic sull'azione dell'estensione, verrà eseguita solo sulle pagine pertinenti.

Corrispondenza URL pagina

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

Criteri Corrisponde a
{ hostSuffix: 'google.com' } Tutti gli URL Google
{ pathPrefix: '/docs/extensions' } URL della documentazione 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 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 dallo schermo o nascosti da altri elementi possono comunque soddisfare la 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 "Segnalibri" 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 questo 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 di questo array devono essere selettori composti per velocizzare la corrispondenza. Nota: elencare centinaia di selettori CSS o selettori CSS che corrispondono centinaia di volte per pagina può rallentare i siti web.

  • isBookmarked

    booleano facoltativo

    Chrome 45+

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

  • pageUrl

    UrlFilter facoltativo

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

RequestContentScript

Azione evento dichiarativa che inserisce uno script dei contenuti.

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

Proprietà

  • constructor

    void

    La funzione constructor ha questo aspetto: 

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

  • allFrames

    booleano facoltativo

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

  • css

    string[] facoltativo

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

  • js

    string[] facoltativo

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

  • matchAboutBlank

    booleano facoltativo

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

SetIcon

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

È necessario specificare esattamente uno tra imageData e 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 i pixel dello schermo scale rientrano in un pixel indipendente dal dispositivo, viene utilizzata l'icona scale * n. Se la scala non è presente, un'altra immagine viene ridimensionata alle dimensioni richieste.

Proprietà

  • constructor

    void

    La funzione constructor ha questo 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 dell'immagine che rientrano in un'unità di spazio dello schermo è pari a scale, viene selezionata un'immagine di dimensioni scale * n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Tieni presente che details.imageData = foo è equivalente a details.imageData = {'16': foo}.

ShowAction

Chrome 97+

Un'azione evento dichiarativa che imposta l'azione della barra degli strumenti dell'estensione su uno stato attivo 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 si concede 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

Deprecato a partire da Chrome 97

Utilizza declarativeContent.ShowAction.

Un'azione evento dichiarativa che imposta l'azione di pagina dell'estensione su uno stato attivato mentre le condizioni corrispondenti sono soddisfatte. 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 si concede 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