chrome.scripting

Beschrijving

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

Rechten

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

Opmerking: u kunt niet zowel de eigenschappen "frameIds" als "allFrames" opgeven.

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

Belangrijk punt: Als u de registratie van inhoudsscripts ongedaan maakt, worden scripts of stijlen die al zijn geïnjecteerd niet verwijderd.

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

• doel

  Injectiedoel

  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.

• ID kaart

  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.

• draaien op

  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, omdat de pagina mogelijk al is geladen tegen de tijd dat het script het doel bereikt.

• doel

  Injectiedoel

  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

• injectie

  ScriptInjectie

  De details van het script dat moet worden geïnjecteerd.

• Bel terug

  functie optioneel

  De callback parameter ziet er als volgt uit:

  (results: InjectionResult[])=>void

  • resultaten

    InjectieResultaat []

Geeft terug

• 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

• filter

  ContentScriptFilter optioneel

  Een object om de dynamisch geregistreerde scripts van de extensie te filteren.

• Bel terug

  functie optioneel

  De callback parameter ziet er als volgt uit:

  (scripts: RegisteredContentScript[])=>void

  • scripts

    Geregistreerde inhoudscript []

Geeft terug

• Belofte< RegisteredContentScript []>

  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.

• Bel terug

  functie optioneel

  De callback parameter ziet er als volgt uit:

  ()=>void

Geeft terug

• 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

• scripts

  Geregistreerde inhoudscript []

  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.

• Bel terug

  functie optioneel

  De callback parameter ziet er als volgt uit:

  ()=>void

Geeft terug

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

• Bel terug

  functie optioneel

  De callback parameter ziet er als volgt uit:

  ()=>void

Geeft terug

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

• Bel terug

  functie optioneel

  De callback parameter ziet er als volgt uit:

  ()=>void

Geeft terug

• 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

• scripts

  Geregistreerde inhoudscript []

  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.

• Bel terug

  functie optioneel

  De callback parameter ziet er als volgt uit:

  ()=>void

Geeft terug

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