chrome.scripting

Beschrijving

Gebruik de chrome.scripting API om scripts in verschillende contexten uit te voeren.

Machtigingen

scripting

Beschikbaarheid

Chroom 88+ MV3+

Manifest

Als u de chrome.scripting API wilt gebruiken, geeft u de machtiging "scripting" op in het manifest , plus de hostmachtigingen voor de pagina's waarin scripts moeten worden geïnjecteerd. Gebruik de sleutel "host_permissions" of de machtiging "activeTab" , die tijdelijke hostmachtigingen verleent. In het volgende voorbeeld wordt de activeTab-machtiging gebruikt.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

Concepten en gebruik

U kunt de chrome.scripting API gebruiken om JavaScript en CSS in websites te injecteren. Dit is vergelijkbaar met wat u kunt doen met inhoudsscripts . Maar door de naamruimte chrome.scripting te gebruiken, kunnen extensies tijdens runtime beslissingen nemen.

Injectiedoelen

U kunt de target parameter gebruiken om een ​​doel op te geven waarin JavaScript of CSS moet worden geïnjecteerd.

Het enige verplichte veld is tabId . Standaard wordt een injectie uitgevoerd in het hoofdframe van het opgegeven tabblad.

function getTabId() { ... }

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

Om in alle frames van het opgegeven tabblad te worden uitgevoerd, kunt u de boolean allFrames instellen op true .

function getTabId() { ... }

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

U kunt ook in specifieke frames van een tabblad injecteren door individuele frame-ID's op te geven. Zie de chrome.webNavigation API voor meer informatie over frame-ID's.

function getTabId() { ... }

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

Geïnjecteerde code

Extensies kunnen de code specificeren die moet worden geïnjecteerd via een extern bestand of een runtimevariabele.

Bestanden

Bestanden worden gespecificeerd als tekenreeksen die paden zijn ten opzichte van de hoofdmap van de extensie. De volgende code injecteert het bestand script.js in het hoofdframe van het tabblad.

function getTabId() { ... }

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

Runtime-functies

Wanneer u JavaScript injecteert met scripting.executeScript() , kunt u een functie opgeven die moet worden uitgevoerd in plaats van een bestand. Deze functie moet een functievariabele zijn die beschikbaar is voor de huidige extensiecontext.

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

U kunt dit omzeilen door de eigenschap args te gebruiken:

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

Runtime-reeksen

Als u CSS binnen een pagina injecteert, kunt u ook een tekenreeks opgeven die in de css eigenschap moet worden gebruikt. Deze optie is alleen beschikbaar voor scripting.insertCSS() ; je kunt een tekenreeks niet uitvoeren met scripting.executeScript() .

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

Behandel de resultaten

De resultaten van het uitvoeren van JavaScript worden doorgegeven aan de extensie. Per frame wordt één resultaat opgenomen. Het hoofdframe is gegarandeerd de eerste index in de resulterende array; alle andere frames bevinden zich in een niet-deterministische volgorde. 

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() retourneert geen resultaten.

Beloften

Als de resulterende waarde van de scriptuitvoering een belofte is, wacht Chrome tot de belofte is afgehandeld en retourneert de resulterende waarde. 

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

Voorbeelden

Maak de registratie van alle dynamische inhoudsscripts ongedaan

Het volgende fragment bevat een functie die de registratie van alle dynamische inhoudsscripts ongedaan maakt die de extensie eerder heeft geregistreerd. 

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

Als u de chrome.scripting API wilt uitproberen, installeert u het scriptvoorbeeld uit de opslagplaats met voorbeelden van Chrome-extensies .

Soorten

ContentScriptFilter

Chroom 96+

Eigenschappen

  • ID's

    tekenreeks[] optioneel

    Indien opgegeven, retourneert getRegisteredContentScripts alleen scripts met een ID die in deze lijst is opgegeven.

CSSInjection

Eigenschappen

  • css

    tekenreeks optioneel

    Een tekenreeks met de CSS die moet worden geïnjecteerd. Precies één van files en css moet worden opgegeven.

  • bestanden

    tekenreeks[] optioneel

    Het pad van de CSS-bestanden die moeten worden geïnjecteerd, relatief ten opzichte van de hoofdmap van de extensie. Precies één van files en css moet worden opgegeven.

  • oorsprong

    StyleOrigin optioneel

    De stijloorsprong voor de injectie. Standaard ingesteld op 'AUTHOR' .

  • Details die het doel specificeren waarin de CSS moet worden ingevoegd.

ExecutionWorld

