browser.scripting

Beschrijving

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

Rechten

scripting

Beschikbaarheid

Chrome 88+ browser.* sinds Chrome 148 MV3+

Manifest

Als je de browser.scripting API wilt gebruiken, definieer je het recht "scripting" in het manifest plus de hostrechten voor de pagina's waarin je scripts wilt injecteren. Gebruik de sleutel "host_permissions" of het recht "activeTab", waarmee tijdelijke hostrechten worden verleend. In het volgende voorbeeld wordt het recht activeTab gebruikt.

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

Concepten en gebruik

Je kunt de browser.scripting API gebruiken om JavaScript en CSS in websites te injecteren. Dit is vergelijkbaar met wat je kunt doen met contentscripts. Maar door de naamruimte browser.scripting te gebruiken, kunnen extensies beslissingen nemen tijdens de runtime.

Injectiedoelen

Je kunt de parameter target 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 aangegeven tabblad.

function getTabId() { ... }

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

Als je de extensie wilt uitvoeren in alle frames van het aangegeven tabblad, stel je de booleaanse waarde allFrames in op true.

function getTabId() { ... }

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

Je kunt ook injecteren in specifieke frames van een tabblad door afzonderlijke frame-ID's op te geven. Ga naar de browser.webNavigation API voor meer informatie over frame-ID's.

function getTabId() { ... }

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

Opmerking: Je kunt niet zowel de property "frameIds" als de property "allFrames" opgeven.

Geïnjecteerde code

Extensies kunnen de code die moet worden geïnjecteerd, specificeren via een extern bestand of een runtime-variabele.

Bestanden

Bestanden worden gespecificeerd als tekenreeksen die paden zijn ten opzichte van de root-map van de extensie. Met de volgende code wordt het bestand script.js geïnjecteerd in het hoofdframe van het tabblad.

function getTabId() { ... }

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

Runtime-functies

Als je JavaScript injecteert met scripting.executeScript(), kun je 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; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

U kunt dit omzeilen door de property args te gebruiken:

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

Runtime-tekenreeksen

Als je css in een pagina injecteert, kun je ook een tekenreeks invoeren die wordt gebruikt in de property css. Deze optie is alleen beschikbaar voor scripting.insertCSS(). Je kunt geen tekenreeks uitvoeren met scripting.executeScript().

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

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

De resultaten verwerken

De resultaten van de uitvoering van JavaScript worden doorgegeven aan de extensie. Er wordt één resultaat per frame opgenomen. Het hoofdframe is gegarandeerd de eerste index in de resulterende matrix. Alle andere frames staan in een niet-deterministische volgorde.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.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 promise is, wacht Chrome tot de promise 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;
}

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

Registratie van alle dynamische contentscripts ongedaan maken

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

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await browser.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return browser.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

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

Als je de browser.scripting API wilt proberen, installeer je het scriptvoorbeeld uit de repository met voorbeelden van Chrome-extensies.

Typen

ContentScriptFilter

Chrome 96+ browser.* sinds Chrome 148

Eigenschappen

• ID's

  string[] optioneel

  Als u dit opgeeft, 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. Er moet precies één van files en css worden ingevoerd.

• bestanden

  string[] optioneel

  Het pad van de css-bestanden die moeten worden geïnjecteerd, ten opzichte van de root-map van de extensie. Er moet precies één van files en css worden ingevoerd.

• oorsprong

  StyleOrigin optioneel

  De stijloorsprong voor de injectie. De standaardwaarde is 'AUTHOR'.

• target

  InjectionTarget

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

ExecutionWorld

Chrome 95+ browser.* sinds Chrome 148

De JavaScript-wereld waarin een script moet worden uitgevoerd.

Enum

ISOLATED
Hiermee wordt de geïsoleerde wereld aangegeven. Dit is de uitvoeringsomgeving die uniek is voor deze extensie.

