Deze pagina is vertaald door de Cloud Translation API.

chrome.scripting

Beschrijving

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

Toestemmingen

scripting

Beschikbaarheid

Chrome 88+ MV3+

Manifest

Om de chrome.scripting API te gebruiken, moet u de "scripting" -machtiging in het manifest declareren, samen met de hostmachtigingen voor de pagina's waarin u scripts wilt injecteren. Gebruik de sleutel "host_permissions" of de "activeTab" -machtiging, die tijdelijke hostmachtigingen verleent. Het volgende voorbeeld gebruikt de activeTab-machtiging.

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

Concepten en gebruik

Je kunt de chrome.scripting API gebruiken om JavaScript en CSS in websites te injecteren. Dit is vergelijkbaar met wat je kunt doen met content scripts . Maar door de chrome.scripting namespace te gebruiken, kunnen extensies tijdens de uitvoering beslissingen nemen.

Injectiedoelen

Je kunt de parameter target gebruiken om een doel te specificeren waarin JavaScript of CSS moet worden geïnjecteerd.

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

function getTabId() { ... }

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

Om de animatie in alle vensters van het opgegeven tabblad uit te voeren, kunt u de boolean-waarde allFrames op true zetten.

function getTabId() { ... }

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

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

Let op: u kunt niet zowel de eigenschap "frameIds" als de eigenschap "allFrames" opgeven.

Geïnjecteerde code

Extensies kunnen specificeren welke code moet worden geïnjecteerd, hetzij via een extern bestand, hetzij via een runtimevariabele.

Bestanden

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

function getTabId() { ... }

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

Runtimefuncties

Bij het injecteren van JavaScript 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 in 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"));

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

Verwerk de resultaten

De resultaten van de JavaScript-uitvoering worden doorgegeven aan de extensie. Per frame wordt één resultaat opgenomen. Het hoofdframe is gegarandeerd het eerste frame in de resulterende array; alle andere frames staan in een willekeurige 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() geeft geen resultaten terug.

Beloftes

Als de uitvoer van het script een promise oplevert, wacht Chrome tot de promise is afgehandeld en retourneert vervolgens 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

Deactiveer alle scripts voor dynamische inhoud.

Het volgende codefragment bevat een functie die alle dynamische content-scripts die de extensie eerder heeft geregistreerd, ongedaan maakt.

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, installeer je het scriptvoorbeeld uit de Chrome-extensievoorbeeldenrepository .

Soorten

ContentScriptFilter

Chrome 96+

Eigenschappen

id's
string[] optioneel
Indien gespecificeerd, retourneert getRegisteredContentScripts alleen scripts met een id die in deze lijst is opgegeven.

CSSInjection

Eigenschappen

css
string optioneel
Een tekenreeks met de CSS die moet worden geïnjecteerd. Er moet precies één van de volgende opties worden opgegeven: files en css .
bestanden
string[] optioneel
Het pad naar de CSS-bestanden die moeten worden geïnjecteerd, relatief ten opzichte van de hoofdmap van de extensie. Er moet precies één van de files en css worden opgegeven.
oorsprong
StijlOrigin optioneel
De stijlbron voor de injectie. Standaard is dit 'AUTHOR' .
doel
Injectiedoelwit
Details die specificeren in welk doel de CSS moet worden ingevoegd.

ExecutionWorld

Chrome 95+

De JavaScript-omgeving waarin een script kan worden uitgevoerd.

Enum

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

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

InjectionResult

Eigenschappen

documentId
snaar
Chrome 106+
Het document dat bij de injectie hoort.
frameId
nummer
Chrome 90+
Het frame dat bij de injectie hoort.
resultaat
eventuele optionele
Het resultaat van de scriptuitvoering.

InjectionTarget

Eigenschappen

alleFrames
boolean optioneel
Geeft aan of het script in alle frames binnen het tabblad moet worden geïnjecteerd. De standaardwaarde is false. Deze waarde mag niet true zijn als frameIds is opgegeven.
documentIds
string[] optioneel
Chrome 106+
De ID's van specifieke document-ID's waarin de gegevens moeten worden geïnjecteerd. Dit mag niet worden ingesteld als frameIds wel zijn ingesteld.
frameIds
nummer[] optioneel
De ID's van specifieke frames waarin de gegevens moeten worden geïnjecteerd.
tabId
nummer
De ID van het tabblad waarin de injectie moet plaatsvinden.

