browser.userScripts

Descrizione

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

Autorizzazioni

userScripts

Per utilizzare l'API User Scripts, browser.userScripts, aggiungi l'autorizzazione "userScripts" al file 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+ browser.* da Chrome 148 MV3+

Concetti e utilizzo

Uno script utente è uno snippet di codice inserito in una pagina web per modificarne l'aspetto o il comportamento. A differenza di altre funzionalità delle estensioni, come gli script dei contenuti e l'API browser.scripting, l'API User Scripts consente di eseguire codice arbitrario. Questa API è obbligatoria per le estensioni che eseguono script forniti dall'utente che non possono essere inviati come parte del pacchetto dell'estensione.

Attiva l'utilizzo dell'API userScripts

Dopo che l'estensione ha ricevuto l'autorizzazione per utilizzare l'API userScripts, gli utenti devono attivare un'opzione specifica per consentire all'estensione di utilizzare l'API. Il pulsante di attivazione/disattivazione specifico richiesto e il comportamento dell'API quando è disattivata variano in base alla versione di Chrome.

Utilizza il seguente controllo per determinare quale pulsante di attivazione/disattivazione l'utente deve attivare, ad esempio durante l'onboarding di un nuovo utente:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

Le sezioni seguenti descrivono i diversi pulsanti di attivazione/disattivazione e come attivarli.

Versioni di Chrome precedenti alla 138 (pulsante di attivazione/disattivazione della modalità sviluppatore)

In qualità di sviluppatore di estensioni, hai già attivato la modalità sviluppatore nella tua installazione di Chrome. Anche i tuoi utenti devono attivare la modalità sviluppatore.

