chrome.scripting

Beschrijving

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

Machtigingen

scripting

Beschikbaarheid

Chroom 88+ MV3+

Manifest

Om de chrome.scripting API te gebruiken, declareert u de machtiging "scripting" in het manifest plus de hostmachtigingen voor de pagina's waarin u scripts wilt injecteren. Gebruik de sleutel "host_permissions" of de machtiging "activeTab" , die tijdelijke hostmachtigingen verleent. In het volgende voorbeeld wordt de machtiging 'activeTab' gebruikt.

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

Begrippen en gebruik

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

Injectiedoelen

U kunt de target -parameter gebruiken om een doel op te geven waarin u JavaScript of CSS wilt injecteren.

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 te injecteren code specificeren via een extern bestand of een runtime-variabele.

Bestanden

Bestanden worden gespecificeerd als strings die paden zijn die relatief 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-strings

Als u CSS in een pagina injecteert, kunt u ook een string opgeven die in de css eigenschap moet worden gebruikt. Deze optie is alleen beschikbaar voor scripting.insertCSS() ; u kunt geen string 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"));

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 array; alle andere frames staan 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 totdat de belofte is verwerkt 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

Alle dynamische inhoudsscripts afmelden

Het volgende fragment bevat een functie waarmee u alle dynamische inhoudsscripts die de extensie eerder heeft geregistreerd, kunt afmelden. 

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

Om de chrome.scripting API uit te proberen, installeert u het scriptvoorbeeld uit de repository met Chrome-extensievoorbeelden .

Typen

ContentScriptFilter

Chroom 96+

Eigenschappen

  • id's

    string[] optioneel

    Als dit is opgegeven, retourneert getRegisteredContentScripts alleen scripts met een id die in deze lijst is opgegeven.

CSSInjection

Eigenschappen

  • css

    string optioneel

    Een string met de te injecteren CSS. Er moet precies één van files en css worden gespecificeerd.

  • bestanden

    string[] optioneel

    Het pad van de te injecteren CSS-bestanden, relatief ten opzichte van de hoofdmap van de extensie. Er moet precies één van files en css worden opgegeven.

  • oorsprong

    StyleOrigin optioneel

    De stijloorsprong voor de injectie. Standaard is dit 'AUTHOR' .

  • Details over het doel waarin de CSS moet worden ingevoegd.

ExecutionWorld

Chroom 95+

De JavaScript-wereld waarin een script kan worden uitgevoerd.

Enum

"GEÏSOLEERD"
Geeft de geïsoleerde wereld aan. Dit is de uitvoeringsomgeving die uniek is voor deze extensie.

"VOORNAAMST"
Geeft de hoofdwereld van de DOM aan. Dit is de uitvoeringsomgeving die wordt gedeeld met het JavaScript van de hostpagina.

InjectionResult

Eigenschappen

  • document-ID

    snaar

    Chroom 106+

    Het document dat bij de injectie hoort.

  • frame-ID

    nummer

    Chroom 90+

    Het frame dat bij de injectie hoort.

  • resultaat

    elke optionele

    Het resultaat van de scriptuitvoering.

InjectionTarget

Eigenschappen

  • alleFrames

    boolean optioneel

    Of het script in alle frames binnen het tabblad moet injecteren. Standaard is dit false. Dit mag niet waar zijn als frameIds is opgegeven.

  • document-ID's

    string[] optioneel

    Chroom 106+

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

  • frame-ID's

    nummer[] optioneel

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

  • tabbladId

    nummer

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

RegisteredContentScript

Chroom 96+

