説明
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({ ids: 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
文字列 省略可
挿入する CSS を含む文字列。
filesとcssのいずれか 1 つを指定する必要があります。 - ファイル
string[] 省略可
挿入する CSS ファイルのパス。拡張機能のルート ディレクトリを基準とする相対パスです。
filesとcssのいずれか 1 つを指定する必要があります。 - origin
StyleOrigin 省略可
挿入のスタイル生成元。デフォルトは
'AUTHOR'です。 - ターゲット
CSS を挿入するターゲットを指定する詳細。
ExecutionWorld
スクリプトが実行される JavaScript の世界。
列挙型
「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 以降URL にサポートされていないスキーム（about:、data:、blob:、filesystem: など）が含まれるフレームにスクリプトを挿入できるかどうかを示します。このような場合、URL のオリジンがチェックされ、スクリプトを挿入するかどうかが判断されます。オリジンが
nullの場合（data: URL の場合など）、使用されるオリジンは、現在のフレームを作成したフレームか、このフレームへのナビゲーションを開始したフレームのいずれかです。これは親フレームではない場合があります。 - 一致
string[] 省略可
このコンテンツ スクリプトが挿入されるページを指定します。これらの文字列の構文の詳細については、一致パターンをご覧ください。
registerContentScriptsで指定する必要があります。 - persistAcrossSessions
ブール値（省略可）
このコンテンツ スクリプトが今後のセッションでも保持されるかどうかを指定します。デフォルトは true です。
- runAt
RunAt 省略可
JavaScript ファイルがウェブページに挿入されるタイミングを指定します。推奨されるデフォルト値は
document_idleです。 - 世界
ExecutionWorld 省略可
Chrome 102 以降スクリプトを実行する JavaScript の「世界」。デフォルトは
ISOLATEDです。
ScriptInjection
プロパティ
- args
any[] 省略可
Chrome 92 以降指定された関数に渡す引数。これは、
funcパラメータが指定されている場合にのみ有効です。これらの引数は JSON シリアル化可能である必要があります。 - ファイル
string[] 省略可
拡張機能のルート ディレクトリを基準とした、挿入する JS ファイルまたは CSS ファイルのパス。
filesまたはfuncのいずれか 1 つを指定する必要があります。 - injectImmediately
ブール値（省略可）
Chrome 102 以降ターゲットでできるだけ早くインジェクションをトリガーするかどうか。スクリプトがターゲットに到達するまでにページがすでに読み込まれている可能性があるため、ページ読み込み前に挿入が行われるとは限りません。
- ターゲット
スクリプトを挿入するターゲットを指定する詳細。
- 世界
ExecutionWorld 省略可
Chrome 95 以降スクリプトを実行する JavaScript の「世界」。デフォルトは
ISOLATEDです。 - func
void optional
Chrome 92 以降挿入する JavaScript 関数。この関数はシリアル化され、挿入のために逆シリアル化されます。つまり、バインドされたパラメータと実行コンテキストはすべて失われます。
filesまたはfuncのいずれか 1 つを指定する必要があります。func関数は次のようになります。() => {...}
StyleOrigin
スタイル変更の発生元。詳しくは、スタイルのオリジンをご覧ください。
列挙型
"AUTHOR"
"USER"
メソッド
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
): Promise<InjectionResult[]>
スクリプトをターゲット コンテキストに挿入します。デフォルトでは、スクリプトは document_idle で実行されます。ページがすでに読み込まれている場合は、すぐに実行されます。injectImmediately プロパティが設定されている場合、ページが読み込みを完了していなくても、スクリプトは待機せずに挿入されます。スクリプトが Promise に評価されると、ブラウザは Promise が確定するのを待ってから、結果の値を返します。
パラメータ
- インジェクション
挿入するスクリプトの詳細。
戻り値
-
Promise<InjectionResult[]>
Chrome 90 以降
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>
指定されたフィルタに一致する、この拡張機能の動的に登録されたすべてのコンテンツ スクリプトを返します。
パラメータ
- フィルタ
拡張機能の動的に登録されたスクリプトをフィルタするオブジェクト。
戻り値
-
Promise<RegisteredContentScript[]>
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
): Promise<void>
CSS スタイルシートをターゲット コンテキストに挿入します。複数のフレームが指定されている場合、挿入に失敗したフレームは無視されます。
パラメータ
- インジェクション
挿入するスタイルの詳細。
戻り値
-
Promise<void>
Chrome 90 以降
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
この拡張機能の 1 つ以上のコンテンツ スクリプトを登録します。
パラメータ
- スクリプト
登録するスクリプトのリストが含まれます。スクリプトの解析/ファイルの検証中にエラーが発生した場合、または指定された ID がすでに存在する場合は、スクリプトは登録されません。
戻り値
-
Promise<void>
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
): Promise<void>
この拡張機能によって以前に挿入された CSS スタイルシートを、ターゲット コンテキストから削除します。
パラメータ
- インジェクション
削除するスタイルの詳細。
css、files、originプロパティは、insertCSSを介して挿入されたスタイルシートと完全に一致している必要があります。存在しないスタイルシートを削除しようとしても、何も起こりません。
戻り値
-
Promise<void>
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
): Promise<void>
この拡張機能のコンテンツ スクリプトの登録を解除します。
パラメータ
- フィルタ
指定した場合、フィルタに一致する動的コンテンツ スクリプトのみを登録解除します。それ以外の場合は、拡張機能の動的コンテンツ スクリプトがすべて登録解除されます。
戻り値
-
Promise<void>
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
この拡張機能の 1 つ以上のコンテンツ スクリプトを更新します。
パラメータ
- スクリプト
更新するスクリプトのリストが含まれます。プロパティは、このオブジェクトで指定されている場合にのみ、既存のスクリプトに対して更新されます。スクリプトの解析やファイルの検証中にエラーが発生した場合、または指定された ID が完全に登録されたスクリプトに対応していない場合は、スクリプトは更新されません。
戻り値
-
Promise<void>