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.

   

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

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.

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

• filtro

  UserScriptFilter facoltativo

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

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (scripts: RegisteredUserScript[]) => void

  • script

    RegisteredUserScript[]

Resi

• Promise<RegisteredUserScript[]>

  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

• script

  RegisteredUserScript[]

  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.

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

• script

  RegisteredUserScript[]

  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.