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 est ouverte et qui correspond à un certain format d'URL. Les extensions permettent également d'injecter des scripts de contenu par programmation. Pour en savoir plus, consultez la section Injecter des scripts.

Fichier manifeste

Voici les clés compatibles avec "content_scripts". Seules la clé "matches" et "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 d'accès relatif à une ressource située dans le répertoire racine de l'extension. Les barres obliques au début (/) sont automatiquement coupées. La clé "run_at" spécifie le moment où chaque fichier sera injecté.

"css" : tableau
Facultatif. Tableau de chemins de fichiers CSS, injectés dans l'ordre de ce tableau, avant toute construction DOM ou affichage de la page.
"js" : tableau,
Facultatif. Tableau de chemins de 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 correspondre à un chemin d'accès relatif vers une ressource située dans le répertoire racine de l'extension. Les barres obliques au début ("/") sont automatiquement coupées.

Faire correspondre les 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 touche "matches" déclenche un avertissement.

"matches" : tableau
Obligatoire. Spécifie les formats d'URL dans lesquels injecter les scripts de contenu. Consultez la section Formats de correspondance pour en savoir plus sur la syntaxe.
"exclude_matches" : tableau
Facultatif. Exclut les formats d'URL dans lesquels injecter les scripts de contenu. Consultez la section Formats de correspondance pour en savoir plus sur la syntaxe.
"include_globs" : tableau
Facultatif. Appliqué après les correspondances pour n'inclure que les URL qui correspondent également à ce globe. Destiné à émuler le mot clé @include Greasemonkey
"exclude_globs" : tableau
Facultatif. Appliqué après les correspondances pour exclure les URL qui correspondent à ce schéma glob. Destiné à émuler le mot clé @excluded Greasemonkey.

Les URL Glob sont celles qui contiennent des caractères génériques. * et de 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 unique.

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

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

Globs et exemples de correspondance 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 frames correspondant aux exigences de l'URL spécifiées. Si elle est définie sur false, elle n'est injectée que dans le cadre 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

Valeur booléenne "all_frames"
Facultatif. La valeur par défaut est false, ce qui signifie que seule le cadre supérieur correspond. Si cette règle est définie sur "true", elle est injectée dans tous les cadres, même s'ils ne sont pas en haut de l'onglet. Les exigences concernant les URL sont vérifiées indépendamment pour chaque frame. Si les exigences de l'URL ne sont pas remplies, les frames enfants ne sont pas injectés.
"match_about_blank" (booléen)
Facultatif. La valeur par défaut est false. Indique si le script doit injecter 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 injecter dans des frames qui ont été créés par une origine correspondante, mais dont l'URL ou l'origine ne correspondent peut-être pas directement au format. Ceux-ci incluent des cadres avec des schémas différents, tels que about:, data:, blob: et filesystem:.

Temps d'exécution et environnement d'exécution

Par défaut, les scripts de contenu sont injectés une fois le chargement du document et de toutes les ressources terminé, et sont exécutés dans un environnement d'exécution privé et isolé, auquel la page ou d'autres extensions n'ont pas accès. Vous pouvez modifier ces valeurs par défaut dans les touches suivantes:

"run_at" – document_start | document_end | document_idle
Facultatif. Indique à quel moment le script doit être injecté dans la page. Elle correspond aux états de chargement de Document.readyState: <ph type="x-smartling-placeholder">
    </ph>
  • "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 chargement du DOM et des ressources est terminé. Il s'agit de la valeur par défaut.
"world" – ISOLATED | MAIN
Facultatif. L'univers JavaScript dans lequel un script doit s'exécuter. La valeur par défaut est "ISOLATED", qui correspond à l'environnement d'exécution unique au script de contenu. Si vous choisissez l'environnement "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.