chrome.userScripts

Descrizione

Utilizza l'API userScripts per eseguire script utente nel contesto Script utente.

Autorizzazioni

userScripts

Per utilizzare l'API chrome.userScripts, aggiungi l'autorizzazione "userScripts" a manifest.json e "host_permissions" per i siti su cui vuoi eseguire gli script.

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

Disponibilità

Chrome 120+ MV3+

Concetti e utilizzo

Uno script utente è un frammento di codice inserito in una pagina web per modificarne l'aspetto o il comportamento. Gli script vengono creati dagli utenti o scaricati da un repository di script o da un'estensione di script utente.

Modalità sviluppatore per gli utenti dell'estensione

In qualità di sviluppatore di estensioni, hai già attivato la modalità Sviluppatore nella tua installazione di Chrome. Per le estensioni di script utente, gli utenti dovranno anche attivare la modalità sviluppatore. Di seguito sono riportate le istruzioni che puoi copiare e incollare nella tua documentazione.

  1. Vai alla pagina Estensioni inserendo chrome://extensions in una nuova scheda. (per impostazione predefinita, gli URL chrome:// non sono collegabili).

  2. Attiva la modalità sviluppatore facendo clic sul pulsante di attivazione/disattivazione accanto a Modalità sviluppatore.

    La pagina Estensioni

    Pagina Estensioni (chrome://extensions)

Puoi determinare se la modalità sviluppatore è attiva controllando se chrome.userScripts genera un errore. Ad esempio:

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

Lavorare in mondi isolati

Sia gli script utente che quelli dei contenuti possono essere eseguiti in un mondo isolato o nel mondo principale. Un mondo isolato è un ambiente di esecuzione non accessibile a una pagina host o ad altre estensioni. In questo modo, uno script utente può modificare il proprio ambiente JavaScript senza influire sulla pagina host o sugli script utente e dei contenuti di altre estensioni. Al contrario, gli script utente (e gli script di contenuti) non sono visibili alla pagina host o agli script utente e di contenuti di altre estensioni. Gli script in esecuzione nel mondo principale sono accessibili alle pagine host e ad altre estensioni e sono visibili alle pagine host e ad altre estensioni. Per selezionare il mondo, passa "USER_SCRIPT" o "MAIN" quando chiami userScripts.register().

Per configurare un criterio di sicurezza dei contenuti per il mondo USER_SCRIPT, chiama userScripts.configureWorld():

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

Messaggistica

Come gli script di contenuti e i documenti offscreen, gli script utente comunicano con altre parti di un'estensione utilizzando i messaggi (ovvero possono chiamare runtime.sendMessage() e runtime.connect() come qualsiasi altra parte di un'estensione). Tuttavia, vengono ricevuti utilizzando gestori eventi dedicati (ovvero non utilizzano onMessage o onConnect). Questi gestori sono chiamati runtime.onUserScriptMessage e runtime.onUserScriptConnect. I gestori dedicati semplificano l'identificazione dei messaggi provenienti dagli script utente, che sono un contesto meno attendibile.

Prima di inviare un messaggio, devi chiamare configureWorld() con l'argomento messaging impostato su true. Tieni presente che è possibile passare contemporaneamente entrambi gli argomenti csp e messaging.

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

Aggiornamenti delle estensioni

Gli script utente vengono cancellati quando un'estensione viene aggiornata. Puoi aggiungerli di nuovo eseguendo il codice nel gestore eventi runtime.onInstalled nel worker del servizio dell'estensione. Rispondere solo al "update" motivo passato al callback dell'evento.

Esempio

Questo esempio proviene dall'esempio di script utente nel nostro repository di esempi.

Registra uno script

L'esempio seguente mostra una chiamata di base a register(). Il primo argomento è un array di oggetti che definiscono gli script da registrare. Esistono più opzioni di quelle mostrate qui.

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

Tipi

ExecutionWorld

L'ambiente JavaScript in cui deve essere eseguito uno script utente.

Enum

"MAIN"
Specifica l'ambiente di esecuzione del DOM, ovvero l'ambiente di esecuzione condiviso con il codice JavaScript della pagina host.

"USER_SCRIPT"
Specifica l'ambiente di esecuzione specifico per gli script utente ed esente dal CSP della pagina.

RegisteredUserScript

