Descrizione
Utilizza l'API chrome.scripting
per eseguire lo script in contesti diversi.
Autorizzazioni
scripting
Disponibilità
Manifest
Per usare l'API chrome.scripting
, dichiara l'autorizzazione "scripting"
nel file manifest oltre alle autorizzazioni dell'host per le pagine in cui inserire gli script. Utilizza la chiave "host_permissions"
o l'autorizzazione "activeTab"
, che concede autorizzazioni temporanee per l'host. L'esempio seguente utilizza l'autorizzazione activeTab.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
Concetti e utilizzo
Puoi utilizzare l'API chrome.scripting
per inserire JavaScript e CSS nei siti web. Questa procedura è simile a quella che puoi fare con gli script di contenuti. Tuttavia, utilizzando lo spazio dei nomi chrome.scripting
, le estensioni
possono prendere decisioni in fase di runtime.
Target di iniezione
Puoi utilizzare il parametro target
per specificare un target in cui inserire JavaScript o CSS.
L'unico campo obbligatorio è tabId
. Per impostazione predefinita, verrà eseguita un'iniezione nel frame principale della scheda specificata.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
Per l'esecuzione in tutti i frame della scheda specificata, puoi impostare il valore booleano allFrames
su true
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
Puoi anche inserire frame specifici di una scheda specificando singoli ID frame. Per ulteriori informazioni sugli ID frame, consulta la pagina relativa all'API chrome.webNavigation
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
Codice inserito
Le estensioni possono specificare il codice da inserire tramite un file esterno o una variabile di runtime.
Files
I file vengono specificati come stringhe, ovvero percorsi relativi alla directory principale dell'estensione. Il seguente codice inietta il file script.js
nel frame principale della scheda.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
Funzioni di runtime
Quando inserisci JavaScript con scripting.executeScript()
, puoi specificare una funzione da eseguire al posto di un file. Questa funzione deve essere una variabile
disponibile per il contesto dell'estensione corrente.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
Puoi risolvere il problema utilizzando la proprietà args
:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
Stringhe di runtime
Se inserisci codice CSS all'interno di una pagina, puoi anche specificare una stringa da utilizzare nella proprietà css
. Questa opzione è disponibile solo per scripting.insertCSS()
;
non puoi eseguire una stringa utilizzando scripting.executeScript()
.
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
Gestire i risultati
I risultati dell'esecuzione di JavaScript vengono passati all'estensione. Per ogni frame viene incluso un solo risultato. Il frame principale sarà sicuramente il primo indice nell'array risultante; tutti gli altri frame sono in ordine non deterministico.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
scripting.insertCSS()
non restituisce alcun risultato.
Promesse
Se il valore risultante dell'esecuzione dello script è una promessa, Chrome attenderà che questa promessa si accumuli e restituisca il valore risultante.
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
Esempi
Annulla la registrazione di tutti gli script di contenuti dinamici
Lo snippet seguente contiene una funzione che annulla la registrazione di tutti gli script di contenuti dinamici registrati in precedenza dall'estensione.
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
Per provare l'API chrome.scripting
, installa l'esempio di script dal repository degli esempi di estensioni di Chrome.
Tipi
ContentScriptFilter
Proprietà
-
ids
string[] facoltativo
Se specificato,
getRegisteredContentScripts
restituirà solo script con un ID specificato in questo elenco.
CSSInjection
Proprietà
-
css
stringa facoltativo
Una stringa contenente il codice CSS da inserire. È necessario specificare esattamente uno tra
files
ecss
. -
file
string[] facoltativo
Il percorso dei file CSS da inserire in relazione alla directory radice dell'estensione. È necessario specificare esattamente uno tra
files
ecss
. -
origine
StyleOrigin facoltativo
L'origine dello stile dell'inserimento. Il valore predefinito è
'AUTHOR'
. -
destinazione
Dettagli che specificano la destinazione in cui inserire il CSS.
ExecutionWorld
Il mondo JavaScript in cui eseguire uno script.
Enum
"ISOLATED"
Specifica il mondo isolato, ovvero l'ambiente di esecuzione univoco per questa estensione.
"MAIN"
Specifica il mondo principale del DOM, ovvero l'ambiente di esecuzione condiviso con il codice JavaScript della pagina host.
InjectionResult
Proprietà
-
documentId
stringa
Chrome 106 e versioni successiveIl documento associato all'iniezione.
-
frameId
numero
Chrome 90 e versioni successiveIl frame associato all'inserimento.
-
risultato
qualsiasi facoltativo
Il risultato dell'esecuzione dello script.
InjectionTarget
Proprietà
-
allFrames
booleano facoltativo
Indica se lo script deve essere inserito in tutti i frame all'interno della scheda. Il valore predefinito è false. Questo non deve essere vero se
frameIds
è specificato. -
documentIds
string[] facoltativo
Chrome 106 e versioni successiveGli ID di documentId specifici in cui inserire i dati. Non deve essere impostato se è impostato
frameIds
. -
frameIds
number[] facoltativo
Gli ID dei frame specifici in cui inserire i dati.
-
tabId
numero
L'ID della scheda in cui eseguire l'inserimento.
RegisteredContentScript
Proprietà
-
allFrames
booleano facoltativo
Se specificato true, verrà inserito in tutti i frame, anche se non è il frame più in alto nella scheda. Ogni frame viene controllato in modo indipendente per verificare i requisiti dell'URL; non verrà inserito nei frame secondari se non sono soddisfatti i requisiti dell'URL. Il valore predefinito è false, il che significa che viene abbinato solo il frame principale.
-
css
string[] facoltativo
L'elenco di file CSS da inserire nelle pagine corrispondenti. Questi vengono inseriti nell'ordine in cui appaiono in questo array, prima che venga creato o visualizzato qualsiasi DOM per la pagina.
-
excludeMatches
string[] facoltativo
Sono escluse le pagine in cui questo script di contenuti verrebbe altrimenti inserito. Per ulteriori dettagli sulla sintassi di queste stringhe, consulta Pattern di corrispondenza.
-
id
stringa
L'ID dello script dei contenuti specificato nella chiamata API. Non deve iniziare con "_" perché viene riservato come prefisso per gli ID script generati.
-
js
string[] facoltativo
L'elenco di file JavaScript da inserire nelle pagine corrispondenti. Questi vengono inseriti nell'ordine in cui appaiono in questo array.
-
matchOriginAsFallback
booleano facoltativo
Chrome 119 e versioni successiveIndica se lo script può essere inserito in frame in cui l'URL contiene uno schema non supportato; in particolare: about:, data:, blob: o filesystem:. In questi casi, l'origine dell'URL viene controllata per determinare se lo script deve essere inserito. Se l'origine è
null
(come nel caso dei dati: URL), l'origine utilizzata è il frame che ha creato il frame corrente o il frame che ha avviato la navigazione verso questo frame. Tieni presente che questo frame potrebbe non essere il frame principale. -
corrisponde a
string[] facoltativo
Specifica in quali pagine verrà inserito questo script di contenuti. Per ulteriori dettagli sulla sintassi di queste stringhe, consulta Pattern di corrispondenza. Deve essere specificato per
registerContentScripts
. -
persistAcrossSessions
booleano facoltativo
Specifica se questo script dei contenuti verrà mantenuto nelle sessioni future. Il valore predefinito è true.
-
runAt
RunAt facoltativo
Specifica quando i file JavaScript vengono inseriti nella pagina web. Il valore preferito e predefinito è
document_idle
. -
internazionali
ExecutionWorld facoltativo
Chrome 102 e versioni successiveIl "mondo" JavaScript in cui eseguire lo script. Il valore predefinito è
ISOLATED
.
ScriptInjection
Proprietà
-
args
any[] facoltativo
Chrome 92 e versioni successiveGli argomenti da passare alla funzione fornita. È valido solo se viene specificato il parametro
func
. Questi argomenti devono essere selezionabili in formato JSON. -
file
string[] facoltativo
Il percorso dei file JS o CSS da inserire rispetto alla directory root dell'estensione. È necessario specificare esattamente uno tra
files
ofunc
. -
injectImmediately
booleano facoltativo
Chrome 102 e versioni successiveIndica se l'inserimento deve essere attivato nella destinazione il prima possibile. Tieni presente che ciò non garantisce che l'inserimento avvenga prima del caricamento della pagina, in quanto quest'ultima potrebbe essere già stata caricata nel momento in cui lo script raggiunge il target.
-
destinazione
Dettagli che specificano la destinazione in cui inserire lo script.
-
internazionali
ExecutionWorld facoltativo
Chrome 95 e versioni successiveIl "mondo" JavaScript in cui eseguire lo script. Il valore predefinito è
ISOLATED
. -
func
void facoltativo
Chrome 92 e versioni successiveUna funzione JavaScript da inserire. Questa funzione verrà serializzata e poi deserializzata per l'iniezione. Ciò significa che tutti i parametri associati e il contesto di esecuzione andranno persi. È necessario specificare esattamente uno tra
files
ofunc
.La funzione
func
ha il seguente aspetto:() => {...}
StyleOrigin
L'origine di una modifica di stile. Per ulteriori informazioni, consulta le origini degli stili.
Enum
Metodi
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
Inserisce uno script in un contesto di destinazione. Per impostazione predefinita, lo script verrà eseguito all'indirizzo document_idle
o immediatamente se la pagina è già stata caricata. Se la proprietà injectImmediately
è impostata, lo script verrà inserito senza attendere, anche se il caricamento della pagina non è stato completato. Se lo script valuta una promessa, il browser attenderà che la promessa venga soddisfatta e restituirà il valore risultante.
Parametri
-
iniezione
I dettagli dello script da inserire.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(results: InjectionResult[]) => void
-
risultati
-
Ritorni
-
Promise<InjectionResult[]>
Chrome 90 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Restituisce tutti gli script di contenuti registrati dinamicamente per questa estensione che corrispondono al filtro specificato.
Parametri
-
filter
ContentScriptFilter facoltativo
Un oggetto per filtrare gli script registrati dinamicamente dell'estensione.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(scripts: RegisteredContentScript[]) => void
-
script
-
Ritorni
-
Promise<RegisteredContentScript[]>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
Inserisce un foglio di stile CSS in un contesto di destinazione. Se vengono specificati più frame, le iniezioni non riuscite vengono ignorate.
Parametri
-
iniezione
I dettagli degli stili da inserire.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 90 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Registra uno o più script di contenuti per questa estensione.
Parametri
-
script
Contiene un elenco di script da registrare. Se si verificano errori durante l'analisi dello script o la convalida del file o se gli ID specificati esistono già, significa che non viene registrato nessuno script.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
Rimuove un foglio di stile CSS precedentemente inserito da questa estensione da un contesto di destinazione.
Parametri
-
iniezione
I dettagli degli stili da rimuovere. Tieni presente che le proprietà
css
,files
eorigin
devono corrispondere esattamente al foglio di stile inserito tramiteinsertCSS
. Il tentativo di rimuovere un foglio di stile inesistente è un tentativo ingiustificato. -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Consente di annullare la registrazione degli script di contenuti per questa estensione.
Parametri
-
filter
ContentScriptFilter facoltativo
Se specificato, annulla solo la registrazione degli script di contenuti dinamici che corrispondono al filtro. In caso contrario, tutti gli script di contenuti dinamici dell'estensione non verranno registrati.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Aggiorna uno o più script di contenuti per questa estensione.
Parametri
-
script
Contiene un elenco di script da aggiornare. Una proprietà viene aggiornata per lo script esistente solo se è specificata in questo oggetto. Se si verificano errori durante l'analisi dello script o la convalida del file o se gli ID specificati non corrispondono a uno script completamente registrato, gli script non vengono aggiornati.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.