chrome.userScripts

Descrizione

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

Autorizzazioni

userScripts

Per usare l'API chrome.userScripts, aggiungi l'autorizzazione "userScripts" al file manifest.json e ai "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 e versioni successive MV3 o versioni successive

Concetti e utilizzo

Uno script utente è una porzione di codice inserita 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 script utente.

Modalità sviluppatore per gli utenti con estensioni

In qualità di sviluppatore di estensioni, hai già attivato la modalità sviluppatore nell'installazione di Chrome. Per le estensioni script degli utenti, gli utenti dovranno attivare anche la modalità sviluppatore. Ecco 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 sull'opzione 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

Gli script utente e di 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. Ciò consente a uno script utente di modificare il proprio ambiente JavaScript senza influire sulla pagina host o sugli script di utenti e contenuti di altre estensioni. Al contrario, gli script utente (e quelli di contenuti) non sono visibili nella pagina host o con gli script degli utenti e dei contenuti di altre estensioni. Gli script in esecuzione nel mondo principale sono accessibili per ospitare pagine e altre estensioni e sono visibili per ospitare pagine e 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'"
});

Messaggi

Come gli script di contenuti e i documenti fuori schermo, gli script utente comunicano con altre parti di un'estensione utilizzando la funzionalità di messaggistica, ovvero possono chiamare runtime.sendMessage() e runtime.connect() come farebbe qualsiasi altra parte di un'estensione. Tuttavia, vengono ricevuti usando gestori di eventi dedicati (ovvero non usano onMessage o onConnect). Questi gestori sono denominati runtime.onUserScriptMessage e runtime.onUserScriptConnect. I gestori dedicati semplificano l'identificazione dei messaggi provenienti dagli script degli utenti, che rappresentano un contesto meno attendibile.

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

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

Aggiornamenti delle estensioni

Gli script utente vengono cancellati quando un'estensione viene aggiornata. Puoi aggiungerle di nuovo eseguendo il codice nel gestore di eventi runtime.onInstalled nel service worker dell'estensione. Rispondi solo al "update" motivo trasmesso al callback dell'evento.

Esempio

Questo esempio è tratto da un esempio userScript presente 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 definisce gli script da registrare. Ci sono più opzioni rispetto a quelle mostrate qui.

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

Tipi

ExecutionWorld

Il mondo JavaScript in cui eseguire uno script dell'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, verrà inserito in tutti i frame, anche se non è il frame più in alto nella scheda. Ogni frame viene controllato in modo indipendente per verificare i requisiti dell'URL; non verrà inserito nei frame secondari se non sono soddisfatti i requisiti dell'URL. Il valore predefinito è false, il che significa che viene abbinato solo il frame principale.

  • excludeGlobs

    string[] facoltativo

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

  • excludeMatches

    string[] facoltativo

    Sono escluse le pagine in cui questo script dell'utente verrebbe altrimenti inserito. 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

    string[] facoltativo

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

  • L'elenco di oggetti ScriptSource che definiscono le origini degli script da inserire nelle pagine corrispondenti.

  • corrisponde a

    string[] facoltativo

    Specifica in quali pagine verrà inserito questo script dell'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.

  • internazionali

    ExecutionWorld facoltativo

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

ScriptSource

Proprietà

  • codice

    stringa facoltativo

    Una stringa contenente il codice JavaScript da inserire. È necessario specificare esattamente uno tra file o code.

  • file

    stringa facoltativo

    Il percorso del file JavaScript da inserire in relazione alla directory root dell'estensione. È necessario specificare esattamente uno tra file o code.

UserScriptFilter

Proprietà

  • ids

    string[] facoltativo

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

WorldProperties

Proprietà

  • CSP

    stringa facoltativo

    Specifica il CSP globale. Il valore predefinito è il CSP mondiale `ISOLATED`.

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

Parametri

  • proprietà

    WorldProperties

    Contiene la configurazione del mondo degli script utente.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

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

getScripts()

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

Restituisce tutti gli script degli utenti registrati dinamicamente per questa estensione.

Parametri

Ritorni

  • Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

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

unregister()

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

Consente di annullare la registrazione di tutti gli script degli utenti registrati dinamicamente per questa estensione.

Parametri

  • filter

    UserScriptFilter facoltativo

    Se specificato, questo metodo annulla solo la registrazione degli script utente corrispondenti.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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 o la convalida del file o se gli ID specificati non corrispondono a uno script completamente registrato, gli script non vengono aggiornati.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

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