Puoi copiare e incollare le seguenti istruzioni nella documentazione dell'estensione per i tuoi utenti

  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'interruttore accanto a Modalità sviluppatore.

    La pagina delle estensioni di Chrome con il pulsante di attivazione/disattivazione della modalità sviluppatore evidenziato

    Pagina Estensioni (chrome://extensions)

Chrome 138 e versioni successive (pulsante di attivazione/disattivazione Consenti script utente)

Il pulsante di attivazione/disattivazione Consenti script utente si trova nella pagina dei dettagli di ogni estensione (ad esempio chrome://extensions/?id=YOUR_EXTENSION_ID).

Puoi copiare e incollare le seguenti istruzioni nella documentazione dell'estensione per i tuoi utenti:

  1. Vai alla pagina Estensioni inserendo chrome://extensions in una nuova scheda. (Per impostazione predefinita, gli URL chrome:// non sono collegabili.)
  2. Fai clic sul pulsante "Dettagli" nella scheda dell'estensione per visualizzare informazioni dettagliate sull'estensione.
  3. Fai clic sul pulsante di attivazione/disattivazione accanto a Consenti script utente.
Il pulsante di attivazione/disattivazione Consenti script utente nella pagina dei dettagli dell'estensione
Attiva/disattiva Consenti script utente (chrome://extensions/?id=abc…)

Verifica la disponibilità dell'API

Ti consigliamo di eseguire il seguente controllo per determinare se l'API userScripts è abilitata, poiché funziona in tutte le versioni di Chrome. Questo controllo tenta di chiamare un metodo browser.userScripts() che dovrebbe sempre riuscire quando l'API è disponibile. Se questa chiamata genera un errore, l'API non è disponibile:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Lavora in mondi isolati

Sia gli script utente che gli script dei contenuti possono essere eseguiti in un mondo isolato o nel mondo principale. Un isolated world è 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 dei contenuti) non sono visibili alla pagina host o agli script utente e dei 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 una Content Security Policy per il mondo USER_SCRIPT, chiama userScripts.configureWorld():

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

Messaggistica

Come gli script dei contenuti e i documenti fuori schermo, gli script utente comunicano con altre parti di un'estensione utilizzando la messaggistica (ovvero possono chiamare runtime.sendMessage() e runtime.connect() come farebbe qualsiasi altra parte di un'estensione). Tuttavia, 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 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 gli argomenti csp e messaging possono essere passati contemporaneamente.

browser.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 dall'esempio userScript 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 di quelle mostrate qui.

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

InjectionResult

Chrome 135 e versioni successive browser.* da Chrome 148

Proprietà

  • documentId

    stringa

    Il documento associato all'inserimento.

  • errore

    stringa facoltativa

    L'errore, se presente. error e result si escludono a vicenda.

  • frameId

    numero

    Il frame associato all'inserimento.

  • risultato

    any optional

    Il risultato dell'esecuzione dello script.

InjectionTarget

Chrome 135 e versioni successive browser.* da Chrome 148

Proprietà

  • allFrames

    boolean facoltativo

    Indica se lo script deve essere inserito in tutti i frame della scheda. Il valore predefinito è false. Questo non deve essere vero se è specificato frameIds.

  • documentIds

    string[] facoltativo

    Gli ID dei documentId specifici in cui inserire i dati. Questo valore non deve essere impostato se è impostato frameIds.

  • frameIds

    number[] facoltativo

    Gli ID dei frame specifici in cui eseguire l'inserimento.

  • tabId

    numero

    L'ID della scheda in cui inserire il codice.

RegisteredUserScript

Proprietà

  • allFrames

    boolean facoltativo

    Se il valore è true, l'inserimento verrà eseguito in tutti i frame, anche se il frame non è quello più in alto nella scheda. Ogni frame viene controllato in modo indipendente per i requisiti per gli URL; non verrà inserito nei frame secondari se i requisiti per gli URL non sono soddisfatti. Il valore predefinito è false, il che significa che viene trovata una corrispondenza solo per il frame superiore.

  • excludeGlobs

    string[] facoltativo

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

  • excludeMatches

    string[] 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

    string[] facoltativo

    Specifica i pattern con 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

    string[] 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

    Chrome 133+ browser.* da Chrome 148

    Specifica l'ID del mondo dello script utente in cui eseguire l'operazione. Se omesso, lo script verrà eseguito nel mondo degli script utente predefinito. Valido solo se world viene omesso o è USER_SCRIPT. I valori con trattini bassi iniziali (_) sono riservati.

ScriptSource

Proprietà

  • codice

    stringa facoltativa

    Una stringa contenente il codice JavaScript da inserire. È necessario specificare esattamente uno dei due valori: file o code.

  • file

    stringa facoltativa

    Il percorso del file JavaScript da inserire relativo alla directory root dell'estensione. È necessario specificare esattamente uno dei due valori: file o code.

UserScriptFilter

Proprietà

  • ids

    string[] facoltativo

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

UserScriptInjection

Chrome 135 e versioni successive browser.* da Chrome 148

Proprietà

  • injectImmediately

    boolean facoltativo

    Indica se l'inserimento deve essere attivato nel target il prima possibile. Tieni presente che questo non garantisce che l'inserimento avvenga prima del caricamento pagina, poiché la pagina potrebbe essere già stata caricata quando lo script raggiunge la destinazione.

  • L'elenco di oggetti ScriptSource che definiscono le origini degli script da inserire nella destinazione.

  • destinazione

    InjectionTarget

    Dettagli che specificano la destinazione in cui inserire lo script.

  • mondo

    ExecutionWorld facoltativo

    Il "mondo" JavaScript in cui eseguire lo script. Il valore predefinito è USER_SCRIPT.

  • worldId

    stringa facoltativa

    Specifica l'ID del mondo dello script utente in cui eseguire l'operazione. Se omesso, lo script verrà eseguito nel mondo degli script utente predefinito. Valido solo se world viene omesso o è USER_SCRIPT. I valori con trattini bassi iniziali (_) sono riservati.

WorldProperties

Proprietà

  • csp

    stringa facoltativa

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

  • messaggistica

    boolean facoltativo

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

  • worldId

    stringa facoltativa

    Chrome 133+ browser.* da Chrome 148

    Specifica l'ID del mondo di script utente specifico da aggiornare. Se non viene fornito, aggiorna le proprietà del mondo degli script utente predefinito. I valori con trattini bassi iniziali (_) sono riservati.

Metodi

configureWorld()

browser.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

Configura l'ambiente di esecuzione `USER_SCRIPT`.

Parametri

  • proprietà

    WorldProperties

    Contiene la configurazione del mondo dello script utente.

Resi

  • Promise<void>

    Promessa che si risolve una volta configurato il mondo.

execute()

Chrome 135 e versioni successive browser.* da Chrome 148 
browser.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

Inserisce uno script in un contesto di destinazione. Per impostazione predefinita, lo script verrà eseguito in document_idle o immediatamente se la pagina è già stata caricata. Se la proprietà injectImmediately è impostata, lo script verrà inserito senza attendere, anche se la pagina non ha terminato il caricamento. Se lo script restituisce una promise, il browser attenderà che la promise venga risolta e restituirà il valore risultante.

Parametri

Resi

getScripts()

browser.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

Restituisce tutti gli script utente registrati dinamicamente per questa estensione.

Parametri

  • filtro

    UserScriptFilter facoltativo

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

Resi

  • Promise che si risolve con gli script registrati. La promessa verrà rifiutata se si verifica un errore.

getWorldConfigurations()

Chrome 133+ browser.* da Chrome 148 
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Recupera tutte le configurazioni del mondo registrate.

Resi

  • Promise<WorldProperties[]>

    Promise che si risolve con le configurazioni del mondo registrate.

register()

browser.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

Registra uno o più script utente per questa estensione.

Parametri

Resi

  • Promise<void>

    Promessa che si risolve una volta che gli script sono stati completamente registrati. La promessa verrà rifiutata se si verifica un errore.

resetWorldConfiguration()

Chrome 133+ browser.* da Chrome 148 
browser.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

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

Parametri

  • worldId

    stringa facoltativa

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

Resi

  • Promise<void>

    Promessa che si risolve quando la configurazione viene reimpostata.

unregister()

browser.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

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

Resi

  • Promise<void>

    Promise che si risolve una volta annullata completamente la registrazione degli script. La promessa verrà rifiutata se si verifica un errore.

update()

browser.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

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 oppure se gli ID specificati non corrispondono a uno script completamente registrato, non viene aggiornato alcuno script.

Resi

  • Promise<void>

    Promise che si risolve una volta che gli script sono stati completamente aggiornati. La promessa verrà rifiutata se si verifica un errore.