Descrizione
Usa l'API chrome.declarativeContent
per eseguire azioni in base ai contenuti di una pagina, senza richiedere l'autorizzazione a leggerli.
Autorizzazioni
declarativeContent
Utilizzo
La Declarative Content API 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 degli URL delle pagine
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 aggiunta ai 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
ImageDataType
Visita la pagina https://developer.mozilla.org/en-US/docs/Web/API/ImageData.
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) => {...}
-
arg
-
returns
-
-
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 successiveCorrisponde 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) => {...}
-
returns
-
-
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
eabout:srcdoc
. Il valore predefinito èfalse
.
SetIcon
Azione dichiarativa che imposta l'icona quadrata n-dip per l'azione sulla 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) => {...}
-
arg
-
returns
-
-
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 ascale
, viene selezionata un'immagine di dimensionescale * n
, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Tieni presente chedetails.imageData = foo
equivale adetails.imageData = {'16': foo}
.
ShowAction
Un'azione di evento dichiarativa che imposta l'azione della barra degli strumenti dell'estensione sullo stato attivato mentre le condizioni corrispondenti sono soddisfatte. 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à
-
costruttore
void
La funzione
constructor
ha il seguente aspetto:(arg: ShowAction) => {...}
-
arg
-
returns
-
ShowPageAction
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à
-
costruttore
void
La funzione
constructor
ha il seguente aspetto:(arg: ShowPageAction) => {...}
-
arg
-
returns
-
Eventi
onPageChanged
Fornisce l'API Declarative Event, composta da addRules
, removeRules
e getRules
.