content_scripts

タイプ

 Array
必須か いいえ
例
json
"content_scripts": [
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["borderify.js"]
  }
]

与えられたパターンに URL がマッチしているページにコンテンツスクリプトをロードすることをブラウザーに教えます。

このキーは配列です。それぞれのアイテムは以下の条件を満たすオブジェクトです:

  • 必ず matches という名前のキーを含まなければならず、これはスクリプトが読み込まれる URL パターンを指定します
  • js と css というキーを入れてもよく、それはマッチしたページに読み込まれるスクリプトを列挙します
  • その他のプロパティを入れてもよく、それはコンテンツスクリプトがいつどのように読み込まれるか管理します

入れることのできるキーの詳細は下記の表にあります。

名前 型 説明
all_frames Boolean

true: js と css で指定されたすべてのスクリプトを、指定した URL要求にマッチするすべてのフレームに(タブの最上位フレームでなくても)挿入します。これは親のフレームだけが URL要求にマッチしている子フレームには挿入しません。URL 要求は各フレームごとにチェックされます。

false: タブの最上位フレームで URL要求にマッチしたフレームだけに挿入します。

デフォルトは false
css Array

manifest.json からの相対パスの配列で、マッチしたページに挿入される CSS ファイルを参照する。

ファイルは指定した順で、DOM が読み込まれる前に挿入される。
exclude_globs Array ワイルドカードを含む文字配列。下記の URL パターンにマッチする を見てください。
exclude_matches Array マッチパターンの配列。下記の URL パターンにマッチするを見てください。
include_globs Array ワイルドカードを含む文字配列。下記の URL パターンにマッチする を見てください。
js Array

manifest.json からの相対パスの配列で、マッチしたページに挿入される JavaScript ファイルを参照する。

ファイルは指定した順でに挿入される。つまり、例えば、ここで jQuery をインクルードしてから他のコンテンツスクリプトを読み込むには、このようにします:

json
"js": ["jquery.js", "my-content-script.js"]

こうすると "my-content-script.js" から jQuery を使えます。

ファイルは run_at で指定した時に挿入されます。

match_about_blank Boolean

コンテンツスクリプトを "about:blank" もしくは"about:srcdoc"のURLを持つページに挿入します。 if the URL of the page that opened or created this page matches the patterns specified in the rest of the content_scripts key.

This is especially useful to run scripts in empty iframes , whose URL is "about:blank". To do this you should also set the all_frames key.

例えば、 以下のような content_scripts キーがあるとします:

json
"content_scripts": [
    {
      "js": ["my-script.js"],
      "matches": ["https://example.org/"],
      "match_about_blank": true,
      "all_frames": true
    }
  ]

ユーザーがhttps://example.org/をロードすると、ページに空のiframeが埋め込まれ、 "my-script.js" がそのiframe内に読み込まれます。

match_about_blank is supported in Firefox from version 52. Note that in Firefox, content scripts won't be injected into empty iframes at "document_start" even if you specify that value in run_at.

matches Array

マッチパターンの配列。下記の URLパターンにマッチする を見てください。

これは唯一の必須なキーです。
run_at String

This option determines when the scripts specified in js are injected. You can supply one of three strings here, each of which identifies a state in the process of loading a document. The states directly correspond to Document.readyState:

  • "document_start": corresponds to loading. The DOM is still loading.
  • "document_end": corresponds to interactive. The DOM has finished loading, but resources such as scripts and images may still be loading.
  • "document_idle": corresponds to complete. The document and all its resources have finished loading.

The default value is "document_idle".

In all cases, files in js are injected after files in css.

URL パターンにマッチする

"content_scripts" キーは URL マッチングを元にしてコンテンツスクリプトをドキュメントに添付します: ドキュメントの URL がキーに指定されたものとマッチしたら、スクリプトは添付されます。"content_scripts" 内には指定に使える 4 つのキーワードがあります:

これらのプロパティにマッチするには、URL は配列内で少なくとも 1 つの項目にマッチしなければなりません。例えばこのようなプロパティが与えられたら:

json
"matches": ["*://*.example.org/*", "*://*.example.com/*"]

"http://example.org/" と "http://example.com/" の両方がマッチします。

matches は唯一必須のキーなため、その他の 3 つのキーはそれ以降のマッチ URL の制限に使われます。全体のキーにマッチするために、URL は下記のようでなければなりません:

  1. matches プロパティにマッチしている
  2. かつ、include_globs があれば、それにマッチする
  3. かつ、exclude_matches があれば、それにマッチしない
  4. かつ、exclude_globs があれば、それにマッチしない

globs

glob は単にワイルドカードを含むことのある文字列です。ワイルドカードには 2 種類あって、glob 内に組み合わせることができます:

  • "*" は 0 個以上のキャラクターにマッチします
  • "?" はちょうど 1 個のキャラクターにマッチします

例えば: "*na?i" は "illuminati" と "annunaki" にマッチし、"sagnarelli" にはマッチしません。

例

json
"content_scripts": [
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["borderify.js"]
  }
]

これは "borderify.js" という 1 つのコンテンツスクリプトを、HTTP か HTTPS のいずれかで配布される、"mozilla.org" かそのサブドメインのページに挿入します。

json
"content_scripts": [
    {
      "exclude_matches": ["*://developer.mozilla.org/*"],
      "matches": ["*://*.mozilla.org/*"],
      "js": ["jquery.js", "borderify.js"]
    }
  ]

これは 2 つのコンテンツスクリプトを、HTTP か HTTPS のいずれかで配布される、 "mozilla.org" かそのサブドメイン(ただし "developer.mozilla.org" を除く)のページに挿入します。

コンテンツスクリプトは同じ DOM を見て、配列の順番どおりに挿入されます。よって "borderify.js" からは "jquery.js" によって追加されたグローバル変数が見えます。

ブラウザーの互換性

BCD tables only load in the browser