chrome.userScripts

Beschrijving

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

Rechten

userScripts

Als u de chrome.userScripts API wilt gebruiken, voegt u de machtiging "userScripts" toe aan uw manifest.json en "host_permissions" voor sites waarop u scripts wilt uitvoeren.

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

Beschikbaarheid

Chroom 120+ MV3+

Concepten en gebruik

Een gebruikersscript is een stukje code dat in een webpagina wordt geïnjecteerd om het uiterlijk of gedrag ervan te wijzigen. Scripts worden door gebruikers gemaakt of gedownload vanuit een scriptrepository of een gebruikersscriptextensie.

Ontwikkelaarsmodus voor gebruikers van extensies

Als extensie-ontwikkelaar heeft u de ontwikkelaarsmodus al ingeschakeld tijdens uw installatie van Chrome. Voor gebruikersscriptextensies moeten uw gebruikers ook de ontwikkelaarsmodus inschakelen. Hier vindt u instructies die u kunt kopiëren en in uw eigen documentatie kunt plakken.

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

  2. Schakel de ontwikkelaarsmodus in door op de tuimelschakelaar naast de ontwikkelaarsmodus te klikken.

    Extensies pagina

    Pagina Extensies (chrome://extensions)

U kunt bepalen of de ontwikkelaarsmodus is ingeschakeld door te controleren of chrome.userScripts een fout genereert. Bijvoorbeeld:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Werk in geïsoleerde werelden

Zowel gebruikers- als inhoudsscripts kunnen in een geïsoleerde wereld of in de hoofdwereld worden uitgevoerd. Een geïsoleerde wereld is een uitvoeringsomgeving die niet toegankelijk is voor een hostpagina of andere extensies. Hierdoor kan een gebruikersscript zijn JavaScript-omgeving wijzigen zonder dat dit invloed heeft op de hostpagina of de gebruikers- en inhoudsscripts van andere extensies. Omgekeerd zijn gebruikersscripts (en inhoudsscripts) niet zichtbaar voor de hostpagina of de gebruikers- en inhoudsscripts van andere extensies. Scripts die in de hoofdwereld worden uitgevoerd, zijn toegankelijk voor hostpagina's en andere extensies en zijn zichtbaar voor hostpagina's en andere extensies. Om de wereld te selecteren, geeft u "USER_SCRIPT" of "MAIN" door bij het aanroepen userScripts.register() .

Om een ​​inhoudsbeveiligingsbeleid voor de USER_SCRIPT wereld te configureren, roept u userScripts.configureWorld() aan:

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

Berichten

Net als inhoudsscripts en documenten buiten het scherm communiceren gebruikersscripts met andere delen van een extensie via berichtenuitwisseling (wat betekent dat ze runtime.sendMessage() en runtime.connect() kunnen aanroepen zoals elk ander deel van een extensie dat zou doen). Ze worden echter ontvangen met behulp van speciale gebeurtenishandlers (wat betekent dat ze geen gebruik maken onMessage of onConnect ). Deze handlers worden runtime.onUserScriptMessage en runtime.onUserScriptConnect genoemd. Toegewijde handlers maken het gemakkelijker om berichten uit gebruikersscripts te identificeren, die een minder vertrouwde context vormen.

Voordat u een bericht verzendt, moet u configureWorld() aanroepen met het messaging ingesteld op true . Houd er rekening mee dat zowel de csp als messaging argumenten tegelijkertijd kunnen worden doorgegeven.

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

Extensie-updates

Gebruikersscripts worden gewist wanneer een extensie wordt bijgewerkt. U kunt ze weer toevoegen door code uit te voeren in de gebeurtenishandler runtime.onInstalled in de uitbreidingsservicewerker. Reageer alleen op de reden "update" die is doorgegeven aan de terugroep van de gebeurtenis.

Voorbeeld

Dit voorbeeld komt uit het userScript-voorbeeld in onze voorbeeldenrepository.

Registreer een script

In het volgende voorbeeld ziet u een eenvoudige aanroep van register() . Het eerste argument is een array van objecten die de te registreren scripts definiëren. Er zijn meer opties dan hier weergegeven.

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

Soorten

ExecutionWorld

De JavaScript-wereld waarin een gebruikersscript kan worden uitgevoerd.

Enum

"VOORNAAMST"
Specificeert de uitvoeringsomgeving van de DOM, de uitvoeringsomgeving die wordt gedeeld met het JavaScript van de hostpagina.

"USER_SCRIPT"
Specificeert de uitvoeringsomgeving die specifiek is voor gebruikersscripts en is vrijgesteld van de CSP van de pagina.

RegisteredUserScript

Eigenschappen

  • alleFrames

    Booleaans optioneel

    Als dit waar is, wordt dit 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.

  • sluitGlobs uit

    tekenreeks[] optioneel

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

  • wedstrijden uitsluiten

    tekenreeks[] optioneel

    Exclusief pagina's waarin dit gebruikersscript anders zou worden geïnjecteerd. Zie Matchpatronen voor meer details over de syntaxis van deze tekenreeksen.

  • ID kaart

    snaar

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

  • omvattenGlobs

    tekenreeks[] optioneel

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

  • js

    Scriptbron []

    De lijst met ScriptSource-objecten die bronnen definiëren van scripts die in overeenkomende pagina's moeten worden geïnjecteerd.

  • wedstrijden

    tekenreeks[] optioneel

    Specificeert op welke pagina's dit gebruikersscript wordt geïnjecteerd. Zie Matchpatronen voor meer details over de syntaxis van deze tekenreeksen. Deze eigenschap moet worden opgegeven voor ${ref:register}.

  • draaien op

    RunAt optioneel

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

  • wereld

    ExecutionWorld optioneel

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

ScriptSource

Eigenschappen

  • code

    tekenreeks optioneel

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

  • bestand

    tekenreeks optioneel

    Het pad van het JavaScript-bestand dat moet worden geïnjecteerd, relatief ten opzichte van de hoofdmap van de extensie. Er moet precies één file of code worden opgegeven.

UserScriptFilter

Eigenschappen

  • ID's

    tekenreeks[] optioneel

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

WorldProperties

Eigenschappen

  • csp

    tekenreeks optioneel

    Specificeert de wereld-csp. De standaardwaarde is de `ISOLATED` wereld-csp.

  • berichtenuitwisseling

    Booleaans optioneel

    Geeft aan of berichten-API's beschikbaar zijn. De standaardwaarde is false .

Methoden

configureWorld()

Belofte
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Configureert de uitvoeringsomgeving `USER_SCRIPT` .

Parameters

  • eigenschappen

    Wereldeigenschappen

    Bevat de wereldconfiguratie van het gebruikersscript.

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

getScripts()

Belofte
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Retourneert alle dynamisch geregistreerde gebruikersscripts voor deze extensie.

Parameters

Geeft terug

  • Belofte< RegisteredUserScript []>

    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.

register()

Belofte
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Registreert een of meer gebruikersscripts voor deze extensie.

Parameters

  • Bevat een lijst met gebruikersscripts die moeten worden 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.

unregister()

Belofte
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Verwijdert de registratie van alle dynamisch geregistreerde gebruikersscripts voor deze extensie.

Parameters

  • filter

    UserScriptFilter optioneel

    Indien opgegeven, verwijdert deze methode de registratie van alleen de gebruikersscripts die ermee overeenkomen.

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

update()

Belofte
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Werkt een of meer gebruikersscripts voor deze extensie bij.

Parameters

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