chrome.userScripts

Beschrijving

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

Machtigingen

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.

   

   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 offscreen-documenten 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 van 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.

• Globs uitsluiten

  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.

• Identiteitskaart

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

• rennenBij

  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.

• terugbellen

  functie optioneel

  De callback parameter ziet er als volgt uit:

  () => void

Retouren

• 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

• filter

  UserScriptFilter optioneel

  Indien opgegeven, retourneert deze methode alleen de gebruikersscripts die ermee overeenkomen.

• terugbellen

  functie optioneel

  De callback parameter ziet er als volgt uit:

  (scripts: RegisteredUserScript[]) => void

  • scripts

    Geregistreerd gebruikersscript []

Retouren

• 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

• scripts

  Geregistreerd gebruikersscript []

  Bevat een lijst met gebruikersscripts die moeten worden geregistreerd.

• terugbellen

  functie optioneel

  De callback parameter ziet er als volgt uit:

  () => void

Retouren

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

• terugbellen

  functie optioneel

  De callback parameter ziet er als volgt uit:

  () => void

Retouren

• 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

• scripts

  Geregistreerd gebruikersscript []

  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.

• terugbellen

  functie optioneel

  De callback parameter ziet er als volgt uit:

  () => void

Retouren

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