コンテンツ スクリプトは、ウェブページのコンテキストで実行されるファイルです。標準のドキュメント オブジェクト モデル(DOM)を使用すると、ブラウザがアクセスしたウェブページの詳細を読み取って変更を加え、親拡張機能に情報を渡すことができます。
コンテンツ スクリプトの機能を理解する
コンテンツ スクリプトは、ウェブからアクセス可能なリソースとして宣言すると、拡張機能ファイルにアクセスできるようになります。次の拡張機能 API に直接アクセスできます。
dom
i18n
storage
runtime.connect()
runtime.getManifest()
runtime.getURL()
runtime.id
runtime.onConnect
runtime.onMessage
runtime.sendMessage()
コンテンツ スクリプトが他の API に直接アクセスすることはできません。ただし、拡張機能の他の部分とメッセージを交換することで、拡張機能の他の部分と間接的にアクセスできます。
隔離された環境で作業する
コンテンツ スクリプトは隔離された環境で動作するため、ページや他の拡張機能のコンテンツ スクリプトと競合することなく、JavaScript 環境に変更を加えることができます。
拡張機能は、次の例のようなコードを使用してウェブページで実行できます。
webPage.html
<html>
<button id="mybutton">click me</button>
<script>
var greeting = "hello, ";
var button = document.getElementById("mybutton");
button.person_name = "Bob";
button.addEventListener(
"click", () => alert(greeting + button.person_name + "."), false);
</script>
</html>
この拡張機能では、スクリプトを挿入するで説明されているいずれかの方法で、次のコンテンツ スクリプトを挿入できます。
content-script.js
var greeting = "hola, ";
var button = document.getElementById("mybutton");
button.person_name = "Roberto";
button.addEventListener(
"click", () => alert(greeting + button.person_name + "."), false);
この変更により、ボタンがクリックされると、両方のアラートが順番に表示されます。
スクリプトの挿入
コンテンツ スクリプトは、静的に宣言することも、動的に宣言することも、プログラムによって挿入することもできます。
静的宣言を使用したインジェクション
よく知られたページセットで自動的に実行する必要があるスクリプトには、manifest.json で静的コンテンツ スクリプトの宣言を使用します。
静的に宣言されたスクリプトは、マニフェストの "content_scripts"
キーで登録されます。JavaScript ファイル、CSS ファイル、またはその両方を含めることができます。自動実行コンテンツ スクリプトはすべて、一致パターンを指定する必要があります。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"css": ["my-styles.css"],
"js": ["content-script.js"]
}
],
...
}
Name | 型 | 説明 |
---|---|---|
matches |
文字列の配列 | 必須。このコンテンツのスクリプトを挿入するページを指定します。これらの文字列の構文の詳細については一致パターンを、URL を除外する方法については一致パターンと glob をご覧ください。 |
css |
文字列の配列 | 省略可。一致するページに挿入される CSS ファイルのリストです。これらは、ページに対して DOM が構築または表示される前に、この配列に出現する順序で挿入されます。 |
js |
|
省略可。一致するページに挿入される JavaScript ファイルのリストです。ファイルは、この配列に出現する順序で挿入されます。このリストの各文字列には、拡張機能のルート ディレクトリ内のリソースへの相対パスを含める必要があります。先頭のスラッシュ(/)は自動的に削除されます。 |
run_at |
RunAt | 省略可。スクリプトをページに挿入するタイミングを指定します。デフォルトは document_idle です。 |
match_about_blank |
boolean | 省略可。matches で宣言されたパターンの 1 つに親フレームまたはオープナー フレームが一致する about:blank フレームにスクリプトを注入するかどうか。デフォルトは false です。 |
match_origin_as_fallback |
boolean |
省略可。一致するオリジンで作成されたが、その URL またはオリジンがパターンと直接一致しない可能性があるフレームを、スクリプトで挿入するかどうか。これには、about: 、data: 、blob: 、filesystem: などの異なるスキームのフレームが含まれます。関連フレームの挿入もご覧ください。 |
world |
ExecutionWorld |
省略可。スクリプトが実行される JavaScript の世界。デフォルトは ISOLATED です。分離された環境で作業するもご覧ください。 |
動的宣言による挿入
動的コンテンツ スクリプトは、コンテンツ スクリプトの一致パターンが不明な場合や、コンテンツ スクリプトを既知のホストに必ずしも挿入すべきでない場合に役立ちます。
Chrome 96 で導入された動的宣言は静的宣言に似ていますが、コンテンツ スクリプト オブジェクトは manifest.json ではなく chrome.scripting
名前空間のメソッドを使用して Chrome に登録されます。拡張機能のデベロッパーは、Scripting API を使用して次のこともできます。
静的宣言と同様に、動的宣言には JavaScript ファイル、CSS ファイル、またはその両方を含めることができます。
service-worker.js
chrome.scripting
.registerContentScripts([{
id: "session-script",
js: ["content.js"],
persistAcrossSessions: false,
matches: ["*://example.com/*"],
runAt: "document_start",
}])
.then(() => console.log("registration complete"))
.catch((err) => console.warn("unexpected error", err))
service-worker.js
chrome.scripting
.updateContentScripts([{
id: "session-script",
excludeMatches: ["*://admin.example.com/*"],
}])
.then(() => console.log("registration updated"));
service-worker.js
chrome.scripting
.getRegisteredContentScripts()
.then(scripts => console.log("registered content scripts", scripts));
service-worker.js
chrome.scripting
.unregisterContentScripts({ ids: ["session-script"] })
.then(() => console.log("un-registration complete"));
プログラムによる挿入
イベントに応じて、または特定の状況で実行する必要があるコンテンツ スクリプトには、プログラムによる挿入を使用します。
プログラムでコンテンツ スクリプトを挿入するには、拡張機能がスクリプトを挿入しようとしているページに対するホスト権限が必要です。ホスト権限は、拡張機能のマニフェストの一部としてリクエストするか、"activeTab"
を使用して一時的に付与できます。
以下は、activeTab ベースの拡張機能のさまざまなバージョンです。
manifest.json:
{
"name": "My extension",
...
"permissions": [
"activeTab",
"scripting"
],
"background": {
"service_worker": "background.js"
},
"action": {
"default_title": "Action Button"
}
}
コンテンツ スクリプトはファイルとして挿入できます。
content-script.js
document.body.style.backgroundColor = "orange";
service-worker.js:
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: { tabId: tab.id },
files: ["content-script.js"]
});
});
または、関数本体をコンテンツ スクリプトとして挿入して実行できます。
service-worker.js:
function injectedFunction() {
document.body.style.backgroundColor = "orange";
}
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target : {tabId : tab.id},
func : injectedFunction,
});
});
注入される関数は、元の関数自体ではなく、chrome.scripting.executeScript()
呼び出しで参照される関数のコピーであることにご注意ください。そのため、関数の本文は自己完結型にする必要があります。関数の外部にある変数を参照すると、コンテンツ スクリプトが ReferenceError
をスローします。
関数として挿入する場合は、関数に引数を渡すこともできます。
service-worker.js
function injectedFunction(color) {
document.body.style.backgroundColor = color;
}
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target : {tabId : tab.id},
func : injectedFunction,
args : [ "orange" ],
});
});
一致と glob を除外する
指定したページの照合をカスタマイズするには、次のフィールドを宣言型登録に含めます。
Name | 型 | 説明 |
---|---|---|
exclude_matches |
文字列の配列 | 省略可。このコンテンツのスクリプトが挿入されるページは除外されます。これらの文字列の構文の詳細については、一致パターンをご覧ください。 |
include_globs |
文字列の配列 | 省略可。この glob にも一致する URL のみを含めるために matches より後に適用されます。これは、@include Greasemonkey キーワードをエミュレートすることを目的としています。 |
exclude_globs |
文字列の配列 | 省略可。この glob に一致する URL を除外するために、matches より後に適用されます。@exclude Greasemonkey キーワードをエミュレートすることを目的としています。 |
次の条件が両方とも満たされている場合、コンテンツ スクリプトがページに挿入されます。
- その URL は、任意の
matches
パターンおよび任意のinclude_globs
パターンと一致します。 - URL が
exclude_matches
またはexclude_globs
のパターンとも一致しない。matches
プロパティは必須であるため、exclude_matches
、include_globs
、exclude_globs
は、影響を受けるページを制限する場合にのみ使用できます。
次の拡張機能は、コンテンツ スクリプトを https://www.nytimes.com/health
に挿入しますが、https://www.nytimes.com/business
には挿入しません。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"exclude_matches": ["*://*/*business*"],
"js": ["contentScript.js"]
}
],
...
}
service-worker.js
chrome.scripting.registerContentScripts([{
id : "test",
matches : [ "https://*.nytimes.com/*" ],
excludeMatches : [ "*://*/*business*" ],
js : [ "contentScript.js" ],
}]);
glob プロパティは、一致パターンとは異なる柔軟な構文に従います。使用できる glob 文字列は、「ワイルドカード」のアスタリスクと疑問符を含む URL です。アスタリスク(*
)は、空の文字列を含む任意の長さの任意の文字列に一致し、疑問符(?
)は任意の 1 文字に一致します。
たとえば、glob https://???.example.com/foo/\*
は次のいずれかに一致します。
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
この拡張機能は、コンテンツ スクリプトを https://www.nytimes.com/arts/index.html
と https://www.nytimes.com/jobs/index.htm*
に挿入しますが、https://www.nytimes.com/sports/index.html
には挿入しません。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"include_globs": ["*nytimes.com/???s/*"],
"js": ["contentScript.js"]
}
],
...
}
この拡張機能は、コンテンツ スクリプトを https://history.nytimes.com
と https://.nytimes.com/history
に挿入しますが、https://science.nytimes.com
と https://www.nytimes.com/science
には挿入しません。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"exclude_globs": ["*science*"],
"js": ["contentScript.js"]
}
],
...
}
適切なスコープを実現するために、これらのうちの 1 つ、すべて、または一部を含めることができます。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"exclude_matches": ["*://*/*business*"],
"include_globs": ["*nytimes.com/???s/*"],
"exclude_globs": ["*science*"],
"js": ["contentScript.js"]
}
],
...
}
実行日時
run_at
フィールドは、JavaScript ファイルがウェブページに挿入されるタイミングを制御します。推奨されるデフォルト値は "document_idle"
です。その他の有効な値については、RunAt タイプをご覧ください。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"run_at": "document_idle",
"js": ["contentScript.js"]
}
],
...
}
service-worker.js
chrome.scripting.registerContentScripts([{
id : "test",
matches : [ "https://*.nytimes.com/*" ],
runAt : "document_idle",
js : [ "contentScript.js" ],
}]);
Name | 型 | 説明 |
---|---|---|
document_idle |
文字列 | 推奨:可能な限り "document_idle" を使用してください。ブラウザは、 "document_end" と window.onload イベントが発生した直後の間でスクリプトを挿入する時間を選択します。挿入の正確なタイミングは、ドキュメントの複雑さと読み込み時間によって異なり、ページの読み込み速度に合わせて最適化されます。"document_idle" で実行されるコンテンツ スクリプトは、window.onload イベントをリッスンする必要はなく、DOM の完了後に実行されることが保証されます。window.onload の後にスクリプトを実行する必要がある場合は、拡張機能で document.readyState プロパティを使用して、onload がすでに呼び出されているかどうかを確認できます。 |
document_start |
文字列 | スクリプトは、css からのファイルの後、他の DOM の構築や他のスクリプトの実行の前に挿入されます。 |
document_end |
文字列 | スクリプトは、DOM の完了直後、画像やフレームなどのサブリソースの読み込みが完了する前に挿入されます。 |
フレームを指定する
この拡張機能では、"all_frames"
フィールドを使用して、指定した URL 要件に一致するすべてのフレームに JavaScript ファイルと CSS ファイルを挿入するか、タブの最上位フレームのみに挿入するかを指定できます。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"all_frames": true,
"js": ["contentScript.js"]
}
],
...
}
service-worker.js
chrome.scripting.registerContentScripts([{
id: "test",
matches : [ "https://*.nytimes.com/*" ],
allFrames : true,
js : [ "contentScript.js" ],
}]);
Name | 型 | 説明 |
---|---|---|
all_frames |
boolean | 省略可。デフォルトは false で、先頭のフレームのみが照合されます。true を指定すると、そのフレームがタブの最上位フレームでなくても、すべてのフレームが注入されます。各フレームは個別に URL 要件が確認されます。URL の要件を満たしていない場合は、子フレームに挿入されません。 |
関連フレームへの注入
拡張機能は、一致するフレームに関連していても、それ自体が一致しないフレームでスクリプトを実行する場合があります。これに該当する一般的なシナリオは、一致するフレームによって作成されたが、その URL 自体がスクリプトの指定パターンと一致しないフレームの場合です。
これは、拡張機能が about:
、data:
、blob:
、filesystem:
スキームを含む URL のフレームに挿入する場合に該当します。このような場合、URL はコンテンツ スクリプトのパターンと一致しません(about:
と data:
の場合は、about:blank
や data:text/html,<html>Hello, World!</html>
のように、親 URL やオリジンを URL に一切含めないでください)。ただし、これらのフレームは作成中のフレームに関連付けることができます。
これらのフレームに挿入するために、拡張機能でマニフェストのコンテンツ スクリプト仕様に "match_origin_as_fallback"
プロパティを指定できます。
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.google.com/*"],
"match_origin_as_fallback": true,
"js": ["contentScript.js"]
}
],
...
}
これを指定して true
に設定すると、Chrome はフレーム自体の URL ではなく、フレームの開始元のオリジンを確認してフレームが一致するかどうかを判断します。なお、これはターゲット フレームのオリジンとは異なる場合があります(例:data:
URL のオリジンが null の場合)。
フレームのイニシエータは、ターゲット フレームを作成または移動したフレームです。通常は直接の親またはオープナーですが、そうでない場合もあります(iframe 内の iframe を移動するフレームの場合など)。
これはイニシエータ フレームのオリジンを比較するため、イニシエータ フレームはそのオリジンからの任意のパスに存在する可能性があります。この意味を明確にするために、Chrome では、"match_origin_as_fallback"
を true
に設定したコンテンツ スクリプトに *
のパスも指定する必要があります。
"match_origin_as_fallback"
と "match_about_blank"
の両方が指定されている場合、"match_origin_as_fallback"
が優先されます。
エンベディング ページとの通信
コンテンツ スクリプトの実行環境と、それをホストするページは互いに分離されていますが、ページの DOM へのアクセスは共有されます。ページがコンテンツ スクリプトまたはコンテンツ スクリプトを介して拡張機能と通信する必要がある場合は、共有 DOM を介して通信する必要があります。
window.postMessage()
を使用した例を次に示します。
content-script.js
var port = chrome.runtime.connect();
window.addEventListener("message", (event) => {
// We only accept messages from ourselves
if (event.source !== window) {
return;
}
if (event.data.type && (event.data.type === "FROM_PAGE")) {
console.log("Content script received: " + event.data.text);
port.postMessage(event.data.text);
}
}, false);
example.js
document.getElementById("theButton").addEventListener("click", () => {
window.postMessage(
{type : "FROM_PAGE", text : "Hello from the webpage!"}, "*");
}, false);
拡張機能以外のページ(example.html)は、そのページ自体にメッセージを投稿します。このメッセージはコンテンツ スクリプトによってインターセプトされて検査されてから、拡張機能プロセスに送信されます。これにより、このページは拡張プロセスへの通信を確立します。その逆も同様の方法で行えます。
拡張機能ファイルにアクセスする
コンテンツ スクリプトから拡張機能ファイルにアクセスするには、次の例(content.js
)に示すように、chrome.runtime.getURL()
を呼び出して拡張機能アセットの絶対 URL を取得します。
content-script.js
let image = chrome.runtime.getURL("images/my_image.png")
CSS ファイルでフォントや画像を使用するには、@@extension_id
を使って、次の例(content.css
)のように URL を作成します。
content.css
body {
background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}
@font-face {
font-family: 'Stint Ultra Expanded';
font-style: normal;
font-weight: 400;
src: url('chrome-extension://__MSG_@@extension_id__/fonts/Stint Ultra Expanded.woff') format('woff');
}
すべてのアセットは、manifest.json
ファイルでウェブアクセス可能なリソースとして宣言する必要があります。
manifest.json
{
...
"web_accessible_resources": [
{
"resources": [ "images/*.png" ],
"matches": [ "https://example.com/*" ]
},
{
"resources": [ "fonts/*.woff" ],
"matches": [ "https://example.com/*" ]
}
],
...
}
安全性の確保
分離された環境では保護レイヤが提供されますが、コンテンツ スクリプトを使用すると、拡張機能やウェブページに脆弱性が生じる可能性があります。コンテンツ スクリプトが(fetch()
を呼び出すなどして)別のウェブサイトからコンテンツを受け取る場合は、コンテンツを挿入する前にクロスサイト スクリプティング攻撃に対してコンテンツをフィルタリングしてください。"man-in-the-middle"攻撃を回避するため、HTTPS でのみ通信を行います。
悪意のあるウェブページが含まれていないか必ずフィルタしてください。たとえば、次のパターンは危険であり、Manifest V3 では許可されません。
content-script.js
const data = document.getElementById("json-data"); // WARNING! Might be evaluating an evil script! const parsed = eval("(" + data + ")");
content-script.js
const elmt_id = ... // WARNING! elmt_id might be '); ... evil script ... //'! window.setTimeout("animate(" + elmt_id + ")", 200);
代わりに、スクリプトを実行しない、より安全な API を使用してください。
content-script.js
const data = document.getElementById("json-data") // JSON.parse does not evaluate the attacker's scripts. const parsed = JSON.parse(data);
content-script.js
const elmt_id = ... // The closure form of setTimeout does not evaluate scripts. window.setTimeout(() => animate(elmt_id), 200);