Manifest: script di contenuti

La chiave "content_scripts" specifica un file JavaScript o CSS caricato staticamente da utilizzare ogni volta che viene aperta una pagina corrispondente a un determinato pattern URL. Le estensioni possono anche inserire script di contenuti in modo programmatico. Per maggiori dettagli, consulta Inserimento di script.

Manifest

Queste sono le chiavi supportate per "content_scripts". Sono obbligatorie solo la chiave "matches" e "js" o "css".

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.example.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"],
     "exclude_matches": ["*://*/*foo*"],
     "include_globs": ["*example.com/???s/*"],
     "exclude_globs": ["*bar*"],     
     "all_frames": false,
     "match_origin_as_fallback": false,
     "match_about_blank": false,
     "run_at": "document_idle",
     "world": "ISOLATED",
   }
 ],
 ...
}

File

Ogni file deve contenere un percorso relativo a una risorsa nella directory root dell'estensione. Le barre iniziali (/) vengono rimosse automaticamente. La chiave "run_at" specifica quando verrà inserito ogni file.

"css" - Array
Facoltativo. Un array di percorsi di file CSS, inseriti nell'ordine di questo array e prima di qualsiasi costruzione del DOM o rendering della pagina.
"js" - Array,
Facoltativo. Un array di percorsi di file JavaScript, inseriti nell'ordine in cui vengono visualizzati in questo array, dopo l'inserimento dei file CSS. Ogni stringa nell'array deve essere un percorso relativo a una risorsa nella directory root dell'estensione. Le barre iniziali ("/") vengono rimosse automaticamente.

URL di corrispondenza

È obbligatoria solo la proprietà "matches". Poi puoi utilizzare "exclude_matches", "include_globs" e "exclude_globs" per personalizzare gli URL in cui inserire il codice. La chiave "matches" attiverà un avviso.

"matches" - Array
Obbligatorio. Specifica i pattern URL in cui inserire gli script dei contenuti. Per la sintassi, consulta Pattern di corrispondenza.
"exclude_matches" - Array
Facoltativo. Esclude i pattern URL in cui inserire gli script dei contenuti. Per la sintassi, consulta Pattern di corrispondenza.
"include_globs" - Array
Facoltativo. Applicato dopo le corrispondenze per includere solo gli URL che corrispondono anche a questo glob. Inteso per emulare la parola chiave Greasemonkey @include.
"exclude_globs" - Array
Facoltativo. Applicato dopo le corrispondenze per escludere gli URL che corrispondono a questo glob. Destinato a emulare la parola chiave Greasemonkey @exclude.

Gli URL glob sono quelli che contengono "caratteri jolly" * e punti interrogativi. Il carattere jolly * corrisponde a qualsiasi stringa di qualsiasi lunghezza, inclusa una stringa vuota, mentre il punto interrogativo ? corrisponde a ogni singolo carattere.

Lo script dei contenuti viene inserito in una pagina se:

  • Il suo URL corrisponde a qualsiasi pattern "matches" e "include_globs".
  • Inoltre, l'URL non corrisponde ai pattern "exclude_matches" o "exclude_globs".

Esempi di glob e corrispondenza degli URL

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Corrisponde a
https://www.example.com/foo/bar
https://the.example.com/foo/
Non corrisponde a
https://my.example.com/foo/bar
https://example.com/foo/*
https://www.example.com/foo

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["*example.com/???s/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Corrisponde a
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
Non corrisponde a
https://www.example.com/sports/index.html
https://www.example.com/music/index.html

"exclude_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Corrisponde a
https://history.example.com
https://.example.com/music
Non corrisponde a
https://science.example.com
https://www.example.com/science

Esempio di personalizzazione avanzata

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Corrisponde a
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
Non corrisponde a
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

Fotogrammi

La chiave "all_frames" specifica se lo script dei contenuti deve essere inserito in tutti i frame che corrispondono ai requisiti per gli URL specificati. Se impostato su false, l'inserimento avverrà solo nel frame più in alto. Può essere utilizzato insieme a "match_about_blank" per l'inserimento in un frame about:blank.

Per l'inserimento in altri frame come data:, blob: e filesystem:, imposta "match_origin_as_fallback" su true. Per maggiori dettagli, consulta Inserisci nei frame correlati.

"all_frames" Booleano
Facoltativo. Il valore predefinito è false, il che significa che viene trovata una corrispondenza solo per il frame superiore. Se impostato su true, l'inserimento avverrà in tutti i frame, anche se il frame non è quello più in alto nella scheda. Ogni frame viene controllato in modo indipendente per verificare i requisiti per gli URL e non verrà inserito nei frame secondari se i requisiti per gli URL non sono soddisfatti.
"match_about_blank" - Booleano
Facoltativo. Il valore predefinito è false. Indica se lo script deve essere inserito in un frame about:blank in cui l'URL principale corrisponde a uno dei pattern dichiarati in "matches".
"match_origin_as_fallback" - Booleano
Facoltativo. Il valore predefinito è false. Indica se lo script deve essere inserito in frame creati da un'origine corrispondente, ma il cui URL o la cui origine potrebbe non corrispondere direttamente al pattern. Sono inclusi i frame con schemi diversi, ad esempio about:, data:, blob: e filesystem:.

Runtime e ambiente di esecuzione

Per impostazione predefinita, gli script dei contenuti vengono inseriti al termine del caricamento del documento e di tutte le risorse e risiedono in un ambiente di esecuzione privato e isolato non accessibile alla pagina o ad altre estensioni. Puoi modificare queste impostazioni predefinite nelle seguenti chiavi:

"run_at" - document_start | document_end | document_idle
Facoltativo. Specifica quando lo script deve essere inserito nella pagina. Corrisponde agli stati di caricamento di Document.readyState:
  • "document_start": il DOM è ancora in fase di caricamento.
  • "document_end": le risorse della pagina sono ancora in fase di caricamento
  • "document_idle": il caricamento del DOM e delle risorse è stato completato. Questa è l'impostazione predefinita.
"world" - ISOLATED | MAIN
Facoltativo. Il mondo JavaScript in cui eseguire uno script. Il valore predefinito è "ISOLATED", ovvero l'ambiente di esecuzione univoco per lo script dei contenuti. Se scegli il mondo "MAIN", lo script condividerà l'ambiente di esecuzione con il codice JavaScript della pagina host. Per saperne di più, consulta Lavora in mondi isolati.

Esempio

Consulta il tutorial Esegui su ogni pagina per creare un'estensione che inserisce uno script di contenuti nel manifest.