MAIN
Hiermee wordt de hoofdwereld van het DOM aangegeven. Dit is de uitvoeringsomgeving die wordt gedeeld met het JavaScript van de hostpagina.

InjectionResult

Eigenschappen

• documentId

  tekenreeks

  Chrome 106 of hoger browser.* sinds Chrome 148

  Het document dat aan de injectie is gekoppeld.

• frameId

  getal

  Chrome 90 of hoger browser.* sinds Chrome 148

  Het frame dat is gekoppeld aan de injectie.

• resultaat

  alleen optioneel

  Het resultaat van de scriptuitvoering.

InjectionTarget

Eigenschappen

• allFrames

  booleaans optioneel

  Of het script moet worden geïnjecteerd in alle frames binnen het tabblad. De standaard is onwaar. Dit mag niet waar zijn als frameIds is ingevoerd.

• documentIds

  string[] optioneel

  Chrome 106 of hoger browser.* sinds Chrome 148

  De ID's van specifieke document-ID's waarin je wilt injecteren. Dit mag niet worden ingesteld als frameIds is ingesteld.

• frameIds

  number[] optioneel

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

• tabId

  getal

  De ID van het tabblad waarin de injectie moet worden uitgevoerd.

RegisteredContentScript

Chrome 96+ browser.* sinds Chrome 148

Eigenschappen

• allFrames

  booleaans optioneel

  Als je true invoert, wordt het script in alle frames geïnjecteerd, zelfs als het frame niet het bovenste frame op het tabblad is. Elk frame wordt onafhankelijk gecontroleerd op vereisten voor URL's. De extensie wordt niet geïnjecteerd in onderliggende frames als niet aan de vereisten voor URL's wordt voldaan. De standaardwaarde is onwaar, wat betekent dat alleen het bovenste frame wordt gevonden.

• css

  string[] optioneel

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

• excludeMatches

  string[] optioneel

  Sluit pagina's uit waarin dit contentscript anders zou worden geïnjecteerd. Ga naar Overeenkomstpatronen voor meer informatie over de syntaxis van deze tekenreeksen.

• id

  tekenreeks

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

• js

  string[] optioneel

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

• matchOriginAsFallback

  booleaans optioneel

  Chrome 119+ browser.* sinds Chrome 148

  Geeft aan of het script kan worden geïnjecteerd in frames waarin de URL een niet-ondersteund schema bevat, met name: about:, data:, blob: of filesystem:. 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), is de gebruikte oorsprong het frame dat het huidige frame heeft gemaakt of het frame dat de navigatie naar dit frame heeft gestart. Dit is misschien niet het bovenliggende frame.

• komt overeen

  string[] optioneel

  Geeft aan op welke pagina's dit contentscript wordt geïnjecteerd. Ga naar Overeenkomstpatronen voor meer informatie over de syntaxis van deze tekenreeksen. Moet worden ingevoerd voor registerContentScripts.

• persistAcrossSessions

  booleaans optioneel

  Geeft aan of dit contentscript blijft bestaan in toekomstige sessies. De standaardwaarde is true.

• runAt

  RunAt optioneel

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

• wereld

  ExecutionWorld optioneel

  Chrome 102 of hoger browser.* sinds Chrome 148

  De JavaScript-wereld waarin het script moet worden uitgevoerd. De standaardwaarde is ISOLATED.

ScriptInjection

Eigenschappen

• arg

  any[] optioneel

  Chrome 92+ browser.* sinds Chrome 148

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

• bestanden

  string[] optioneel

  Het pad van de JS- of CSS-bestanden die moeten worden geïnjecteerd, ten opzichte van de root-map van de extensie. Er moet precies één files of func worden ingevoerd.

• injectImmediately

  booleaans optioneel

  Chrome 102 of hoger browser.* sinds Chrome 148

  Of de injectie zo snel mogelijk in het doel moet worden geactiveerd. Dit is geen garantie dat de injectie plaatsvindt voordat de pagina wordt geladen, omdat de pagina misschien al is geladen op het moment dat het script het doel bereikt.

