chrome.scripting (original) (raw)

Descrizione

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

Autorizzazioni

scripting

Disponibilità

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

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

Proprietà

CSSInjection

Proprietà

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

InjectionResult

Proprietà

InjectionTarget

Proprietà

RegisteredContentScript

Proprietà

ScriptInjection

Proprietà

StyleOrigin

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

Enum

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.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

Restituisce tutti gli script di contenuti registrati dinamicamente per questa estensione che corrispondono al filtro specificato.

Parametri

Resi

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise

Inserisce un foglio di stile CSS in un contesto di destinazione. Se vengono specificati più frame, le iniezioni non riuscite vengono ignorate.

Parametri

Resi

registerContentScripts()

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise

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

Parametri

Resi

removeCSS()

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise

Rimuove un foglio di stile CSS inserito in precedenza da questa estensione da un contesto di destinazione.

Parametri

Resi

unregisterContentScripts()

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise

Annulla la registrazione degli script di contenuti per questa estensione.

Parametri

Resi

updateContentScripts()

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise

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

Parametri

Resi