chrome.declarativeContent

Descrizione

Usa l'API chrome.declarativeContent per eseguire azioni in base ai contenuti di una pagina, senza richiedere l'autorizzazione a leggerli.

Autorizzazioni

declarativeContent

Concetti e utilizzo

La Declarative Content API 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 comprendono condizioni e azioni. Se una delle condizioni è soddisfatta, tutte le azioni vengono eseguite. Le azioni sono setIcon() e showAction().

PageStateMatcher trova corrispondenze con le pagine web se e solo se tutti i criteri elencati sono soddisfatti. Può corrispondere a un URL pagina, un selettore composto CSS o lo stato aggiunto ai preferiti di una pagina. La seguente regola consente 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 rimangono invariate tra le sessioni di navigazione; pertanto, durante il tempo di installazione delle estensioni, devi prima utilizzare removeRules per cancellare le regole installate in precedenza, quindi 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à alcun avviso relativo alle autorizzazioni e, quando l'utente fa clic sull'azione dell'estensione, l'estensione viene pubblicata solo sulle pagine pertinenti.

Corrispondenza URL pagina

Il valore PageStateMatcher.pageurl corrisponde quando vengono soddisfatti i criteri dell'URL. 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 Google
{ pathPrefix: '/docs/extensions' } URL dei documenti delle estensioni
{ urlContains: 'developer.chrome.com' } URL di tutti i documenti 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 gli spazi vuoti o ">" nei tuoi selettori. Ciò consente a Chrome di 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 corrispondente al selettore è display:none o uno degli 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 far corrispondere la condizione.

Corrispondenza dello stato dei preferiti

La condizione PageStateMatcher.isBookmarked consente la corrispondenza dello stato aggiunto ai 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à

  • costruttore

    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: mostrare centinaia di selettori CSS o elencare centinaia di selettori CSS che corrispondono centinaia di volte in ogni pagina può rallentare i siti web.

  • isBookmarked

    booleano facoltativo

    Chrome 45 e versioni successive

    Corrisponde se lo stato aggiunto ai preferiti della pagina è uguale al valore specificato. Richiede l'autorizzazione ai preferiti.

  • pageUrl

    UrlFilter facoltativo

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

RequestContentScript

Azione dichiarativa dell'evento che inserisce uno script di contenuti.

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

Proprietà

  • costruttore

    void

    La funzione constructor ha il seguente 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 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 dei contenuti.

  • matchAboutBlank

    booleano facoltativo

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

SetIcon

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

È necessario specificare esattamente uno tra imageData o path. Entrambi sono dizionari che mappano una serie di pixel a una rappresentazione di un'immagine. La rappresentazione dell'immagine in imageData è un oggetto ImageData; ad esempio, da un elemento canvas, mentre la rappresentazione immagine in path è il percorso di un file immagine rispetto 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à

  • costruttore

    void

    La funzione constructor ha il seguente aspetto: 

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

  • imageData

    DatiImmagine|oggetto facoltativo

    Un oggetto ImageData o un dizionario {size -> ImageData} che rappresenta un'icona da impostare. Se l'icona viene 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à dello spazio dello schermo è uguale a scale, viene selezionata un'immagine di dimensione scale * n, dove n è la dimensione dell'icona nell'interfaccia utente. È 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 di evento dichiarativa che imposta l' azione della barra degli strumenti dell'estensione sullo stato attivato mentre sono soddisfatte le condizioni corrispondenti. Questa azione può essere utilizzata senza autorizzazioni host. Se l'estensione ha l'autorizzazione activeTab, facendo clic sull'azione della pagina ottieni 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 facendo clic si aprirà il menu contestuale, invece di attivare l'azione.

Proprietà

ShowPageAction

Obsoleto da Chrome 97

Utilizza declarativeContent.ShowAction.

Un'azione di evento dichiarativa che imposta l' azione sulla pagina dell'estensione su uno stato attivato mentre sono soddisfatte le condizioni corrispondenti. Questa azione può essere utilizzata senza autorizzazioni host, ma l'estensione deve avere un'azione relativa alla pagina. Se l'estensione ha l'autorizzazione activeTab, facendo clic sull'azione della pagina ottieni 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 facendo clic si aprirà il menu contestuale, invece di attivare l'azione.

Proprietà

Eventi

onPageChanged

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

Condizioni

PageStateMatcher

Azioni

RequestContentScript

SetIcon

ShowPageAction

ShowAction