• target

  InjectionTarget

  Informatie over het doel waarin het script moet worden geïnjecteerd.

• wereld

  ExecutionWorld optioneel

  Chrome 95+ browser.* sinds Chrome 148

  De JavaScript-wereld waarin het script moet worden uitgevoerd. De standaardwaarde is ISOLATED.

• func

  void optioneel

  Chrome 92+ browser.* sinds Chrome 148

  Een JavaScript-functie die moet worden geïnjecteerd. Deze functie wordt geserialiseerd en daarna gedeserialiseerd voor injectie. Dit betekent dat alle gebonden parameters en de uitvoeringscontext verloren gaan. Er moet precies één files of func worden ingevoerd.

  De functie func ziet er zo uit:

  () => {...}

StyleOrigin

De oorsprong van een stijlwijziging. Ga naar stijloorsprongen voor meer informatie.

Enum

"AUTHOR"

"USER"

Methoden

executeScript()

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

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

Parameters

• injectie

  ScriptInjection

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

Retourzendingen

• Promise<InjectionResult[]>

  Chrome 90 of hoger browser.* sinds Chrome 148

  Retourneert een Promise die wordt opgelost nadat de injectie is afgerond. De resulterende matrix bevat het resultaat van de uitvoering voor elk frame waarin de injectie is geslaagd.

getRegisteredContentScripts()

Chrome 96+ browser.* sinds Chrome 148

browser.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

Retourneert alle dynamisch geregistreerde contentscripts 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.

Retourzendingen

• Promise<RegisteredContentScript[]>

insertCSS()

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

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

Parameters

• injectie

  CSSInjection

  De details van de stijlen die moeten worden ingevoegd.

Retourzendingen

• Promise<void>

  Chrome 90 of hoger browser.* sinds Chrome 148

  Retourneert een Promise die wordt opgelost nadat de invoeging is afgerond.

registerContentScripts()

Chrome 96+ browser.* sinds Chrome 148

browser.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Registreert een of meer contentscripts voor deze extensie.

Parameters

• scripts

  RegisteredContentScript[]

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

Retourzendingen

• Promise<void>

  Retourneert een Promise die wordt opgelost zodra scripts volledig zijn geregistreerd of wordt geweigerd als er een fout is opgetreden.

removeCSS()

Chrome 90 of hoger browser.* sinds Chrome 148

browser.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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

Parameters

• injectie

  CSSInjection

  De details van de stijlen die je wilt verwijderen. De eigenschappen css, files en origin moeten exact overeenkomen met de stylesheet die is ingevoegd via insertCSS. Poging om een niet-bestaande stylesheet te verwijderen is een no-op.

Retourzendingen

• Promise<void>

  Retourneert een Promise die wordt opgelost nadat de verwijdering is afgerond.

unregisterContentScripts()

Chrome 96+ browser.* sinds Chrome 148

browser.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Maakt de registratie van contentscripts voor deze extensie ongedaan.

Parameters

• filter

  ContentScriptFilter optioneel

  Als dit is opgegeven, wordt alleen de registratie van dynamische contentscripts ongedaan gemaakt die overeenkomen met het filter. Anders wordt de registratie van alle dynamische contentscripts van de extensie ongedaan gemaakt.

Retourzendingen

• Promise<void>

  Retourneert een Promise die wordt opgelost nadat de registratie van scripts ongedaan is gemaakt of die wordt afgewezen als er een fout is opgetreden.

updateContentScripts()

Chrome 96+ browser.* sinds Chrome 148

browser.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Updatet een of meer contentscripts voor deze extensie.

Parameters

• scripts

  RegisteredContentScript[]

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

Retourzendingen

• Promise<void>

  Retourneert een Promise die wordt opgelost nadat de scripts zijn geüpdatet of wordt afgewezen als er een fout is opgetreden.