browser.userScripts

Beschrijving

Gebruik de userScripts API om gebruikersscripts uit te voeren in de context van gebruikersscripts.

Rechten

userScripts

Als je de User Scripts API wilt gebruiken, browser.userScripts, voeg je het recht "userScripts" toe aan je manifest.json en "host_permissions" voor sites waarop je scripts wilt uitvoeren.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Beschikbaarheid

Chrome 120+ browser.* sinds Chrome 148 MV3+

Concepten en gebruik

Een gebruikersscript is een codefragment dat in een webpagina wordt geïnjecteerd om de weergave of het gedrag ervan aan te passen. In tegenstelling tot andere extensiefuncties, zoals Content Scripts en de browser.scripting API, kun je met de User Scripts API willekeurige code uitvoeren. Deze API is vereist voor extensies die scripts uitvoeren die door de gebruiker worden geleverd en die niet kunnen worden geleverd als onderdeel van je extensiepakket.

Gebruik van de userScripts API aanzetten

Nadat je extensie het recht heeft gekregen om de userScripts API te gebruiken, moeten gebruikers een specifieke schakelaar aanzetten om je extensie toe te staan de API te gebruiken. De specifieke schakelaar die vereist is en het gedrag van de API als deze is uitgezet, verschillen per Chrome-versie.

Gebruik de volgende controle om te bepalen welke schakelaar de gebruiker moet aanzetten, bijvoorbeeld tijdens de introductie van nieuwe gebruikers:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

In de volgende gedeelten worden de verschillende schakelaars beschreven en hoe je ze aanzet.

Chrome-versies ouder dan 138 (schakelaar voor ontwikkelaarsmodus)

Als extensieontwikkelaar heb je de ontwikkelaarsmodus al aangezet in je installatie van Chrome. Je gebruikers moeten ook de ontwikkelaarsmodus aanzetten.

Je kunt de volgende instructies kopiëren en plakken in de documentatie van je extensie voor je gebruikers

1. Ga naar de pagina Extensies door chrome://extensions in te voeren in een nieuw tabblad. (chrome://-URL's zijn standaard niet koppelbaar.)