RegisteredContentScript

Chrome 96+

Eigenschappen

alleFrames
boolean optioneel
Indien ingesteld op 'true', wordt er 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 subframes geïnjecteerd als niet aan de URL-vereisten wordt voldaan. De standaardwaarde is 'false', wat betekent dat alleen het bovenste frame wordt gecontroleerd.
css
string[] optioneel
De lijst met CSS-bestanden die in de bijbehorende pagina's moeten worden geïnjecteerd. Deze worden geïnjecteerd in de volgorde waarin ze in deze lijst voorkomen, voordat er DOM-elementen voor de pagina worden opgebouwd of weergegeven.
Matches uitsluiten
string[] optioneel
Sluit pagina's uit waar dit contentscript anders zou worden ingevoegd. Zie 'Overeenkomstpatronen' voor meer informatie over de syntaxis van deze tekenreeksen.
id
snaar
De ID van het contentscript, zoals opgegeven in de API-aanroep. Mag niet beginnen met een underscore ('_'), aangezien deze gereserveerd is als voorvoegsel voor gegenereerde script-ID's.
js
string[] optioneel
De lijst met JavaScript-bestanden die in de bijbehorende pagina's moeten worden geïnjecteerd. Deze worden geïnjecteerd in de volgorde waarin ze in deze lijst voorkomen.
matchOriginAsFallback
boolean optioneel
Chrome 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 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 bij data: URL's), dan is de gebruikte oorsprong ofwel het frame dat het huidige frame heeft aangemaakt, ofwel het frame dat de navigatie naar dit frame heeft geïnitieerd. Merk op dat dit niet per se het bovenliggende frame hoeft te zijn.
wedstrijden
string[] optioneel
Hiermee wordt gespecificeerd in welke pagina's dit contentscript wordt geïnjecteerd. Zie 'Match Patterns' voor meer informatie over de syntaxis van deze tekenreeksen. Moet worden opgegeven voor registerContentScripts .
persistentAcrossSessions
boolean optioneel
Hiermee wordt bepaald of dit inhoudsscript behouden blijft in toekomstige sessies. De standaardwaarde is 'true'.
runAt
RunAt optioneel
Hiermee wordt bepaald wanneer JavaScript-bestanden in de webpagina worden geïnjecteerd. De voorkeurswaarde en standaardwaarde is document_idle .
wereld
ExecutionWorld optioneel
Chrome 102+
De JavaScript-omgeving waarin het script moet worden uitgevoerd. Standaard is dit ISOLATED .

ScriptInjection

Eigenschappen

argumenten
elk[] optioneel
Chrome 92+
De argumenten die aan de opgegeven functie moeten worden doorgegeven. Dit is alleen geldig als de parameter func is gespecificeerd. Deze argumenten moeten JSON-serialiseerbaar zijn.
bestanden
string[] optioneel
Het pad naar de JS- of CSS-bestanden die geïnjecteerd moeten worden, relatief ten opzichte van de hoofdmap van de extensie. Er moet precies één van de volgende opties worden opgegeven: files of func .
Onmiddellijk injecteren
boolean optioneel
Chrome 102+
Of de injectie zo snel mogelijk in het doelgebied moet worden uitgevoerd. Houd er rekening mee dat dit geen garantie is dat de injectie plaatsvindt voordat de pagina wordt geladen, aangezien de pagina mogelijk al geladen is tegen de tijd dat het script het doelgebied bereikt.
doel
Injectiedoelwit
Details die specificeren in welk doel het script moet worden geïnjecteerd.
wereld
ExecutionWorld optioneel
Chrome 95+
De JavaScript-omgeving waarin het script moet worden uitgevoerd. Standaard is dit ISOLATED .
func
void optioneel
Chrome 92+
Een JavaScript-functie om te injecteren. Deze functie wordt geserialiseerd en vervolgens gedeserialiseerd voor injectie. Dit betekent dat alle gebonden parameters en de uitvoeringscontext verloren gaan. Precies één van de files of func moet worden opgegeven.
De functie func ziet er als volgt uit:
```
() => {...}
```

