Questa pagina è stata tradotta dall'API Cloud Translation.

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

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

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.

Avviso: l'utilizzo del mondo "MAIN" comporta dei rischi. La pagina host può accedere allo script inserito e interferire con quest'ultimo. Per saperne di più, consulta Lavorare in mondi isolati.

Esempio

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