2. Zet de ontwikkelaarsmodus aan door op de schakelaar naast Ontwikkelaarsmodus te klikken.

   

   Pagina Extensies (chrome://extensions)

Opmerking: Als de ontwikkelaarsmodus niet aanstaat, krijg je een foutmelding als je naar browser.userScripts gaat. Je kunt deze fout gebruiken om de beschikbaarheid van de API te bepalen. Ga naar De beschikbaarheid van de API controleren.

Chrome-versie 138 en hoger (schakelaar Gebruikersscripts toestaan)

De schakelaar Gebruikersscripts toestaan staat op de detailpagina van elke extensie (bijvoorbeeld chrome://extensions/?id=YOUR_EXTENSION_ID).

Je kunt de volgende instructies kopiëren en plakken in de documentatie van je extensie voor je gebruikers:

1. Ga naar de pagina Extensies door chrome://extensions in te voeren in een nieuw tabblad. (chrome://-URL's zijn standaard niet koppelbaar.)
2. Klik op de knop Details op de extensiekaart om gedetailleerde informatie over de extensie te bekijken.
3. Klik op de schakelaar naast Gebruikersscripts toestaan.

Schakelaar Gebruikersscripts toestaan (chrome://extensions/?id=abc...)

Opmerking: Als de schakelaar Gebruikersscripts toestaan niet aanstaat, is browser.userScripts niet gedefinieerd. Deze ongedefinieerde status (vergelijkbaar met hoe andere API's zich gedragen) wordt alleen gereset als de context van een extensiescript opnieuw wordt geladen. Als een gebruiker bijvoorbeeld de toegang intrekt terwijl je servicemedewerker actief is, blijft browser.userScripts gedefinieerd. In dit scenario wordt er een foutmelding gegeven als je een van de methoden probeert aan te roepen.

Checken of de API beschikbaar is

We raden de volgende controle aan om te bepalen of de userScripts API aanstaat, omdat deze werkt in alle Chrome-versies. Deze controle probeert een browser.userScripts()-methode aan te roepen die altijd zou moeten slagen als de API beschikbaar is. Als deze aanroep een foutmelding oplevert, is de API niet beschikbaar:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Werken in geïsoleerde werelden

Zowel gebruikers- als contentscripts kunnen worden uitgevoerd in een geïsoleerde wereld of in de hoofdwereld. Een geïsoleerde wereld is een uitvoeringsomgeving die niet toegankelijk is voor een hostpagina of andere extensies. Zo kan een gebruikersscript de JavaScript-omgeving wijzigen zonder dat dit invloed heeft op de hostpagina of de gebruikers- en contentscripts van andere extensies. Omgekeerd zijn gebruikersscripts (en contentscripts) niet zichtbaar voor de hostpagina of de gebruikers- en contentscripts van andere extensies. Scripts die in de hoofdomgeving worden uitgevoerd, zijn toegankelijk voor hostpagina's en andere extensies en zijn zichtbaar voor hostpagina's en andere extensies. Als je de wereld wilt selecteren, geef je "USER_SCRIPT" of "MAIN" door wanneer je userScripts.register() aanroept.

Als je een contentbeveiligingsbeleid wilt instellen voor de wereld USER_SCRIPT, roep je userScripts.configureWorld() aan:

browser.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Berichten

Net als contentscripts en offscreen documenten communiceren gebruikersscripts met andere delen van een extensie via berichten (wat betekent dat ze runtime.sendMessage() en runtime.connect() kunnen aanroepen zoals elk ander deel van een extensie). Ze worden wel ontvangen via speciale gebeurtenishandlers (ze gebruiken dus niet onMessage of onConnect). Deze handlers heten runtime.onUserScriptMessage en runtime.onUserScriptConnect. Met speciale handlers kun je makkelijker berichten van gebruikersscripts identificeren, die een minder vertrouwde context hebben.

Voordat u een bericht stuurt, moet u configureWorld() aanroepen met het argument messaging ingesteld op true. U kunt de argumenten csp en messaging tegelijkertijd doorgeven.

browser.userScripts.configureWorld({
  messaging: true
});

Extensie-updates

Gebruikersscripts worden gewist als een extensie wordt geüpdatet. Je kunt ze weer toevoegen door code uit te voeren in de gebeurtenishandler runtime.onInstalled in de serviceworker van de extensie. Reageer alleen op de reden "update" die is doorgegeven aan de callback van de gebeurtenis.

Voorbeeld

Dit voorbeeld is afkomstig uit het userScript-voorbeeld in onze repository met voorbeelden.

Een script registreren

In het volgende voorbeeld ziet u een basisaanroep van register(). Het eerste argument is een matrix van objecten die de scripts definiëren die moeten worden geregistreerd. Er zijn meer opties dan hier worden getoond.

browser.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Typen

ExecutionWorld

De JavaScript-wereld waarin een gebruikersscript moet worden uitgevoerd.

Enum

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

"USER_SCRIPT"
Hiermee geef je de uitvoeringsomgeving aan die specifiek is voor gebruikersscripts en die is vrijgesteld van het CSP van de pagina.

InjectionResult

Chrome 135+ browser.* sinds Chrome 148

Eigenschappen

• documentId

  tekenreeks

  Het document dat aan de injectie is gekoppeld.

• fout

  tekenreeks optioneel

  De fout, indien van toepassing. error en result sluiten elkaar uit.

• frameId

  getal

  Het frame dat is gekoppeld aan de injectie.

• resultaat

  alleen optioneel

  Het resultaat van de scriptuitvoering.

InjectionTarget

Chrome 135+ browser.* sinds Chrome 148

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

  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.

RegisteredUserScript

Eigenschappen

• allFrames

  booleaans optioneel

  Als de waarde 'true' is, wordt de code 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.

• excludeGlobs

  string[] optioneel

  Specificeert jokertekenpatronen voor pagina's waarin dit gebruikersscript NIET wordt geïnjecteerd.

• excludeMatches

  string[] optioneel

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

• id

  tekenreeks

  De ID van het gebruikersscript dat is opgegeven in de API-aanroep. Deze property mag niet beginnen met een '_' omdat deze is gereserveerd als voorvoegsel voor gegenereerde script-ID's.

• includeGlobs

  string[] optioneel

  Specificeert jokertekenpatronen voor pagina's waarin dit gebruikersscript wordt geïnjecteerd.

• js

  ScriptSource[] optioneel

  De lijst met ScriptSource-objecten die bronnen van scripts definiëren die moeten worden geïnjecteerd in overeenkomende pagina's. Deze property moet worden ingevoerd voor ${ref:register} en moet een niet-lege matrix zijn.

• komt overeen

  string[] optioneel

  Hiermee geef je aan op welke pagina's dit gebruikersscript wordt geïnjecteerd. Ga naar Overeenkomstpatronen voor meer informatie over de syntaxis van deze tekenreeksen. Deze property moet worden ingevoerd voor ${ref:register}.

• runAt

  RunAt optioneel

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

• wereld

  ExecutionWorld optioneel

  De JavaScript-uitvoeringsomgeving waarin het script moet worden uitgevoerd. De standaardwaarde is `USER_SCRIPT`.

• worldId

  tekenreeks optioneel

  Chrome 133+ browser.* sinds Chrome 148

  Hiermee wordt de wereld-ID van het gebruikersscript aangegeven waarin moet worden uitgevoerd. Als je dit weglaat, wordt het script uitgevoerd in de standaardwereld voor gebruikersscripts. Alleen geldig als world wordt weggelaten of USER_SCRIPT is. Waarden met een underscore aan het begin (_) zijn gereserveerd.

ScriptSource

Eigenschappen

• code

  tekenreeks optioneel

  Een tekenreeks met de JavaScript-code die moet worden geïnjecteerd. Er moet precies één file of code worden ingevoerd.

• bestand

  tekenreeks optioneel

  Het pad van het JavaScript-bestand dat moet worden geïnjecteerd ten opzichte van de root-map van de extensie. Er moet precies één file of code worden ingevoerd.

UserScriptFilter

Eigenschappen

• ID's

  string[] optioneel

  getScripts retourneert alleen scripts met de ID's die in deze lijst staan.

UserScriptInjection

Chrome 135+ browser.* sinds Chrome 148

Eigenschappen

• injectImmediately

  booleaans optioneel

  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.

• js

  ScriptSource[]

  De lijst met ScriptSource-objecten die bronnen van scripts definiëren die in het doel moeten worden geïnjecteerd.

• target

  InjectionTarget

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

• wereld

  ExecutionWorld optioneel

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

• worldId

  tekenreeks optioneel

  Hiermee wordt de wereld-ID van het gebruikersscript aangegeven waarin moet worden uitgevoerd. Als je dit weglaat, wordt het script uitgevoerd in de standaardwereld voor gebruikersscripts. Alleen geldig als world wordt weggelaten of USER_SCRIPT is. Waarden met een underscore aan het begin (_) zijn gereserveerd.

WorldProperties

Eigenschappen

• csp

  tekenreeks optioneel

  Hiermee wordt de wereld-csp aangegeven. De standaard is de `ISOLATED` wereld-csp.

• chat

  booleaans optioneel

  Geeft aan of API's voor berichten worden weergegeven. De standaardwaarde is false.

• worldId

  tekenreeks optioneel

  Chrome 133+ browser.* sinds Chrome 148

  Hiermee geef je de ID op van de specifieke gebruikersscriptwereld die je wilt updaten. Als deze niet wordt verstrekt, worden de eigenschappen van de standaard gebruikersscriptwereld geüpdatet. Waarden met een underscore aan het begin (_) zijn gereserveerd.

Methoden

configureWorld()

browser.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

Hiermee stel je de `USER_SCRIPT`-uitvoeringsomgeving in.

Parameters

• property's

  WorldProperties

  Bevat de wereldconfiguratie van het gebruikersscript.

Retourzendingen

• Promise<void>

  Promise die wordt opgelost zodra de wereld is geconfigureerd.

execute()

Chrome 135+ browser.* sinds Chrome 148

browser.userScripts.execute(
  injection: UserScriptInjection,
): 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

  UserScriptInjection

Retourzendingen

• Promise<InjectionResult[]>

getScripts()

browser.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

Retourneert alle dynamisch geregistreerde gebruikersscripts voor deze extensie.

Parameters

• filter

  UserScriptFilter optioneel

  Als deze methode is ingevoerd, retourneert deze alleen de gebruikersscripts die ermee overeenkomen.

Retourzendingen

• Promise<RegisteredUserScript[]>

  Promise die wordt opgelost met de geregistreerde scripts. De belofte wordt afgewezen als er een fout optreedt.

getWorldConfigurations()

Chrome 133+ browser.* sinds Chrome 148

browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Haalt alle geregistreerde wereldconfiguraties op.

Retourzendingen

• Promise<WorldProperties[]>

  Promise die wordt opgelost met de geregistreerde wereldconfiguraties.

register()

browser.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

Registreert een of meer gebruikersscripts voor deze extensie.

Parameters

• scripts

  RegisteredUserScript[]

  Bevat een lijst met gebruikersscripts die moeten worden geregistreerd.

Retourzendingen

• Promise<void>

  Belofte die wordt omgezet zodra de scripts volledig zijn geregistreerd. De belofte wordt afgewezen als er een fout optreedt.

resetWorldConfiguration()

Chrome 133+ browser.* sinds Chrome 148

browser.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

Reset de configuratie voor een gebruikersscriptwereld. Scripts die in de wereld worden geïnjecteerd met de opgegeven ID, gebruiken de standaard wereldconfiguratie.

Parameters

• worldId

  tekenreeks optioneel

  De ID van de gebruikersscriptwereld die je wilt resetten. Als je dit weglaat, wordt de configuratie van de standaardwereld gereset.

Retourzendingen

• Promise<void>

  Promise die wordt opgelost als de configuratie wordt gereset.

unregister()

browser.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

Maakt de registratie ongedaan van alle dynamisch geregistreerde gebruikersscripts voor deze extensie.

Parameters

• filter

  UserScriptFilter optioneel

  Als je dit opgeeft, maakt deze methode alleen de registratie ongedaan van de gebruikersscripts die overeenkomen.

Retourzendingen

• Promise<void>

  Promise die wordt opgelost zodra de registratie van de scripts volledig ongedaan is gemaakt. De belofte wordt afgewezen als er een fout optreedt.

update()

browser.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

Updatet een of meer gebruikersscripts voor deze extensie.

Parameters

• scripts

  RegisteredUserScript[]

  Bevat een lijst met gebruikersscripts 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>

  Promise die wordt opgelost zodra de scripts volledig zijn geüpdatet. De belofte wordt afgewezen als er een fout optreedt.