chrome.userScripts

説明

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 120 以降 MV3 以降

コンセプトと使用方法

ユーザー スクリプトとは、ウェブページの外観や動作を変更するためにウェブページに挿入される小さなコードです。スクリプトは、ユーザーが作成するか、スクリプト リポジトリまたはユーザー スクリプト拡張機能からダウンロードされます。

拡張機能ユーザーのデベロッパー モード

拡張機能のデベロッパーは、Chrome のインストールでデベロッパー モードをすでに有効にしています。ユーザー スクリプト拡張機能を使用する場合は、デベロッパー モードも有効にする必要があります。以下の手順は、コピーしてご自身のドキュメントに貼り付けることができます。

  1. 新しいタブで「chrome://extensions」と入力して [拡張機能] ページに移動します。（設計上、chrome:// URL はリンクできません）。

  2. [デベロッパー モード] の横にある切り替えスイッチをクリックして、デベロッパー モードを有効にします。

    [広告表示オプション] ページ

    拡張機能ページ（chrome://extensions）

デベロッパー モードが有効になっているかどうかは、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[] 省略可

    このユーザー スクリプトの挿入先となるページのワイルドカード パターンを指定します。

  • 一致するページに挿入するスクリプトのソースを定義する 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()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

`USER_SCRIPT` 実行環境を構成します。

パラメータ

  • プロパティ

    WorldProperties

    ユーザー スクリプトの世界構成が含まれています。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

この拡張機能に動的に登録されたユーザー スクリプトをすべて返します。

パラメータ

  • フィルタ

    UserScriptFilter 省略可

    指定すると、このメソッドは一致するユーザー スクリプトのみを返します。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (scripts: RegisteredUserScript[])=>void

戻り値

  • Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

この拡張機能に 1 つ以上のユーザー スクリプトを登録します。

パラメータ

  • スクリプト

    RegisteredUserScript[]

    登録するユーザー スクリプトのリストを指定します。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

この拡張機能に動的に登録されたすべてのユーザー スクリプトの登録を解除します。

パラメータ

  • フィルタ

    UserScriptFilter 省略可

    指定した場合、このメソッドは一致するユーザー スクリプトのみを登録解除します。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

この拡張機能の 1 つ以上のユーザー スクリプトを更新します。

パラメータ

  • スクリプト

    RegisteredUserScript[]

    更新するユーザー スクリプトのリストが含まれます。このオブジェクトで指定されていれば、既存のスクリプトのプロパティのみが更新されます。スクリプトの解析やファイルの検証でエラーが発生した場合や、指定された ID が完全に登録されたスクリプトに対応していない場合、スクリプトは更新されません。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。