説明
userScripts
API を使用して、ユーザー スクリプトのコンテキストでユーザー スクリプトを実行します。
権限
userScripts
chrome.userScripts
API を使用するには、スクリプトを実行するサイトの manifest.json と "host_permissions"
に "userScripts"
権限を追加します。
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
対象
コンセプトと使用方法
ユーザー スクリプトとは、ウェブページの外観や動作を変更するためにウェブページに挿入される小さなコードです。スクリプトは、ユーザーが作成するか、スクリプト リポジトリまたはユーザー スクリプト拡張機能からダウンロードされます。
拡張機能ユーザーのデベロッパー モード
拡張機能のデベロッパーは、Chrome のインストールでデベロッパー モードをすでに有効にしています。ユーザー スクリプト拡張機能を使用する場合は、デベロッパー モードも有効にする必要があります。以下の手順は、コピーしてご自身のドキュメントに貼り付けることができます。
- 新しいタブで「
chrome://extensions
」と入力して [拡張機能] ページに移動します。(設計上、chrome://
URL はリンクできません)。 [デベロッパー モード] の横にある切り替えスイッチをクリックして、デベロッパー モードを有効にします。
デベロッパー モードが有効になっているかどうかは、chrome.userScripts
がエラーをスローするかどうかを確認することでわかります。次に例を示します。
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
隔離された環境で作業する
ユーザー スクリプトとコンテンツ スクリプトはどちらも、隔離された環境でもメイン環境でも実行できます。隔離された環境とは、ホストページや他の拡張機能からアクセスできない実行環境のことです。これにより、ホストページや他の拡張機能のユーザー スクリプトやコンテンツ スクリプトに影響を与えずに、ユーザー スクリプトが JavaScript 環境を変更できるようになります。逆に、ユーザー スクリプト(およびコンテンツ スクリプト)は、ホストページや、他の拡張機能のユーザー スクリプトやコンテンツ スクリプトには表示されません。メイン環境で実行されているスクリプトは、ホストページやその他の拡張機能からアクセスでき、ホストページや他の拡張機能から参照できます。ワールドを選択するには、userScripts.register()
を呼び出すときに "USER_SCRIPT"
または "MAIN"
を渡します。
USER_SCRIPT
環境のコンテンツ セキュリティ ポリシーを構成するには、userScripts.configureWorld()
を呼び出します。
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
メッセージ
コンテンツ スクリプトや画面外のドキュメントと同様に、ユーザー スクリプトはメッセージを使用して拡張機能の他の部分と通信します(つまり、拡張機能の他の部分と同様に runtime.sendMessage()
と runtime.connect()
を呼び出すことができます)。ただし、専用のイベント ハンドラを使用して受信します(つまり、onMessage
や onConnect
は使用しません)。これらのハンドラは、runtime.onUserScriptMessage
および runtime.onUserScriptConnect
と呼ばれます。専用ハンドラを使用すると、信頼性の低いコンテキストであるユーザー スクリプトからのメッセージを簡単に識別できます。
メッセージを送信する前に、messaging
引数を true
に設定して configureWorld()
を呼び出す必要があります。csp
引数と messaging
引数は同時に渡すことができます。
chrome.userScripts.configureWorld({
messaging: true
});
拡張機能の更新
ユーザー スクリプトは拡張機能の更新時に消去されます。拡張機能 Service Worker の runtime.onInstalled
イベント ハンドラでコードを実行することで、再度追加できます。イベントのコールバックに渡された "update"
の理由にのみ応答します。
例
この例は、サンプル リポジトリの userScript サンプルの一部です。
スクリプトを登録する
次の例は、register()
の基本的な呼び出しを示しています。1 つ目の引数は、登録するスクリプトを定義するオブジェクトの配列です。ここで紹介する以外にも多数のオプションがあります。
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
型
ExecutionWorld
ユーザー スクリプトが実行される JavaScript の世界。
列挙型
"MAIN"
DOM の実行環境を指定します。これは、ホストページの JavaScript と共有される実行環境です。
"USER_SCRIPT"
ユーザー スクリプトに固有で、ページの CSP から除外される実行環境を指定します。
RegisteredUserScript
Properties
-
allFrames
ブール値(省略可)
true の場合、そのフレームがタブの最上位フレームでなくても、すべてのフレームに挿入されます。各フレームは URL の要件について個別にチェックされます。URL の要件が満たされていない場合、子フレームには挿入されません。デフォルトは false で、一番上のフレームのみが照合されます。
-
excludeGlobs
string[] 省略可
このユーザー スクリプトが挿入されないページのワイルドカード パターンを指定します。
-
excludeMatches
string[] 省略可
このユーザー スクリプトが挿入されるページは除外されます。これらの文字列の構文の詳細については、一致パターンをご覧ください。
-
id
string
API 呼び出しで指定されたユーザー スクリプトの ID。このプロパティの先頭を「_」にすることはできません。このプロパティは、生成されたスクリプト ID の接頭辞として予約されています。
-
includeGlobs
string[] 省略可
このユーザー スクリプトの挿入先となるページのワイルドカード パターンを指定します。
-
js
一致するページに挿入するスクリプトのソースを定義する ScriptSource オブジェクトのリスト。
-
一致
string[] 省略可
このユーザー スクリプトを挿入するページを指定します。これらの文字列の構文の詳細については、一致パターンをご覧ください。このプロパティは ${ref:register} に対して指定する必要があります。
-
runAt
RunAt(省略可)
JavaScript ファイルをウェブページに挿入するタイミングを指定します。推奨されるデフォルト値は
document_idle
です。 -
世界
ExecutionWorld 省略可
スクリプトを実行する JavaScript 実行環境。デフォルト値は
`USER_SCRIPT`
です。
ScriptSource
Properties
-
コード
string(省略可)
挿入する JavaScript コードを含む文字列。
file
またはcode
のいずれか 1 つのみを指定する必要があります。 -
あなた宛てに表示されます。
string(省略可)
挿入する JavaScript ファイルのパス(拡張機能のルート ディレクトリからの相対パス)。
file
またはcode
のいずれか 1 つのみを指定する必要があります。
UserScriptFilter
Properties
-
ids
string[] 省略可
getScripts
は、このリストで指定された ID を持つスクリプトのみを返します。
WorldProperties
Properties
-
CSS
string(省略可)
ワールド CSP を指定します。デフォルトは
`ISOLATED`
ワールド CSP です。 -
メッセージング
ブール値(省略可)
メッセージング API を公開するかどうかを指定します。デフォルト値は
false
です。
Methods
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
`USER_SCRIPT`
実行環境を構成します。
パラメータ
-
プロパティ
ユーザー スクリプトの世界構成が含まれています。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
この拡張機能に動的に登録されたユーザー スクリプトをすべて返します。
パラメータ
-
フィルタ
UserScriptFilter 省略可
指定すると、このメソッドは一致するユーザー スクリプトのみを返します。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(scripts: RegisteredUserScript[]) => void
-
スクリプト
-
戻り値
-
Promise<RegisteredUserScript[]>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
この拡張機能に 1 つ以上のユーザー スクリプトを登録します。
パラメータ
-
スクリプト
登録するユーザー スクリプトのリストを指定します。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
この拡張機能に動的に登録されたすべてのユーザー スクリプトの登録を解除します。
パラメータ
-
フィルタ
UserScriptFilter 省略可
指定した場合、このメソッドは一致するユーザー スクリプトのみを登録解除します。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
この拡張機能の 1 つ以上のユーザー スクリプトを更新します。
パラメータ
-
スクリプト
更新するユーザー スクリプトのリストが含まれます。このオブジェクトで指定されていれば、既存のスクリプトのプロパティのみが更新されます。スクリプトの解析やファイルの検証でエラーが発生した場合や、指定された ID が完全に登録されたスクリプトに対応していない場合、スクリプトは更新されません。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。