説明
chrome.scripting
API を使用して、さまざまなコンテキストでスクリプトを実行します。
権限
scripting
対象
マニフェスト
chrome.scripting
API を使用するには、マニフェストで "scripting"
権限と、スクリプトを挿入するページのホスト権限を宣言します。一時的なホストの権限を付与する "host_permissions"
キーまたは "activeTab"
権限を使用します。次の例では、activeTab 権限を使用しています。
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
コンセプトと使用方法
chrome.scripting
API を使用して、JavaScript と CSS をウェブサイトに挿入できます。これは、コンテンツ スクリプトでできることに似ています。ただし、chrome.scripting
名前空間を使用すると、拡張機能が実行時に決定を下すことができます。
インジェクション ターゲット
target
パラメータを使用して、JavaScript または CSS を挿入するターゲットを指定できます。
必須項目は tabId
のみです。デフォルトでは、インジェクションは指定されたタブのメインフレームで実行されます。
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
指定したタブのすべてのフレームで実行するには、allFrames
ブール値を true
に設定します。
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
個別のフレーム ID を指定して、タブの特定のフレームに挿入することもできます。フレーム ID の詳細については、chrome.webNavigation
API をご覧ください。
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
コードの挿入
拡張機能では、外部ファイルまたはランタイム変数を介して挿入するコードを指定できます。
ファイル
ファイルは、拡張機能のルート ディレクトリからの相対パスである文字列として指定します。次のコードは、script.js
ファイルをタブのメインフレームに挿入します。
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
ランタイム関数
scripting.executeScript()
を使用して JavaScript を挿入する場合は、ファイルの代わりに実行する関数を指定できます。この関数は、現在の拡張機能コンテキストで使用できる関数変数にする必要があります。
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
この問題を回避するには、args
プロパティを使用します。
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
ランタイム文字列
ページ内に CSS を挿入する場合は、css
プロパティで使用する文字列を指定することもできます。このオプションは scripting.insertCSS()
でのみ使用できます。scripting.executeScript()
を使用して文字列を実行することはできません。
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
結果を処理する
JavaScript の実行結果は拡張機能に渡されます。フレームごとに 1 つの結果が含まれます。メインフレームは結果の配列の最初のインデックスであることが保証され、他のすべてのフレームは非決定的な順序になります。
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
scripting.insertCSS()
は結果を返しません。
Promise
スクリプト実行の結果の値が Promise の場合、Chrome は Promise が解決されるのを待ってから、生成された値を返します。
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
例
すべての動的コンテンツ スクリプトの登録を解除
次のスニペットには、拡張機能が以前に登録したすべての動的コンテンツ スクリプトの登録を解除する関数が含まれています。
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
chrome.scripting
API を試すには、Chrome 拡張機能のサンプル リポジトリからスクリプト サンプルをインストールします。
型
ContentScriptFilter
プロパティ
-
ids
string[] 省略可
指定すると、
getRegisteredContentScripts
はこのリストで指定された ID を持つスクリプトのみを返します。
CSSInjection
プロパティ
-
css
string(省略可)
挿入する CSS を含む文字列です。
files
またはcss
のいずれか 1 つのみを指定する必要があります。 -
ファイル
string[] 省略可
挿入する CSS ファイルのパス(拡張機能のルート ディレクトリからの相対パス)。
files
またはcss
のいずれか 1 つのみを指定する必要があります。 -
出所
StyleOrigin 省略可
インジェクションのスタイルの起点。デフォルトは
'AUTHOR'
です。 -
ターゲット
CSS の挿入先となるターゲットを指定する詳細。
ExecutionWorld
スクリプトが実行される JavaScript の世界。
Enum
"ISOLATED"
分離された環境(この拡張機能に固有の実行環境)を指定します。
"MAIN"
DOM のメイン環境(ホストページの JavaScript と共有される実行環境)を指定します。
InjectionResult
プロパティ
-
documentId
文字列
Chrome 106 以降インジェクションに関連するドキュメント。
-
frameId
数値
Chrome 90 以降インジェクションに関連するフレーム。
-
件の結果
省略可
スクリプトの実行結果。
InjectionTarget
プロパティ
RegisteredContentScript
プロパティ
-
allFrames
ブール値(省略可)
true に設定すると、タブの最上部のフレームでなくても、すべてのフレームに挿入されます。各フレームは URL の要件について個別にチェックされます。URL の要件が満たされていない場合、子フレームには挿入されません。デフォルトは false で、一番上のフレームのみが照合されます。
-
css
string[] 省略可
一致するページに挿入される CSS ファイルのリストです。これらは、ページに対して DOM が構築または表示される前に、この配列に出現する順序で挿入されます。
-
excludeMatches
string[] 省略可
このコンテンツのスクリプトが挿入されるページは除外されます。これらの文字列の構文の詳細については、一致パターンをご覧ください。
-
id
文字列
API 呼び出しで指定されたコンテンツ スクリプトの ID。先頭に「_」は使用できません。これは、生成されたスクリプト ID の接頭辞として予約されています。
-
js
string[] 省略可
一致するページに挿入される JavaScript ファイルのリストです。これらは、この配列に出現する順序で挿入されます。
-
matchOriginAsFallback
ブール値(省略可)
Chrome 119 以降サポートされていないスキーム(about:、data:、blob:、filesystem:)が URL に含まれているフレームにスクリプトを挿入できるかどうかを示します。このような場合は、URL の生成元を確認して、スクリプトを挿入する必要があるかどうかを判断します。オリジンが
null
の場合(data: URL の場合と同様)、使用されるオリジンは、現在のフレームを作成したフレームか、このフレームへのナビゲーションを開始したフレームです。なお、これは親フレームではない可能性があります。 -
一致
string[] 省略可
このコンテンツのスクリプトを挿入するページを指定します。これらの文字列の構文の詳細については、一致パターンをご覧ください。
registerContentScripts
に指定する必要があります。 -
persistAcrossSessions
ブール値(省略可)
このコンテンツのスクリプトを今後のセッションでも保持するかどうかを指定します。デフォルトは true です。
-
runAt
RunAt(省略可)
JavaScript ファイルをウェブページに挿入するタイミングを指定します。推奨されるデフォルト値は
document_idle
です。 -
世界
ExecutionWorld 省略可
Chrome 102 以降スクリプトを実行する JavaScript の「world」。デフォルトは
ISOLATED
です。
ScriptInjection
プロパティ
-
args
any[] 省略可
Chrome 92 以降指定された関数に渡す引数。これは、
func
パラメータが指定されている場合にのみ有効です。これらの引数は JSON でシリアル化可能である必要があります。 -
ファイル
string[] 省略可
挿入する JS ファイルまたは CSS ファイルのパス(拡張機能のルート ディレクトリからの相対パス)。
files
またはfunc
のいずれか 1 つのみを指定する必要があります。 -
injectImmediately
ブール値(省略可)
Chrome 102 以降ターゲットでできるだけ早くインジェクションをトリガーするかどうか。ただし、スクリプトがターゲットに到達するまでにページがすでに読み込まれている可能性があるため、ページの読み込み前に挿入が行われるとは限りません。
-
ターゲット
スクリプトの挿入先のターゲットを指定する詳細。
-
世界
ExecutionWorld 省略可
Chrome 95 以降スクリプトを実行する JavaScript の「world」。デフォルトは
ISOLATED
です。 -
func
void 省略可
Chrome 92 以降挿入する JavaScript 関数。この関数はシリアル化され、インジェクションのためにシリアル化解除されます。つまり、バインドされているパラメータと実行コンテキストはすべて失われます。
files
またはfunc
のいずれか 1 つのみを指定する必要があります。func
関数は次のようになります。() => {...}
StyleOrigin
スタイル変更の起点。詳しくは、スタイルのオリジンをご覧ください。
Enum
Methods
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
ターゲット コンテキストにスクリプトを挿入します。デフォルトでは、スクリプトは document_idle
に実行されます。ページがすでに読み込まれている場合はすぐに実行されます。injectImmediately
プロパティが設定されている場合、ページの読み込みが完了していなくても、スクリプトは待機なしで挿入します。スクリプトが Promise と評価された場合、ブラウザは Promise が解決されるのを待ってから、結果の値を返します。
パラメータ
-
インジェクション
挿入するスクリプトの詳細。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(results: InjectionResult[]) => void
-
結果
-
戻り値
-
Promise<InjectionResult[]>
Chrome 90 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
指定したフィルタに一致する、この拡張機能に動的に登録されたコンテンツ スクリプトをすべて返します。
パラメータ
-
フィルタ
拡張機能に動的に登録されたスクリプトをフィルタするオブジェクト。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(scripts: RegisteredContentScript[]) => void
-
スクリプト
-
戻り値
-
Promise<RegisteredContentScript[]>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
CSS スタイルシートをターゲット コンテキストに挿入します。複数のフレームが指定されている場合、失敗したインジェクションは無視されます。
パラメータ
-
インジェクション
挿入するスタイルの詳細。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 90 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
この拡張機能に 1 つ以上のコンテンツ スクリプトを登録します。
パラメータ
-
スクリプト
登録するスクリプトのリストが含まれています。スクリプトの解析やファイルの検証でエラーが発生した場合や、指定した ID がすでに存在する場合、スクリプトは登録されません。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
以前にこの拡張機能によって挿入された CSS スタイルシートをターゲット コンテキストから削除します。
パラメータ
-
インジェクション
削除するスタイルの詳細。
css
、files
、origin
の各プロパティは、insertCSS
で挿入されたスタイルシートと完全に一致している必要があります。存在しないスタイルシートを削除しようとしても何も起こりません。 -
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
この拡張機能のコンテンツ スクリプトの登録を解除します。
パラメータ
-
フィルタ
指定すると、フィルタに一致する動的コンテンツ スクリプトのみを登録解除します。それ以外の場合、拡張機能の動的コンテンツ スクリプトはすべて登録されません。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
この拡張機能の 1 つ以上のコンテンツ スクリプトを更新します。
パラメータ
-
スクリプト
更新するスクリプトのリストが含まれます。このオブジェクトで指定されていれば、既存のスクリプトのプロパティのみが更新されます。スクリプトの解析やファイルの検証でエラーが発生した場合や、指定された ID が完全に登録されたスクリプトに対応していない場合、スクリプトは更新されません。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。