chrome.userScripts

説明

userScripts API を使用して、ユーザー スクリプトのコンテキストでユーザー スクリプトを実行します。

権限

userScripts

chrome.userScripts API を使用するには、manifest.json に "userScripts" 権限を追加し、スクリプトを実行するサイトに "host_permissions" を追加します。

{
  "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
});

拡張機能の更新

ユーザー スクリプトは、拡張機能の更新時に削除されます。拡張機能サービス ワーカーの runtime.onInstalled イベント ハンドラでコードを実行すると、これらの機能を再度追加できます。イベント コールバックに渡された "update" の理由にのみ応答します。

例

この例は、サンプル リポジトリの userScript サンプルから取ったものです。

スクリプトを登録する

次の例は、register() の基本的な呼び出しを示しています。最初の引数は、登録するスクリプトを定義するオブジェクトの配列です。ここに表示されているオプション以外にも、さまざまなオプションがあります。

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

型

ExecutionWorld

ユーザー スクリプトが実行される JavaScript の世界。

列挙型

「MAIN」
DOM の実行環境を指定します。これは、ホストページの JavaScript と共有される実行環境です。

「USER_SCRIPT」
ユーザー スクリプトに固有の実行環境を指定し、ページの CSP の適用対象から除外します。

RegisteredUserScript

プロパティ

  • allFrames

    ブール値（省略可）

    true の場合、タブ内の最上位のフレームでなくても、すべてのフレームに挿入されます。各フレームは URL 要件について個別にチェックされます。URL 要件が満たされていない場合、子フレームには挿入されません。デフォルトは false で、最上位のフレームのみが照合されます。

  • excludeGlobs

    string[] 省略可

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

  • excludeMatches

    string[] 省略可

    このユーザー スクリプトが挿入されるページを除外します。これらの文字列の構文の詳細については、一致パターンをご覧ください。

  • id

    文字列

    API 呼び出しで指定されたユーザー スクリプトの ID。このプロパティは、生成されるスクリプト ID の接頭辞として予約されているため、先頭に「_」を付けないでください。

  • includeGlobs

    string[] 省略可

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

  • js

    ScriptSource[] 省略可

    一致するページに挿入されるスクリプトのソースを定義する ScriptSource オブジェクトのリスト。このプロパティは ${ref:register} に指定する必要があります。指定する場合は、空でない配列にする必要があります。

  • 一致

    string[] 省略可

    このユーザー スクリプトを挿入するページを指定します。これらの文字列の構文の詳細については、一致パターンをご覧ください。このプロパティは ${ref:register} に指定する必要があります。

  • runAt

    RunAt 省略可

    JavaScript ファイルがウェブページに挿入されるタイミングを指定します。推奨されるデフォルト値は document_idle です。

  • 世界

    ExecutionWorld（省略可）

    スクリプトを実行する JavaScript 実行環境。デフォルト値は `USER_SCRIPT` です。

  • worldId

    文字列 省略可

    保留中

    指定した場合は、実行する特定のユーザー スクリプト ワールド ID を指定します。world が省略されているか USER_SCRIPT の場合にのみ有効です。省略すると、スクリプトはデフォルトのユーザー スクリプト ワールドで実行されます。先頭にアンダースコア（_）が付いた値は予約済みです。

ScriptSource

プロパティ

  • コード

    文字列 省略可

    挿入する JavaScript コードを含む文字列。file または code のいずれか 1 つを指定する必要があります。

  • ファイル

    文字列 省略可

    拡張機能のルート ディレクトリを基準とする、挿入する JavaScript ファイルのパス。file または code のいずれか 1 つを指定する必要があります。

UserScriptFilter

プロパティ

  • ids

    string[] 省略可

    getScripts は、このリストに指定された ID のスクリプトのみ返します。

WorldProperties

プロパティ

  • csp

    文字列 省略可

    世界 csp を指定します。デフォルトは `ISOLATED` 世界 csp です。

  • メッセージング

    ブール値（省略可）

    メッセージ アプリの API を公開するかどうかを指定します。デフォルト値は false です。

  • worldId

    文字列 省略可

    保留中

    更新する特定のユーザー スクリプト ワールドの ID を指定します。指定しない場合、デフォルトのユーザー スクリプト ワールドのプロパティが更新されます。先頭にアンダースコア（_）が付いた値は予約済みです。

メソッド

configureWorld()

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

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

パラメータ

  • プロパティ

    WorldProperties

    ユーザー スクリプトのワールド構成が含まれています。

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

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

getScripts()

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

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

パラメータ

  • フィルタ

    UserScriptFilter（省略可）

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

  • callback

    function 省略可

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

    (scripts: RegisteredUserScript[]) => void

戻り値

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

getWorldConfigurations()

Promise 保留中
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

登録されているすべてのワールド構成を取得します。

パラメータ

  • callback

    function 省略可

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

    (worlds: WorldProperties[]) => void

戻り値

  • Promise<WorldProperties[]>

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

register()

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

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

パラメータ

  • スクリプト

    RegisteredUserScript[]

    登録するユーザー スクリプトのリストが含まれています。

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

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

resetWorldConfiguration()

Promise 保留中
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

ユーザー スクリプト ワールドの構成をリセットします。指定された ID でワールドに挿入されるスクリプトは、デフォルトのワールド構成を使用します。

パラメータ

  • worldId

    文字列 省略可

    再設定するユーザー スクリプト ワールドの ID。省略した場合は、デフォルトのワールドの構成がリセットされます。

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

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

unregister()

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

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

パラメータ

  • フィルタ

    UserScriptFilter（省略可）

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

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

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

update()

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

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

パラメータ

  • スクリプト

    RegisteredUserScript[]

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

  • callback

    function 省略可

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

    () => void

戻り値

  • Promise<void>

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