chrome.scripting

Descrizione

Utilizza l'API chrome.scripting per eseguire lo script in contesti diversi.

Autorizzazioni

scripting

Disponibilità

Chrome 88 e versioni successive MV3 o versioni successive

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"));

Nota:non puoi specificare entrambe le proprietà "frameIds" e "allFrames".

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});
  }
}

Punto chiave: l'annullamento della registrazione degli script di contenuti non comporta la rimozione degli script o degli stili che sono già stati inseriti.

Per provare l'API chrome.scripting, installa l'esempio di script dal repository degli esempi di estensioni di Chrome.

Tipi

ContentScriptFilter

Chrome 96 e versioni successive

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 e css.

• file

  string[] facoltativo

  Il percorso dei file CSS da inserire in relazione alla directory radice dell'estensione. È necessario specificare esattamente uno tra files e css.

• origine

  StyleOrigin facoltativo

  L'origine dello stile dell'inserimento. Il valore predefinito è 'AUTHOR'.

• destinazione

  InjectionTarget

  Dettagli che specificano la destinazione in cui inserire il CSS.

ExecutionWorld

Chrome 95 e versioni successive

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 successive

  Il documento associato all'iniezione.

• frameId

  numero

  Chrome 90 e versioni successive

  Il 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 successive

  Gli 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

Chrome 96 e versioni successive

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 successive

  Indica 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 successive

  Il "mondo" JavaScript in cui eseguire lo script. Il valore predefinito è ISOLATED.

ScriptInjection

Proprietà

• args

  any[] facoltativo

  Chrome 92 e versioni successive

  Gli 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 o func.

• injectImmediately

  booleano facoltativo

  Chrome 102 e versioni successive

  Indica 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

  InjectionTarget

  Dettagli che specificano la destinazione in cui inserire lo script.

• internazionali

  ExecutionWorld facoltativo

  Chrome 95 e versioni successive

  Il "mondo" JavaScript in cui eseguire lo script. Il valore predefinito è ISOLATED.

• func

  void facoltativo

  Chrome 92 e versioni successive

  Una 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 o func.

  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()

Promessa

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

  ScriptInjection

  I dettagli dello script da inserire.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  (results: InjectionResult[])=>void

  • risultati

    InjectionResult[]

Ritorni

• Promise<InjectionResult[]>

  Chrome 90 e versioni successive

  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.

getRegisteredContentScripts()

Promessa Chrome 96 e versioni successive

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

    RegisteredContentScript[]

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()

Promessa

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

  CSSInjection

  I dettagli degli stili da inserire.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  ()=>void

Ritorni

• Promise<void>

  Chrome 90 e versioni successive

  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.

registerContentScripts()

Promessa Chrome 96 e versioni successive

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Registra uno o più script di contenuti per questa estensione.

Parametri

• script

  RegisteredContentScript[]

  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()

Promessa Chrome 90 e versioni successive

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

  CSSInjection

  I dettagli degli stili da rimuovere. Tieni presente che le proprietà css, files e origin devono corrispondere esattamente al foglio di stile inserito tramite insertCSS. 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()

Promessa Chrome 96 e versioni successive

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()

Promessa Chrome 96 e versioni successive

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Aggiorna uno o più script di contenuti per questa estensione.

Parametri

• script

  RegisteredContentScript[]

  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.