Fichier manifeste - scripts de contenu

La clé "content_scripts" spécifie un fichier JavaScript ou CSS chargé de manière statique à utiliser chaque fois qu'une page correspondant à un certain format d'URL est ouverte. Les extensions peuvent également injecter des scripts de contenu de manière programmatique. Pour en savoir plus, consultez Injecter des scripts.

Fichier manifeste

Voici les clés compatibles avec "content_scripts". Seules la clé "matches" et l'une des clés "js" ou "css" sont obligatoires.

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

Fichiers

Chaque fichier doit contenir un chemin relatif vers une ressource du répertoire racine de l'extension. Les barres obliques de début (/) sont automatiquement supprimées. La clé "run_at" spécifie quand chaque fichier sera injecté.

"css" - Tableau
Facultatif. Tableau de chemins d'accès aux fichiers CSS, injectés dans l'ordre de ce tableau, et avant toute construction DOM ou tout rendu de page.
"js" : tableau,
Facultatif. Tableau de chemins d'accès aux fichiers JavaScript, injectés dans l'ordre dans lequel ils apparaissent dans ce tableau, après l'injection des fichiers CSS. Chaque chaîne du tableau doit être un chemin relatif à une ressource dans le répertoire racine de l'extension. Les barres obliques de début ('/') sont automatiquement supprimées.

Correspondance des URL

Seule la propriété "matches" est obligatoire. Vous pouvez ensuite utiliser "exclude_matches", "include_globs" et "exclude_globs" pour personnaliser les URL dans lesquelles injecter du code. La clé "matches" déclenchera un avertissement.

"matches" - Tableau
Obligatoire. Spécifie les formats d'URL dans lesquels injecter les scripts de contenu. Pour connaître la syntaxe, consultez Formats de correspondance.
"exclude_matches" - Tableau
Facultatif. Exclut les formats d'URL dans lesquels injecter les scripts de contenu. Pour en savoir plus sur la syntaxe, consultez Formats de correspondance.
"include_globs" – Tableau
Facultatif. Appliqué après les correspondances pour n'inclure que les URL qui correspondent également à ce glob. Destiné à émuler le mot clé Greasemonkey @include.
"exclude_globs" – Tableau
Facultatif. Appliqué après les correspondances pour exclure les URL qui correspondent à ce glob. Destiné à émuler le mot clé Greasemonkey @exclude.

Les URL glob sont celles qui contiennent des caractères génériques * et des points d'interrogation. Le caractère générique * correspond à n'importe quelle chaîne de n'importe quelle longueur, y compris une chaîne vide, tandis que le point d'interrogation ? correspond à n'importe quel caractère.

Le script de contenu est injecté dans une page si :

  • Son URL correspond à tous les formats "matches" et "include_globs".
  • Et l'URL ne correspond pas aux formats "exclude_matches" ou "exclude_globs".

Exemples de globs et de correspondances d'URL

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Correspond à
https://www.example.com/foo/bar
https://the.example.com/foo/
Ne correspond pas
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"]
    }
  ],
  ...
}
Correspond à
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
Ne correspond pas
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"]
    }
  ],
  ...
}
Correspond à
https://history.example.com
https://.example.com/music
Ne correspond pas
https://science.example.com
https://www.example.com/science

Exemple de personnalisation avancée

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Correspond à
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
Ne correspond pas
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

Images

La clé "all_frames" indique si le script de contenu doit être injecté dans tous les cadres correspondant aux exigences relatives aux URL spécifiées. Si la valeur est définie sur false, l'injection ne s'effectue que dans le frame supérieur. Il peut être utilisé avec "match_about_blank" pour injecter dans un frame about:blank.

Pour injecter dans d'autres frames comme data:, blob: et filesystem:, définissez "match_origin_as_fallback" sur true. Pour en savoir plus, consultez Injecter dans les frames associés.

"all_frames" Booléen
Facultatif. La valeur par défaut est false, ce qui signifie que seul le frame supérieur est mis en correspondance. Si la valeur est "true", l'injection s'effectue dans tous les cadres, même s'il ne s'agit pas du cadre supérieur de l'onglet. Chaque frame est vérifié indépendamment pour les exigences relatives aux URL. Il ne sera pas injecté dans les frames enfants si les exigences relatives aux URL ne sont pas respectées.
"match_about_blank" : booléen.
Facultatif. La valeur par défaut est false. Indique si le script doit être injecté dans un frame about:blank où l'URL parente correspond à l'un des formats déclarés dans "matches".
"match_origin_as_fallback" : booléen
Facultatif. La valeur par défaut est false. Indique si le script doit être injecté dans des frames créés par une origine correspondante, mais dont l'URL ou l'origine ne correspondent pas directement au format. Cela inclut les frames avec différents schémas, tels que about:, data:, blob: et filesystem:.

Environnement d'exécution et d'exécution

Par défaut, les scripts de contenu sont injectés une fois que le document et toutes les ressources ont fini de se charger. Ils résident dans un environnement d'exécution isolé privé qui n'est pas accessible à la page ni aux autres extensions. Vous pouvez modifier ces valeurs par défaut dans les clés suivantes :

"run_at" - document_start | document_end | document_idle
Facultatif. Indique quand le script doit être injecté dans la page. Il correspond aux états de chargement de Document.readyState :
  • "document_start" : le DOM est toujours en cours de chargement.
  • "document_end" : les ressources de la page sont toujours en cours de chargement
  • "document_idle" : le DOM et les ressources ont fini de se charger. Il s'agit de la valeur par défaut.
"world" - ISOLATED | MAIN
Facultatif. Environnement JavaScript dans lequel un script doit s'exécuter. La valeur par défaut est "ISOLATED", qui est l'environnement d'exécution unique du script de contenu. Si vous choisissez le monde "MAIN", le script partagera l'environnement d'exécution avec le code JavaScript de la page hôte. Pour en savoir plus, consultez Travailler dans des mondes isolés.

Exemple

Consultez le tutoriel Exécuter sur chaque page pour créer une extension qui injecte un script de contenu dans le fichier manifeste.