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 al "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 è 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 di estensioni

In qualità di sviluppatore di estensioni, hai già attivato la modalità sviluppatore nella tua installazione di Chrome. Per le estensioni 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, chrome:// URL non è collegabile.

  2. Attiva la modalità sviluppatore facendo clic sull'opzione di attivazione/disattivazione accanto alla Modalità sviluppatore.

    La pagina Estensioni

    Pagina Estensioni (chrome://extensions)
    .

Per determinare se la modalità sviluppatore è attiva, controlla 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;
  }
}

Lavora in mondi isolati

Sia gli script relativi agli utenti che ai 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. Questo consente a uno script utente di modificare il proprio ambiente JavaScript senza influire sulla pagina host o su altre estensioni script di utenti e contenuti. Al contrario, gli script utente (e i 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 e ad altre estensioni host e sono visibili alle pagine e ad altre estensioni. Per selezionare il mondo, passa "USER_SCRIPT" o "MAIN" quando chiami userScripts.register().

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

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

Messaggistica

Analogamente a quanto accade per gli script di contenuti e i documenti fuori schermo, gli script utente comunicano con altre parti di un'estensione tramite la messaggistica, nel senso che possono chiamare runtime.sendMessage() e runtime.connect() come farebbe qualsiasi altra parte di un'estensione. ma vengono ricevuti utilizzando gestori di 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 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 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 aggiungerli di nuovo eseguendo il codice nel gestore di eventi runtime.onInstalled nel service worker dell'estensione. Rispondi solo al motivo "update" passato al callback dell'evento.

Esempio

Questo esempio è tratto da userScript sample 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. Sono disponibili più opzioni rispetto a quelle mostrate qui.

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

Tipi

ExecutionWorld

Il mondo 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 impostato su 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 degli URL. non verrà inserito nei frame secondari se non vengono soddisfatti i requisiti degli URL. Il valore predefinito è false, vale a dire che viene abbinata solo la parte superiore del frame.

  • excludeGlobs

    string[] facoltativo

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

  • excludeMatches

    string[] facoltativo

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

  • id

    stringa

    L'ID dello script utente specificato nella chiamata API. Questa proprietà non deve iniziare con "_" in quanto è riservato 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 utente.

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

  • corrisponde a

    string[] facoltativo

    Specifica le pagine in cui verrà inserito questo script utente. Consulta Pattern di corrispondenza per ulteriori dettagli sulla sintassi di queste stringhe. 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 di 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 in modo esatto uno tra file o code.

  • file

    stringa facoltativo

    Il percorso del file JavaScript da inserire relativo alla directory radice dell'estensione. È necessario specificare in modo esatto uno tra file o code.

UserScriptFilter

Proprietà

  • ID

    string[] facoltativo

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

WorldProperties

Proprietà

  • CSS

    stringa facoltativo

    Specifica il World CSP. Il valore predefinito è `ISOLATED` World csp.

  • messaggistica

    booleano facoltativo

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

Metodi

configureWorld()

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

Configura l'ambiente di esecuzione `USER_SCRIPT`.

Parametri

  • proprietà

    WorldProperties

    Contiene la configurazione globale degli script utente.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getScripts()

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

Restituisce tutti gli script utente registrati dinamicamente per questa estensione.

Parametri

Resi

  • Promise&lt;RegisteredUserScript[]&gt;

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

register()

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

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

unregister()

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

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

Parametri

  • filtro

    UserScriptFilter facoltativo

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

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

update()

Promesso .
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 degli script o la convalida del file o se gli ID specificati non corrispondono a uno script completamente registrato, non viene aggiornato alcuno script.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.