Descrizione
Utilizza l'API chrome.scripting per eseguire lo script in contesti diversi.
Autorizzazioni
scriptingDisponibilità
Manifest
Per utilizzare l'API browser.scripting, dichiara l'autorizzazione "scripting" nel manifest, oltre alle autorizzazioni host per le pagine in cui inserire gli script. Utilizza la chiave "host_permissions" o l'autorizzazione "activeTab", che concede autorizzazioni host temporanee. L'esempio seguente utilizza l'autorizzazione activeTab.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
Concetti e utilizzo
Puoi utilizzare l'API browser.scripting per inserire JavaScript e CSS nei siti web. Questo è simile a ciò che puoi fare con gli script dei contenuti. Tuttavia, utilizzando lo spazio dei nomi browser.scripting, le estensioni possono prendere decisioni in fase di runtime.
Target di injection
Puoi utilizzare il parametro target per specificare un target in cui inserire JavaScript o CSS.
L'unico campo obbligatorio è tabId. Per impostazione predefinita, un'iniezione verrà eseguita nel frame principale della scheda specificata.
function getTabId() { ... }
browser.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() { ... }
browser.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
Puoi anche inserire script in frame specifici di una scheda specificando i singoli ID frame. Per saperne di più sugli ID frame, consulta l'API browser.webNavigation.
function getTabId() { ... }
browser.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.
File
I file vengono specificati come stringhe che rappresentano percorsi relativi alla directory root dell'estensione. Il seguente codice inserisce il file script.js nel frame principale della scheda.
function getTabId() { ... }
browser.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 anziché un file. Questa funzione deve essere una variabile di funzione disponibile per il contesto dell'estensione corrente.
function getTabId() { ... }
function getTitle() { return document.title; }
browser.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
browser.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
Puoi aggirare questo problema utilizzando la proprietà args:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
browser.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
Stringhe di runtime
Se inserisci il 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; }";
browser.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
Gestisci i risultati
I risultati dell'esecuzione di JavaScript vengono passati all'estensione. Per ogni frame viene incluso un singolo risultato. Il frame principale è garantito come primo indice nell'array risultante; tutti gli altri frame sono in un ordine non deterministico.
function getTabId() { ... }
function getTitle() { return document.title; }
browser.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 risultati.
Promesse
Se il valore risultante dell'esecuzione dello script è una promise, Chrome attenderà che la promise venga risolta e restituirà 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;
}
browser.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
Il seguente snippet 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 browser.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return browser.scripting.unregisterContentScripts({ ids: 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 browser.scripting,
installa l'esempio di scripting dal repository degli esempi di estensioni di Chrome.
Tipi
ContentScriptFilter
Proprietà
-
ids
string[] facoltativo
Se specificato,
getRegisteredContentScriptsrestituirà solo gli script con un ID specificato in questo elenco.
CSSInjection
Proprietà
-
css
stringa facoltativa
Una stringa contenente il CSS da inserire. È necessario specificare esattamente uno dei due valori:
filesocss. -
file
string[] facoltativo
Il percorso dei file CSS da inserire, relativo alla directory root dell'estensione. È necessario specificare esattamente uno dei due valori:
filesocss. -
origine
StyleOrigin facoltativo
L'origine dello stile per l'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 l'ambiente 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+ browser.* da Chrome 148Il documento associato all'inserimento.
-
frameId
numero
Browser Chrome 90 e versioni successive .* da Chrome 148Il frame associato all'inserimento.
-
risultato
any optional
Il risultato dell'esecuzione dello script.
InjectionTarget
Proprietà
-
allFrames
boolean facoltativo
Indica se lo script deve essere inserito in tutti i frame della scheda. Il valore predefinito è false. Questo non deve essere vero se è specificato
frameIds. -
documentIds
string[] facoltativo
Chrome 106+ browser.* da Chrome 148Gli ID di documentId specifici in cui eseguire l'inserimento. Questo valore non deve essere impostato se è impostato
frameIds. -
frameIds
number[] facoltativo
Gli ID di frame specifici in cui eseguire l'inserimento.
-
tabId
numero
L'ID della scheda in cui inserire il codice.
RegisteredContentScript
Proprietà
-
allFrames
boolean facoltativo
Se impostato su true, l'inserimento avverrà in tutti i frame, anche se non si tratta del frame più in alto nella scheda. Ogni frame viene controllato in modo indipendente per i requisiti per gli URL; non verrà inserito nei frame secondari se i requisiti per gli URL non sono soddisfatti. Il valore predefinito è false, il che significa che viene trovata una corrispondenza solo per il frame superiore.
-
css
string[] facoltativo
L'elenco dei file CSS da inserire nelle pagine corrispondenti. Questi vengono inseriti nell'ordine in cui appaiono in questo array, prima che venga costruito o visualizzato un DOM per la pagina.
-
excludeMatches
string[] facoltativo
Esclude le pagine in cui altrimenti verrebbe inserito questo script di contenuti. 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 "_", in quanto è riservato come prefisso per gli ID script generati.
-
js
string[] facoltativo
L'elenco dei file JavaScript da inserire nelle pagine corrispondenti. Questi vengono inseriti nell'ordine in cui appaiono in questo array.
-
matchOriginAsFallback
boolean facoltativo
Chrome 119+ browser.* da Chrome 148Indica 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 degli URL data:), 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 potrebbe non essere il frame principale. -
corrisponde a
string[] facoltativo
Specifica le pagine in cui verrà inserito questo script dei contenuti. Per ulteriori dettagli sulla sintassi di queste stringhe, consulta Pattern di corrispondenza. Deve essere specificato per
registerContentScripts. -
persistAcrossSessions
boolean 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. -
mondo
ExecutionWorld facoltativo
Browser Chrome 102 e versioni successive.* A partire da Chrome 148Il "mondo" JavaScript in cui eseguire lo script. Il valore predefinito è
ISOLATED.
ScriptInjection
Proprietà
-
args
any[] facoltativo
Chrome 92+ browser.* da Chrome 148Gli argomenti da passare alla funzione fornita. Questo è valido solo se viene specificato il parametro
func. Questi argomenti devono essere serializzabili in JSON. -
file
string[] facoltativo
Il percorso dei file JS o CSS da inserire, relativo alla directory root dell'estensione. È necessario specificare esattamente uno dei due valori:
filesofunc. -
injectImmediately
boolean facoltativo
Browser Chrome 102 e versioni successive.* A partire da Chrome 148Indica se l'inserimento deve essere attivato nel target il prima possibile. Tieni presente che questo non garantisce che l'inserimento avvenga prima del caricamento pagina, poiché la pagina potrebbe essere già stata caricata quando lo script raggiunge la destinazione.
-
destinazione
Dettagli che specificano la destinazione in cui inserire lo script.
-
mondo
ExecutionWorld facoltativo
Browser Chrome 95+ .* da Chrome 148Il "mondo" JavaScript in cui eseguire lo script. Il valore predefinito è
ISOLATED. -
func
void optional
Chrome 92+ browser.* da Chrome 148Una funzione JavaScript da inserire. Questa funzione verrà serializzata e poi deserializzata per l'inserimento. Ciò significa che tutti i parametri associati e il contesto di esecuzione andranno persi. È necessario specificare esattamente uno dei due valori:
filesofunc.La funzione
funcha il seguente aspetto:() => {...}
StyleOrigin
L'origine di una modifica dello stile. Per saperne di più, consulta le origini degli stili.
Enum
"AUTHOR"
"USER"
Metodi
executeScript()
browser.scripting.executeScript(
injection: ScriptInjection,
): Promise<InjectionResult[]>
Inserisce uno script in un contesto di destinazione. Per impostazione predefinita, lo script verrà eseguito in document_idle o immediatamente se la pagina è già stata caricata. Se la proprietà injectImmediately è impostata, lo script verrà inserito senza attendere, anche se la pagina non ha terminato il caricamento. Se lo script restituisce una promise, il browser attenderà che la promise venga risolta e restituirà il valore risultante.
Parametri
-
iniezione
I dettagli dello script da inserire.
Resi
-
Promise<InjectionResult[]>
Browser Chrome 90 e versioni successive .* da Chrome 148Restituisce una promessa che viene risolta al completamento dell'inserimento. L'array risultante contiene il risultato dell'esecuzione per ogni frame in cui l'inserimento è andato a buon fine.
getRegisteredContentScripts()
browser.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>
Restituisce tutti gli script dei contenuti registrati dinamicamente per questa estensione che corrispondono al filtro specificato.
Parametri
-
filtro
ContentScriptFilter facoltativo
Un oggetto per filtrare gli script registrati dinamicamente dell'estensione.
Resi
-
Promise<RegisteredContentScript[]>
insertCSS()
browser.scripting.insertCSS(
injection: CSSInjection,
): Promise<void>
Inserisce un foglio di stile CSS in un contesto di destinazione. Se vengono specificati più frame, le inserzioni non riuscite vengono ignorate.
Parametri
-
iniezione
I dettagli degli stili da inserire.
Resi
-
Promise<void>
Browser Chrome 90 e versioni successive .* da Chrome 148Restituisce una promessa che viene risolta al completamento dell'inserimento.
registerContentScripts()
browser.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
Registra uno o più script dei 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 oppure se gli ID specificati esistono già, non viene registrato alcuno script.
Resi
-
Promise<void>
Restituisce una Promise che si risolve una volta che gli script sono stati completamente registrati o rifiuta se si è verificato un errore.
removeCSS()
browser.scripting.removeCSS(
injection: CSSInjection,
): Promise<void>
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,fileseorigindevono corrispondere esattamente al foglio di stile inserito tramiteinsertCSS. Il tentativo di rimuovere un foglio di stile inesistente non ha alcun effetto.
Resi
-
Promise<void>
Restituisce una promessa che si risolve al completamento della rimozione.
unregisterContentScripts()
browser.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
): Promise<void>
Annulla la registrazione degli script di contenuti per questa estensione.
Parametri
-
filtro
ContentScriptFilter facoltativo
Se specificato, annulla la registrazione solo degli script di contenuti dinamici che corrispondono al filtro. In caso contrario, la registrazione di tutti gli script di contenuti dinamici dell'estensione viene annullata.
Resi
-
Promise<void>
Restituisce una Promise che si risolve una volta annullata la registrazione degli script o che viene rifiutata se si è verificato un errore.
updateContentScripts()
browser.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
Aggiorna uno o più script dei 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 oppure se gli ID specificati non corrispondono a uno script completamente registrato, non viene aggiornato alcuno script.
Resi
-
Promise<void>
Restituisce una Promise che si risolve una volta aggiornati gli script o che viene rifiutata se si è verificato un errore.