マニフェスト - コンテンツ スクリプト

"content_scripts" キーは、特定の URL パターンに一致するページが開かれるたびに使用される、静的に読み込まれる JavaScript ファイルまたは CSS ファイルを指定します。拡張機能は、プログラムでコンテンツ スクリプトを挿入することもできます。詳しくは、スクリプトの挿入をご覧ください。

マニフェスト

"content_scripts" でサポートされているキーは次のとおりです。"matches" キーと、"js" または "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",
   }
 ],
 ...
}

ファイル

各ファイルには、拡張機能のルート ディレクトリにあるリソースへの相対パスを含める必要があります。先頭のスラッシュ（/）は自動的に削除されます。"run_at" キーは、各ファイルが挿入されるタイミングを指定します。

"css" - 配列
省略可。CSS ファイルパスの配列。この配列の順序で、DOM の構築やページのレンダリングが行われる前に挿入されます。
"js" - 配列
省略可。JavaScript ファイルパスの配列。CSS ファイルが挿入された後、この配列に表示される順序で挿入されます。配列内の各文字列は、拡張機能のルート ディレクトリ内のリソースへの相対パスにする必要があります。先頭のスラッシュ（/）は自動的に削除されます。

URL の一致

"matches" プロパティのみが必須です。その後、"exclude_matches"、"include_globs"、"exclude_globs" を使用して、コードを挿入する URL をカスタマイズできます。"matches" キーは警告をトリガーします。

"matches" - 配列
必須。コンテンツ スクリプトを挿入する URL パターンを指定します。構文については、一致パターンをご覧ください。
"exclude_matches" - 配列
省略可。コンテンツ スクリプトを挿入する URL パターンを除外します。構文については、一致パターンをご覧ください。
"include_globs" - 配列
省略可。一致後に適用され、この glob にも一致する URL のみが含まれます。@include Greasemonkey キーワードをエミュレートすることを目的としています。
"exclude_globs" - 配列
省略可。一致した後に適用され、この glob に一致する URL を除外します。Greasemonkey の @exclude キーワードをエミュレートすることを目的としています。

Glob URL とは、「ワイルドカード」* と疑問符を含む URL です。ワイルドカード * は、空の文字列を含む任意の長さの任意の文字列に一致します。一方、疑問符 ? は、任意の 1 文字に一致します。

コンテンツ スクリプトは、次の条件を満たす場合にページに挿入されます。

  • URL が "matches" パターンと "include_globs" パターンに一致する。
  • URL が "exclude_matches" または "exclude_globs" のパターンと一致しない。

glob と 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

高度なカスタマイズの例

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

フレーム

"all_frames" キーは、指定された URL の要件に一致するすべてのフレームにコンテンツ スクリプトを挿入するかどうかを指定します。false に設定すると、最上位のフレームにのみ挿入されます。"match_about_blank" と組み合わせて使用すると、about:blank フレームに挿入できます。

data:、blob:、filesystem: などの他のフレームに挿入するには、"match_origin_as_fallback" を true に設定します。詳しくは、関連するフレームに挿入するをご覧ください。

"all_frames" ブール値
省略可。デフォルトは false で、最上位フレームのみが一致します。true に設定すると、フレームがタブの最上位フレームでない場合でも、すべてのフレームに挿入されます。各フレームは URL の要件を個別にチェックされ、URL の要件を満たしていない場合は子フレームに挿入されません。
"match_about_blank" - ブール値
省略可。デフォルトは false です。親 URL が "matches" で宣言されたパターンのいずれかに一致する about:blank フレームにスクリプトを挿入するかどうか。
"match_origin_as_fallback" - ブール値
省略可。デフォルトは false です。一致するオリジンによって作成されたフレームにスクリプトを挿入するかどうか。ただし、URL またはオリジンがパターンに直接一致しない場合があります。これには、about:、data:、blob:、filesystem: などの異なるスキームを持つフレームが含まれます。

ランタイムと実行環境

デフォルトでは、コンテンツ スクリプトはドキュメントとすべてのリソースの読み込みが完了したときに挿入され、ページや他の拡張機能からアクセスできないプライベートな分離された実行環境に存在します。これらのデフォルトは、次のキーで変更できます。

"run_at" - document_start | document_end | document_idle
省略可。スクリプトをページに挿入するタイミングを指定します。これは、Document.readyState の読み込み状態に対応します。
  • "document_start": DOM はまだ読み込み中です。
  • "document_end": ページの読み込みが完了していない
  • "document_idle": DOM とリソースの読み込みが完了しました。これがデフォルトです。
"world" - ISOLATED | MAIN
省略可。スクリプトを実行する JavaScript ワールド。デフォルトは "ISOLATED" で、これはコンテンツ スクリプトに固有の実行環境です。"MAIN" ワールドを選択すると、スクリプトはホストページの JavaScript と実行環境を共有します。詳しくは、分離された環境で作業するをご覧ください。

例

マニフェストにコンテンツ スクリプトを挿入する拡張機能をビルドするには、すべてのページで実行するチュートリアルをご覧ください。