Eigenschappen

  • alleFrames

    boolean optioneel

    Indien true gespecificeerd, wordt de URL in alle frames geïnjecteerd, zelfs als het frame niet het bovenste frame in het tabblad is. Elk frame wordt afzonderlijk gecontroleerd op URL-vereisten; er wordt niet in onderliggende frames geïnjecteerd als niet aan de URL-vereisten wordt voldaan. Standaard is dit false, wat betekent dat alleen het bovenste frame wordt gematcht.

  • css

    string[] optioneel

    De lijst met CSS-bestanden die in de overeenkomende pagina's moeten worden ingevoegd. Deze worden ingevoegd in de volgorde waarin ze in deze array voorkomen, voordat er een DOM voor de pagina wordt geconstrueerd of weergegeven.

  • uitsluitenMatches

    string[] optioneel

    Sluit pagina's uit waarin dit contentscript anders zou worden geïnjecteerd. Zie Matchpatronen voor meer informatie over de syntaxis van deze strings.

  • id

    snaar

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

  • js

    string[] 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 voorkomen.

  • matchOriginAsFallback

    boolean optioneel

    Chroom 119+

    Geeft aan of het script kan worden ingevoegd 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 ingevoegd. Als de oorsprong null is (zoals het geval is bij data: URL's), 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

    string[] optioneel

    Geeft aan in welke pagina's dit contentscript wordt ingevoegd. Zie Match Patterns voor meer informatie over de syntaxis van deze strings. Moet worden opgegeven voor registerContentScripts .

  • persistAcrossSessions

    boolean optioneel

    Geeft aan of dit inhoudsscript in toekomstige sessies behouden blijft. De standaardwaarde is 'true'.

  • rennen op

    RunAt optioneel

    Geeft aan 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 moet worden uitgevoerd. Standaard is dit ISOLATED .

ScriptInjection

Eigenschappen

  • argumenten

    any[] optioneel

    Chroom 92+

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

  • bestanden

    string[] optioneel

    Het pad van de te injecteren JS- of CSS-bestanden, relatief ten opzichte van de hoofdmap van de extensie. Er moet precies één files of func worden opgegeven.

  • Direct injecteren

    boolean optioneel

    Chroom 102+

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

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

  • wereld

    ExecutionWorld optioneel

    Chroom 95+

    De JavaScript-"wereld" waarin het script moet worden uitgevoerd. Standaard is dit ISOLATED .

  • functie

    leeg 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. Er moet precies één files of func worden opgegeven.

    De func -functie ziet er als volgt uit: 

    () => {...}

StyleOrigin

De oorsprong van een stijlverandering. Zie Stijloorsprongen voor meer informatie.

Enum

"AUTEUR"

"GEBRUIKER"

Methoden

executeScript()

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

Injecteert een script in een doelcontext. Standaard wordt het script uitgevoerd op document_idle , of direct als de pagina al geladen is. Als de eigenschap injectImmediately is ingesteld, injecteert het script zonder te wachten, zelfs als de pagina nog niet geladen is. Als het script een promise oplevert, wacht de browser tot de promise is verwerkt en retourneert de resulterende waarde.

Parameters

  • injectie

    ScriptInjectie

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

Retourneren

getRegisteredContentScripts()

Chroom 96+
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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.

Retourneren

insertCSS()

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

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

Parameters

  • injectie

    CSS-injectie

    De details van de in te voegen stijlen.

Retourneren

  • Belofte<leegte>

    Chroom 90+

registerContentScripts()

Chroom 96+
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Registreert een of meer inhoudsscripts voor deze extensie.

Parameters

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

Retourneren

  • Belofte<leegte>

removeCSS()

Chroom 90+
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Verwijdert een CSS-stijlblad dat eerder door deze extensie is ingevoegd uit een doelcontext.

Parameters

  • injectie

    CSS-injectie

    De details van de te verwijderen stijlen. Let op: de eigenschappen css , files en origin moeten exact overeenkomen met het stylesheet dat is ingevoegd via insertCSS . Het verwijderen van een niet-bestaand stylesheet is een no-op.

Retourneren

  • Belofte<leegte>

unregisterContentScripts()

Chroom 96+
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Registreert de inhoudsscripts voor deze extensie niet meer.

Parameters

  • filter

    ContentScriptFilter optioneel

    Indien opgegeven, worden alleen dynamische contentscripts die aan het filter voldoen, gederegistreerd. Anders worden alle dynamische contentscripts van de extensie gederegistreerd.

Retourneren

  • Belofte<leegte>

updateContentScripts()

Chroom 96+
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Werkt een of meer inhoudsscripts bij voor deze extensie.

Parameters

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

Retourneren

  • Belofte<leegte>