Manifest: script di contenuti

La chiave "content_scripts" specifica un file JavaScript o CSS caricato in modo statico da utilizzare ogni volta che viene aperta una pagina che corrisponde a un determinato pattern URL. Le estensioni possono anche inserire script di contenuti in modo programmatico. Per informazioni dettagliate, consulta la sezione 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",
   }
 ],
 ...
}

Files

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

"css" - Array

Facoltativo. Un array di percorsi dei file CSS, inseriti nell'ordine di questo array, prima che avvenga la creazione di un DOM o il rendering della pagina.

"js" - Array,

Facoltativo. Un array di percorsi di file JavaScript, inseriti nell'ordine in cui appaiono 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 tagliate automaticamente.

Corrispondenza URL

È necessaria solo la proprietà "matches". Dopodiché puoi usare i criteri "exclude_matches", "include_globs" e "exclude_globs" per personalizzare gli URL in cui inserire il codice. Il tasto "matches" attiva un avviso.

"matches" - Array

Obbligatorio. Specifica i pattern URL in cui inserire gli script di contenuti. Per la sintassi, consulta la sezione Pattern di corrispondenza.

"exclude_matches" - Array

Facoltativo. Esclude i pattern URL in cui inserire gli script di contenuti. Per la sintassi, consulta la sezione Pattern di corrispondenza.

"include_globs" - Array

Facoltativo. Applicata dopo le corrispondenze per includere solo gli URL che corrispondono anche a questo glob. Destinato a emulare la parola chiave Greasemonkey @include.

"exclude_globs" - Array

Facoltativo. Applicata dopo le corrispondenze per escludere gli URL che corrispondono a questo glob. Destinato a emulare la parola chiave Greasemonkey @exclude.

Gli URL del globo 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 qualsiasi carattere singolo.

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 corrispondenza di globi ed URL

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}

https://www.example.com/foo/bar
https://the.example.com/foo/

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"]
    }
  ],
  ...
}

https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html

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"]
    }
  ],
  ...
}

https://history.example.com
https://.example.com/music

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"]
    }
  ],
  ...
}

https://www.example.com/arts/index.html
https://.example.com/jobs/index.html

https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

Strutture

La chiave "all_frames" consente di specificare se lo script dei contenuti deve essere inserito in tutti i frame corrispondenti ai requisiti per gli URL specificati. Se impostato su false, verrà inserito solo nel frame più alto. Può essere utilizzato insieme a "match_about_blank" per inserire un frame about:blank.

Per inserire i dati in altri frame come data:, blob: e filesystem:, imposta "match_origin_as_fallback" su true. Per maggiori dettagli, vedi Inserire frame correlati

Valore booleano "all_frames"

Facoltativo. Il valore predefinito è false, il che significa che viene abbinato solo il frame principale. Se impostato su true, verrà inserito in tutti i frame, anche se non è quello più in alto nella scheda. Ogni frame viene controllato in modo indipendente per verificare i requisiti dell'URL e non verrà inserito nei frame secondari se i requisiti dell'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 dove 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 nei frame creati da un'origine corrispondente, ma il cui URL o origine potrebbe non corrispondere direttamente al pattern. Includono frame con schemi diversi, ad esempio about:, data:, blob: e filesystem:.

Ambiente di esecuzione ed esecuzione

Per impostazione predefinita, gli script di contenuti vengono inseriti al termine del caricamento del documento e di tutte le risorse e risiedono in un ambiente di esecuzione privato e isolato che 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 DOM e le risorse sono stati caricati. Questa è l'impostazione predefinita.

"world" - ISOLATED | MAIN

Facoltativo. Il mondo JavaScript in cui eseguire uno script. Il valore predefinito è "ISOLATED", che è l'ambiente di esecuzione univoco dello 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ù, vedi Lavorare in mondi isolati.

Esempio

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