Chroom 95+

De JavaScript-wereld waarin een script kan worden uitgevoerd.

Enum

"GEÏSOLEERD"
Specificeert de geïsoleerde wereld, de uitvoeringsomgeving die uniek is voor deze extensie.

"VOORNAAMST"
Specificeert de hoofdwereld van de DOM, de uitvoeringsomgeving die wordt gedeeld met het JavaScript van de hostpagina.

InjectionResult

Eigenschappen

  • documentId

    snaar

    Chroom 106+

    Het document dat bij de injectie hoort.

  • frameId

    nummer

    Chroom 90+

    Het frame dat bij de injectie hoort.

  • resultaat

    eventueel optioneel

    Het resultaat van de uitvoering van het script.

InjectionTarget

Eigenschappen

  • alleFrames

    Booleaans optioneel

    Of het script in alle frames binnen het tabblad moet worden geïnjecteerd. Standaard ingesteld op false. Dit mag niet waar zijn als frameIds is opgegeven.

  • documentIds

    tekenreeks[] optioneel

    Chroom 106+

    De ID's van specifieke documentIds waarin moet worden geïnjecteerd. Dit mag niet worden ingesteld als frameIds is ingesteld.

  • frameIds

    nummer[] optioneel

    De ID's van specifieke frames waarin moet worden geïnjecteerd.

  • tabId

    nummer

    De ID van het tabblad waarin moet worden geïnjecteerd.

RegisteredContentScript

Chroom 96+