Proprietà

  • allFrames

    booleano facoltativo

    Se il valore è true, l'elemento verrà inserito in tutti i frame, anche se non è il frame più in alto della scheda. Per ogni frame vengono controllati in modo indipendente i requisiti relativi agli URL. Se questi requisiti non sono soddisfatti, il frame non verrà inserito nei frame secondari. Il valore predefinito è false, il che significa che viene abbinato solo il frame superiore.

  • excludeGlobs

    stringa[] facoltativo

    Specifica i pattern generici per le pagine in cui NON verrà inserito questo script utente.

  • excludeMatches

    stringa[] facoltativo

    Esclude le pagine in cui altrimenti verrebbe inserito questo script utente. Per ulteriori dettagli sulla sintassi di queste stringhe, consulta Pattern di corrispondenza.

  • id

    stringa

    L'ID dello script utente specificato nella chiamata API. Questa proprietà non deve iniziare con "_" perché è riservata come prefisso per gli ID script generati.

  • includeGlobs

    stringa[] facoltativo

    Specifica i pattern di caratteri jolly per le pagine in cui verrà inserito questo script utente.

  • js

    ScriptSource[] facoltativo

    L'elenco di oggetti ScriptSource che definiscono le origini degli script da inserire nelle pagine corrispondenti. Questa proprietà deve essere specificata per ${ref:register} e, se specificata, deve essere un array non vuoto.

  • corrisponde a

    stringa[] facoltativo

    Specifica le pagine in cui verrà inserito questo script utente. Per ulteriori dettagli sulla sintassi di queste stringhe, consulta Pattern di corrispondenza. Questa proprietà deve essere specificata per ${ref:register}.

  • runAt

    RunAt facoltativo

    Specifica quando i file JavaScript vengono inseriti nella pagina web. Il valore preferito e predefinito è document_idle.

  • mondo

    ExecutionWorld facoltativo

    L'ambiente di esecuzione JavaScript in cui eseguire lo script. Il valore predefinito è `USER_SCRIPT`.

  • worldId

    stringa facoltativa

    In attesa

    Se specificato, specifica un ID mondo dello script utente specifico in cui eseguire il comando. Valido solo se world è omesso o è USER_SCRIPT. Se omesso, lo script verrà eseguito nel mondo dello script utente predefinito. I valori con trattini bassi iniziali (_) sono riservati.

ScriptSource

Proprietà

  • codice

    stringa facoltativa

    Una stringa contenente il codice JavaScript da iniettare. È necessario specificare esattamente un valore per file o code.

  • file

    stringa facoltativa

    Il percorso del file JavaScript da iniettare rispetto alla directory principale dell'estensione. È necessario specificare esattamente un valore per file o code.

UserScriptFilter

Proprietà

  • ids

    stringa[] facoltativo

    getScripts restituisce solo gli script con gli ID specificati in questo elenco.

WorldProperties

Proprietà

  • csp

    stringa facoltativa

    Specifica il csp mondiale. Il valore predefinito è il csp `ISOLATED` mondiale.

  • messaggistica

    booleano facoltativo

    Specifica se le API di messaggistica sono esposte. Il valore predefinito è false.

  • worldId

    stringa facoltativa

    In attesa

    Specifica l'ID del mondo dello script utente specifico da aggiornare. Se non specificato, vengono aggiornate le proprietà del mondo dello script utente predefinito. I valori con trattini bassi iniziali (_) sono riservati.

Metodi

configureWorld()

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

Configura l'ambiente di esecuzione di `USER_SCRIPT`.

Parametri

  • proprietà

    WorldProperties

    Contiene la configurazione del mondo dello script utente.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getScripts()

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

Restituisce tutti gli script utente registrati dinamicamente per questa estensione.

Parametri

Resi

  • Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getWorldConfigurations()

Promessa In attesa
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Recupera tutte le configurazioni dei mondi registrate.

Parametri

Resi

  • Promise<WorldProperties[]>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

register()

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

Registra uno o più script utente per questa estensione.

Parametri

  • Contiene un elenco di script utente da registrare.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

resetWorldConfiguration()

Promessa In attesa
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Reimposta la configurazione per un mondo di script utente. Tutti gli script iniettati nel mondo con l'ID specificato utilizzeranno la configurazione predefinita del mondo.

Parametri

  • worldId

    stringa facoltativa

    L'ID del mondo dello script utente da reimpostare. Se omesso, reimposta la configurazione del mondo predefinito.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

unregister()

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

Annullamento della registrazione di tutti gli script utente registrati dinamicamente per questa estensione.

Parametri

  • filtro

    UserScriptFilter facoltativo

    Se specificato, questo metodo registra solo gli script utente corrispondenti.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

update()

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

Aggiorna uno o più script utente per questa estensione.

Parametri

  • Contiene un elenco di script utente da aggiornare. Una proprietà viene aggiornata per lo script esistente solo se è specificata in questo oggetto. Se si verificano errori durante l'analisi dello script/la convalida del file o se gli ID specificati non corrispondono a uno script completamente registrato, nessun script viene aggiornato.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.