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à
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.
- Vai alla pagina Estensioni inserendo
chrome://extensions
in una nuova scheda. (Per impostazione predefinita, gli URLchrome://
non sono collegabili). Attiva la modalità sviluppatore facendo clic sull'opzione di attivazione/disattivazione accanto a Modalità sviluppatore.
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.
-
js
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
ocode
. -
file
stringa facoltativo
Il percorso del file JavaScript da inserire in relazione alla directory root dell'estensione. È necessario specificare esattamente uno tra
file
ocode
.
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()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Configura l'ambiente di esecuzione `USER_SCRIPT`
.
Parametri
-
proprietà
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()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Restituisce tutti gli script degli utenti registrati dinamicamente per questa estensione.
Parametri
-
filter
UserScriptFilter facoltativo
Se specificato, questo metodo restituisce solo gli script utente corrispondenti.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(scripts: RegisteredUserScript[]) => void
-
script
-
Ritorni
-
Promise<RegisteredUserScript[]>
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()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Registra uno o più script utente per questa estensione.
Parametri
-
script
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()
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()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Aggiorna uno o più script utente per questa estensione.
Parametri
-
script
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.