chrome.scripting

Descrizione

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

Autorizzazioni

scripting

Disponibilità

Chrome 88+ MV3+

Manifest

Per utilizzare l'API chrome.scripting, dichiara l'autorizzazione "scripting" nel manifest, oltre alle autorizzazioni host per le pagine in cui inserire gli script. Utilizza il tasto "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 chrome.scripting per inserire JavaScript e CSS nei siti web. È simile a quello che puoi fare con gli script dei 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, un'iniezione viene eseguita nel frame principale della scheda specificata.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

Per eseguire l'annuncio 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 codice in frame specifici di una scheda specificando ID frame individuali. Per saperne di più sugli ID frame, consulta l'chrome.webNavigation API.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

Codice iniettato

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 sono percorsi relativi alla directory root dell'estensione. Il seguente codice inserirà 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 anziché 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 aggirare questo 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 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 è incluso un solo risultato. Il frame principale è garantito per essere il primo indice dell'array risultante; tutti gli altri frame sono in un 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 la promessa 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;
}

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

Il seguente snippet contiene una funzione che annulla la registrazione di tutti gli script di contenuti dinamici che l'estensione ha registrato in precedenza.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.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 chrome.scripting, installa l'esempio di scripting dal repository degli esempi di estensioni di Chrome.

Tipi

ContentScriptFilter

Chrome 96+

Proprietà

  • ids

    string[] facoltativo

    Se specificato, getRegisteredContentScripts restituirà 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 valori files e css.

  • file

    string[] facoltativo

    Il percorso dei file CSS da inserire, relativo alla directory root dell'estensione. È necessario specificare esattamente uno dei valori files e css.

  • origine

    StyleOrigin facoltativo

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

  • Dettagli che specificano il target in cui inserire il CSS.

ExecutionWorld

Chrome 95+

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 JavaScript della pagina host.

InjectionResult

Proprietà

  • documentId

    stringa

    Chrome 106+

    Il documento associato all'inserimento.

  • frameId

    numero

    Chrome 90+

    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+

    Gli ID di documentId specifici da inserire. Questo valore non deve essere impostato se è impostato frameIds.

  • frameIds

    number[] facoltativo

    Gli ID di frame specifici da inserire.

  • tabId

    numero

    L'ID della scheda in cui inserire il codice.

RegisteredContentScript

Chrome 96+

Proprietà

  • allFrames

    booleano facoltativo

    Se viene specificato il valore true, viene inserito in tutti i frame, anche se il frame non è il primo nella scheda. Ogni frame viene controllato in modo indipendente per i requisiti dell'URL; non verrà inserito nei frame secondari se i requisiti dell'URL non vengono soddisfatti. Il valore predefinito è false, il che significa che viene abbinato solo il frame principale.

  • css

    string[] facoltativo

    L'elenco dei file CSS da inserire nelle pagine corrispondenti. Vengono inseriti nell'ordine in cui appaiono in questo array, prima che venga costruito o visualizzato qualsiasi 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 del content script, specificato nella chiamata API. Non deve iniziare con "_" perché è 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

    booleano facoltativo

    Chrome 119+

    Indica se lo script può essere inserito nei 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 dei dati), l'origine utilizzata è il frame che ha creato il frame corrente o il frame che ha avviato la navigazione a 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 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.

  • mondo

    ExecutionWorld facoltativo

    Chrome 102+

    L'ambiente JavaScript in cui eseguire lo script. Il valore predefinito è ISOLATED.

ScriptInjection

Proprietà

  • args

    any[] facoltativo

    Chrome 92+

    Gli argomenti da passare alla funzione fornita. Questo è valido solo se è 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 principale dell'estensione. È necessario specificare esattamente uno dei seguenti valori: files o func.

  • injectImmediately

    booleano facoltativo

    Chrome 102+

    Indica se l'inserimento deve essere attivato nella destinazione il prima possibile. Tieni presente che non è garantito che l'inserimento avvenga prima del caricamento della pagina, in quanto la pagina potrebbe essere già stata caricata quando lo script raggiunge la destinazione.

  • Dettagli che specificano il target in cui inserire lo script.

  • mondo

    ExecutionWorld facoltativo

    Chrome 95+

    L'ambiente JavaScript in cui eseguire lo script. Il valore predefinito è ISOLATED.

  • func

    void optional

    Chrome 92+

    Una 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 seguenti valori: files o func.

    La funzione func ha questo aspetto: 

    () => {...}

StyleOrigin

L'origine di una modifica dello stile. Per saperne di più, consulta Origini dello stile.

Enum

"AUTHOR"

"USER"

Metodi

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Inserisce uno script in un contesto di destinazione. Per impostazione predefinita, lo script verrà eseguito alle ore 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 è stata caricata completamente. Se lo script restituisce una promessa, il browser attenderà che la promessa venga risolta e restituirà il valore risultante.

Parametri

Resi

getRegisteredContentScripts()

Chrome 96+ 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

Restituisce tutti gli script di 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

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

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.

Resi

  • Promise<void>

    Chrome 90+

registerContentScripts()

Chrome 96+ 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

Parametri

  • Contiene un elenco di script da registrare. Se si verificano errori durante l'analisi dello script/la convalida del file o se gli ID specificati esistono già, non vengono registrati script.

Resi

  • Promise<void>

removeCSS()

Chrome 90+ 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Rimuove un foglio di stile CSS inserito in precedenza 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'operazione nulla.

Resi

  • Promise<void>

unregisterContentScripts()

Chrome 96+ 
chrome.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, tutti gli script di contenuti dinamici dell'estensione vengono annullati.

Resi

  • Promise<void>

updateContentScripts()

Chrome 96+ 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

Parametri

  • 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/la convalida del file o se gli ID specificati non corrispondono a uno script completamente registrato, non vengono aggiornati script.

Resi

  • Promise<void>