chrome.scripting

Descrizione

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

Autorizzazioni

scripting

Disponibilità

Chrome 88 e versioni successive MV3 o versioni successive

Manifest

Per utilizzare l'API chrome.scripting, dichiara l'autorizzazione "scripting" nel file manifest più le autorizzazioni host per le pagine in cui inserire script. Utilizza la chiave "host_permissions" o l'autorizzazione "activeTab", che concede autorizzazioni temporanee all'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 siti web. È un processo simile a quello che puoi fare con i contenuti script. 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 in CSS.

L'unico campo obbligatorio è tabId. Per impostazione predefinita, viene eseguita un'iniezione 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 a 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 in frame specifici di una scheda specificando singoli frame ID. Per ulteriori informazioni sugli ID frame, consulta la 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 inserito

Le estensioni possono specificare il codice da inserire tramite un file esterno o un di runtime.

File

I file vengono specificati come stringhe che rappresentano percorsi relativi alla radice dell'estensione . Il seguente codice inserirà il file script.js nell'istanza principale frame della scheda.

function getTabId() { ... }

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

Funzioni runtime

Quando inserisci JavaScript con scripting.executeScript(), puoi specificare un valore funzione da eseguire al posto di un file. Questa funzione deve essere una funzione disponibile per il contesto attuale dell'estensione.

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 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 CSS all'interno di una pagina, puoi anche specificare una stringa da utilizzare nella css proprietà. Questa opzione è disponibile solo per scripting.insertCSS(). tu non può 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. Un singolo risultato è incluso per frame. Il frame principale è sicuramente il primo indice nella l'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 attende per la promessa di assestarsi e restituire 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 i contenuti dinamici gli script precedentemente registrati 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 dagli esempi di estensioni di Chrome. repository Git.

Tipi

ContentScriptFilter

Chrome 96 e versioni successive .

Proprietà

CSSInjection

Proprietà

  • css

    stringa facoltativo

    Una stringa contenente il CSS da inserire. È necessario specificare in modo esatto uno tra files e css.

  • file

    string[] facoltativo

    Il percorso dei file CSS da inserire relativo alla directory radice dell'estensione. È necessario specificare in modo esatto uno tra 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 e versioni successive .

Il mondo JavaScript in cui deve essere eseguito uno script.

Enum

"ISOLATED"
Specifica il mondo isolato, che è l'ambiente di esecuzione unico 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'iniezione.

  • risultato

    qualsiasi opzione facoltativa

    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 specifici documentId da inserire. Questo valore non deve essere impostato se è impostato il criterio frameIds.

  • frameIds

    numero[] facoltativo

    Gli ID di frame specifici da inserire.

  • tabId

    numero

    L'ID della scheda in cui inserire.

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 degli URL. non verrà inserito nei frame secondari se non vengono soddisfatti i requisiti degli URL. Il valore predefinito è false, vale a dire che viene abbinata solo la parte superiore del frame.

  • 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

    Esclude le pagine in cui verrebbe altrimenti inserito questo script di contenuti. Consulta Pattern di corrispondenza per ulteriori dettagli sulla sintassi di queste stringhe.

  • 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 di file JavaScript da inserire nelle pagine corrispondenti. che 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 nei frame in cui l'URL contiene uno schema non supportato. in particolare: about:, data:, blob: o filesystem:. In questi casi, viene controllata l'origine dell'URL per determinare se lo script deve essere inserito. Se l'origine è null (come nel caso di 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 potrebbe non essere il frame principale.

  • corrisponde a

    string[] facoltativo

    Specifica le pagine in cui verrà inserito questo script di contenuti. Consulta Pattern di corrispondenza per ulteriori dettagli sulla sintassi di queste stringhe. Deve essere specificato per registerContentScripts.

  • persistAcrossSessions

    booleano facoltativo

    Specifica se questo script di 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 e versioni successive .

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

ScriptInjection

Proprietà

  • argomenti

    qualsiasi[] 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 serializzabili in formato JSON.

  • file

    string[] facoltativo

    Il percorso dei file JS o CSS da inserire, relativo alla directory radice dell'estensione. È necessario specificare in modo esatto uno tra files o func.

  • injectImmediately

    booleano facoltativo

    Chrome 102 e versioni successive .

    Indica se l'inserimento deve essere attivato nel target il prima possibile. Tieni presente che ciò non garantisce che l'inserimento venga eseguito prima del caricamento pagina, poiché quest'ultima potrebbe essere già stata caricata nel momento in cui lo script ha raggiunto il target.

  • Dettagli che specificano la destinazione in cui inserire lo script.

  • mondo

    ExecutionWorld facoltativo

    Chrome 95 e versioni successive .

    Il "mondo" di 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'inserimento. Ciò significa che tutti i parametri associati e il contesto di esecuzione andranno persi. È necessario specificare in modo esatto uno tra files o func.

    La funzione func ha questo aspetto: 

    () => {...}

StyleOrigin

L'origine di un cambiamento di stile. Per saperne di più, consulta la sezione sulle origini degli stili.

Enum

"AUTHOR"

"UTENTE"

Metodi

executeScript()

Promesso .
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

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 il caricamento della pagina non è terminato. Se lo script restituisce una promessa, il browser attende che la promessa si stabilizzi e restituirà il valore risultante.

Parametri

Resi

  • Promise<InjectionResult[]>

    Chrome 90 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getRegisteredContentScripts()

Promesso 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

Resi

  • Promise<RegisteredContentScript[]>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

insertCSS()

Promesso .
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

Resi

  • Promesso<void>

    Chrome 90 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

registerContentScripts()

Promesso Chrome 96 e versioni successive 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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 degli script o la convalida del file oppure se gli ID specificati esistono già, non verrà registrato nessuno script.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

removeCSS()

Promesso 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 non esistente è un'operazione nulla.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

unregisterContentScripts()

Promesso 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

  • filtro

    ContentScriptFilter facoltativo

    Se specificato, vengono annullate solo la registrazione degli script di contenuti dinamici che corrispondono al filtro. In caso contrario, tutti gli script di contenuti dinamici dell'estensione non vengono registrati.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

updateContentScripts()

Promesso Chrome 96 e versioni successive 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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 degli script o la convalida del file o se gli ID specificati non corrispondono a uno script completamente registrato, non viene aggiornato alcuno script.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.