Eigenschappen

  • alleFrames

    Booleaans optioneel

    Als u 'true' specificeert, wordt het in alle frames geïnjecteerd, zelfs als het frame niet het bovenste frame op het tabblad is. Elk frame wordt onafhankelijk gecontroleerd op URL-vereisten; het wordt niet in onderliggende frames geïnjecteerd als niet aan de URL-vereisten wordt voldaan. Standaard ingesteld op false, wat betekent dat alleen het bovenste frame overeenkomt.

  • css

    tekenreeks[] optioneel

    De lijst met CSS-bestanden die in overeenkomende pagina's moeten worden geïnjecteerd. Deze worden geïnjecteerd in de volgorde waarin ze in deze array verschijnen, voordat er een DOM voor de pagina wordt gemaakt of weergegeven.

  • wedstrijden uitsluiten

    tekenreeks[] optioneel

    Exclusief pagina's waarin dit inhoudsscript anders zou worden geïnjecteerd. Zie Matchpatronen voor meer details over de syntaxis van deze tekenreeksen.

  • Identiteitskaart

    snaar

    De id van het inhoudsscript, opgegeven in de API-aanroep. Mag niet beginnen met een '_', omdat dit is gereserveerd als voorvoegsel voor gegenereerde script-ID's.

  • js

    tekenreeks[] optioneel

    De lijst met JavaScript-bestanden die in overeenkomende pagina's moeten worden geïnjecteerd. Deze worden geïnjecteerd in de volgorde waarin ze in deze array verschijnen.

  • matchOriginAsFallback

    Booleaans optioneel

    Chroom 119+

    Geeft aan of het script kan worden geïnjecteerd in frames waarvan de URL een niet-ondersteund schema bevat; specifiek: about:, data:, blob: of bestandssysteem:. In deze gevallen wordt de oorsprong van de URL gecontroleerd om te bepalen of het script moet worden geïnjecteerd. Als de oorsprong null is (zoals het geval is voor data: URL's), dan is de gebruikte oorsprong ofwel het frame dat het huidige frame heeft gemaakt, ofwel het frame dat de navigatie naar dit frame heeft geïnitieerd. Houd er rekening mee dat dit mogelijk niet het bovenliggende frame is.

  • wedstrijden

    tekenreeks[] optioneel

    Specificeert op welke pagina's dit inhoudsscript wordt geïnjecteerd. Zie Matchpatronen voor meer details over de syntaxis van deze tekenreeksen. Moet worden opgegeven voor registerContentScripts .

  • persistentAcrossSessions

    Booleaans optioneel

    Geeft aan of dit inhoudsscript in toekomstige sessies blijft bestaan. De standaardwaarde is waar.

  • rennenBij

    RunAt optioneel

    Specificeert wanneer JavaScript-bestanden in de webpagina worden geïnjecteerd. De voorkeurs- en standaardwaarde is document_idle .

  • wereld

    ExecutionWorld optioneel

    Chroom 102+

    De JavaScript-"wereld" waarin het script wordt uitgevoerd. Standaard ingesteld op ISOLATED .

ScriptInjection

Eigenschappen

  • arg

    elke [] optioneel

    Chroom 92+

    De argumenten die moeten worden doorgegeven aan de opgegeven functie. Dit is alleen geldig als de func parameter is opgegeven. Deze argumenten moeten JSON-serialiseerbaar zijn.

  • bestanden

    tekenreeks[] optioneel

    Het pad van de JS- of CSS-bestanden die moeten worden geïnjecteerd, relatief ten opzichte van de hoofdmap van de extensie. Precies één van files of func moet worden opgegeven.

  • injecteer onmiddellijk

    Booleaans optioneel

    Chroom 102+

    Of de injectie zo snel mogelijk in het doel moet worden geactiveerd. Houd er rekening mee dat dit geen garantie is dat de injectie plaatsvindt vóór het laden van de pagina, aangezien de pagina mogelijk al is geladen tegen de tijd dat het script het doel bereikt.

  • Details die het doel specificeren waarin het script moet worden geïnjecteerd.

  • wereld

    ExecutionWorld optioneel

    Chroom 95+

    De JavaScript-"wereld" waarin het script wordt uitgevoerd. Standaard ingesteld op ISOLATED .

  • func

    ongeldig optioneel

    Chroom 92+

    Een JavaScript-functie om te injecteren. Deze functie wordt geserialiseerd en vervolgens gedeserialiseerd voor injectie. Dit betekent dat alle gebonden parameters en uitvoeringscontext verloren gaan. Precies één van files of func moet worden opgegeven.

    De func functie ziet er als volgt uit: 

    () => {...}

StyleOrigin

De oorsprong voor een stijlverandering. Zie stijloorsprong voor meer informatie.

Enum

"AUTEUR"

"GEBRUIKER"

Methoden

executeScript()

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

Injecteert een script in een doelcontext. Standaard wordt het script uitgevoerd op document_idle , of onmiddellijk als de pagina al is geladen. Als de eigenschap injectImmediately is ingesteld, wordt het script zonder wachten geïnjecteerd, zelfs als de pagina nog niet is geladen. Als het script een belofte oplevert, wacht de browser tot de belofte is afgehandeld en retourneert de resulterende waarde.

Parameters

Retouren

  • Belofte< InjectieResultaat []>

    Chroom 90+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getRegisteredContentScripts()

BeloofChrome 96+
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Retourneert alle dynamisch geregistreerde inhoudsscripts voor deze extensie die overeenkomen met het opgegeven filter.

Parameters

Retouren

  • Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

insertCSS()

Belofte
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

Voegt een CSS-stylesheet in een doelcontext in. Als er meerdere frames zijn opgegeven, worden mislukte injecties genegeerd.

Parameters

  • injectie

    CSSInjectie

    De details van de stijlen die moeten worden ingevoegd.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 90+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

registerContentScripts()

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

Registreert een of meer inhoudsscripts voor deze extensie.

Parameters

  • Bevat een lijst met scripts die moeten worden geregistreerd. Als er fouten optreden tijdens het parseren van scripts/bestandsvalidatie, of als de opgegeven ID's al bestaan, worden er geen scripts geregistreerd.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

removeCSS()

BeloofChrome 90+
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

Verwijdert een CSS-stylesheet die eerder door deze extensie is ingevoegd uit een doelcontext.

Parameters

  • injectie

    CSSInjectie

    De details van de stijlen die moeten worden verwijderd. Houd er rekening mee dat de css , files en origin eigenschappen exact moeten overeenkomen met het stylesheet dat is ingevoegd via insertCSS . Een poging om een ​​niet-bestaand stylesheet te verwijderen is een no-op.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

unregisterContentScripts()

BeloofChrome 96+
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Maakt de registratie van inhoudsscripts voor deze extensie ongedaan.

Parameters

  • filter

    ContentScriptFilter optioneel

    Indien opgegeven, worden alleen dynamische inhoudsscripts uitgeschreven die overeenkomen met het filter. Anders worden alle dynamische inhoudsscripts van de extensie niet meer geregistreerd.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

updateContentScripts()

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

Werkt een of meer inhoudsscripts voor deze extensie bij.

Parameters

  • Bevat een lijst met scripts die moeten worden bijgewerkt. Een eigenschap wordt alleen bijgewerkt voor het bestaande script als deze in dit object is opgegeven. Als er fouten optreden tijdens het parseren van scripts/bestandsvalidatie, of als de opgegeven ID's niet overeenkomen met een volledig geregistreerd script, worden er geen scripts bijgewerkt.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.