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 maggiori dettagli, consulta la sezione Inserimento di script.

Manifest

Queste sono le chiavi supportate per "content_scripts". Sono necessari 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 di una risorsa nella directory principale dell'estensione. Le barre iniziali (/) vengono tagliate automaticamente. La chiave "run_at" specifica quando verrà inserito ciascun file.

"css" - Array

Facoltativo. Un array di percorsi di file CSS, inseriti nell'ordine di questo array e prima che si verifichi qualsiasi costruzione DOM o 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 di una risorsa nella directory radice dell'estensione. Le barre iniziali ("/") vengono tagliate automaticamente.

Crea corrispondenze con gli URL

È richiesta 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" attiva un avviso.

"matches" - Array

Obbligatorio. Specifica in quali pattern URL inserire gli script di contenuti. Consulta Pattern di corrispondenza per la sintassi.

"exclude_matches" - Array

Facoltativo. Esclude i pattern URL in cui inserire gli script di contenuti. Consulta Pattern di corrispondenza per la sintassi.

"include_globs" - Array

Facoltativo. Applicato dopo le corrispondenze per includere solo gli URL che corrispondono a questo glob. Ha lo scopo di emulare la parola chiave Greasemonkey @include.

"exclude_globs" - Array

Facoltativo. Applicato dopo le corrispondenze per escludere gli URL che corrispondono a questo glob. Ha lo scopo di emulare la parola chiave Greasemonkey @excluded.

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 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 glob e 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" specifica se lo script dei contenuti deve essere inserito in tutti i frame corrispondenti ai requisiti dell'URL specificati. Se impostato su false, verrà inserito solo nel frame più in alto. Può essere utilizzato insieme a "match_about_blank" per inserirlo in un frame about:blank.

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

"all_frames" Booleano

Facoltativo. Il valore predefinito è false, il che significa che viene abbinata solo la parte superiore del frame. 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 e non verrà inserito nei frame secondari se i requisiti degli URL non vengono 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 potrebbero non corrispondere direttamente al pattern. Sono inclusi frame con schemi diversi, come about:, data:, blob: e filesystem:.

Tempo di esecuzione e ambiente di 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 isolato privato 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 deve essere eseguito uno script. Il valore predefinito è "ISOLATED", che è 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 Lavorare in mondi isolati.

di Gemini Advanced.

Esempio

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