StyleOrigin

De oorsprong van een stijlverandering. Zie ' Oorsprong van stijlen' 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 wanneer document_idle is, of direct als de pagina al geladen is. Als de eigenschap injectImmediately is ingesteld, wordt het script zonder wachten geïnjecteerd, zelfs als de pagina nog niet volledig geladen is. Als het script een promise oplevert, wacht de browser tot de promise is afgehandeld en retourneert vervolgens de resulterende waarde.

Parameters

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

Retourneert

Promise< InjectionResult []>
Chrome 90+
Retourneert een Promise die wordt opgelost zodra de injectie is voltooid. De resulterende array bevat het resultaat van de uitvoering voor elk frame waarin de injectie is geslaagd.

getRegisteredContentScripts()

Chrome 96+

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

Retourneert

Promise< RegisteredContentScript []>

insertCSS()

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

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

Parameters

injectie
CSSInjectie
De details van de in te voegen stijlen.

Retourneert

Promise<void>
Chrome 90+
Retourneert een Promise die wordt opgelost zodra de invoeging is voltooid.

registerContentScripts()

Chrome 96+

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

Registreert een of meer inhoudsscripts voor deze extensie.

Parameters

scripts
RegisteredContentScript []
Bevat een lijst met scripts die geregistreerd moeten worden. Als er fouten optreden tijdens het parsen van de scripts/het valideren van de bestanden, of als de opgegeven ID's al bestaan, worden er geen scripts geregistreerd.

Retourneert

Promise<void>
Retourneert een Promise die wordt opgelost zodra de scripts volledig zijn geregistreerd, of wordt afgewezen als er een fout is opgetreden.

removeCSS()

Chrome 90+

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

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

Parameters

injectie
CSSInjectie
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 heeft geen effect.

Retourneert

Promise<void>
Retourneert een Promise die wordt opgelost zodra de verwijdering is voltooid.

unregisterContentScripts()

Chrome 96+

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

Hiermee worden de inhoudsscripts voor deze extensie afgemeld.

Parameters

filter
ContentScriptFilter optioneel
Indien gespecificeerd, worden alleen dynamische content-scripts die aan het filter voldoen, afgemeld. Anders worden alle dynamische content-scripts van de extensie afgemeld.

Retourneert

Promise<void>
Retourneert een Promise die wordt opgelost zodra de scripts zijn afgemeld of wordt afgewezen als er een fout is opgetreden.

updateContentScripts()

Chrome 96+

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

Werkt een of meer inhoudsscripts voor deze extensie bij.

Parameters

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

Retourneert

Promise<void>
Retourneert een Promise die wordt opgelost zodra de scripts zijn bijgewerkt, of wordt afgewezen als er een fout is opgetreden.

chrome.scripting Stay organized with collections Save and categorize content based on your preferences.

Beschrijving

Toestemmingen

Beschikbaarheid

Manifest

Concepten en gebruik

Injectiedoelen

Geïnjecteerde code

Bestanden

Runtimefuncties

Runtime-strings

Verwerk de resultaten

Beloftes

Voorbeelden

Deactiveer alle scripts voor dynamische inhoud.

Soorten

ContentScriptFilter

Eigenschappen

CSSInjection

Eigenschappen

ExecutionWorld

Enum

InjectionResult

Eigenschappen

InjectionTarget

Eigenschappen

RegisteredContentScript

Eigenschappen

ScriptInjection

Eigenschappen

StyleOrigin

Enum

Methoden

executeScript()

Parameters

Retourneert

getRegisteredContentScripts()

Parameters

Retourneert

insertCSS()

Parameters

Retourneert

registerContentScripts()

Parameters

Retourneert

removeCSS()

Parameters

Retourneert

unregisterContentScripts()

Parameters

Retourneert

updateContentScripts()

Parameters

Retourneert

chrome.scripting