このページは Cloud Translation API によって翻訳されました。

chrome.userScripts

説明

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

権限

userScripts

User Scripts API chrome.userScripts を使用するには、マニフェストファイルの "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.scripting API などの他の拡張機能とは異なり、User Scripts API では任意のコードを実行できます。この API は、拡張機能パッケージの一部として配布できないユーザー提供のスクリプトを実行する拡張機能に必要です。

userScripts API の使用を有効にする

拡張機能が userScripts API を使用する権限を取得した後、ユーザーは特定の切り替えを有効にして、拡張機能が API を使用できるようにする必要があります。必要な特定の切り替えと、無効にした場合の API の動作は、Chrome のバージョンによって異なります。

たとえば、新規ユーザーのオンボーディング時に、ユーザーが有効にする必要がある切り替えを判断するには、次のチェックを使用します。

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

以降のセクションでは、さまざまな切り替えとその有効化方法について説明します。

Chrome バージョン 138 より前（デベロッパーモードの切り替え）

拡張機能のデベロッパーは、Chrome のインストールでデベロッパーモードがすでに有効になっています。ユーザーもデベロッパーモードを有効にする必要があります。

次の手順をコピーして、ユーザー向け拡張機能のドキュメントに貼り付けることができます。

新しいタブで chrome://extensions と入力して、[拡張機能] ページに移動します。（設計上、chrome:// URL はリンクできません）。
[デベロッパーモード] の横にある切り替えスイッチをクリックして、デベロッパーモードを有効にします。

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

Chrome バージョン 138 以降（[ユーザースクリプトを許可] 切り替え）

[ユーザースクリプトを許可する] 切り替えボタンは、各拡張機能の詳細ページ（chrome://extensions/?id=YOUR_EXTENSION_ID など）にあります。

次の手順をコピーして、拡張機能のユーザー向けドキュメントに貼り付けることができます。

新しいタブで chrome://extensions と入力して、[拡張機能] ページに移動します。（設計上、chrome:// URL はリンクできません）。
拡張機能カードの [詳細] ボタンをクリックすると、拡張機能の詳細情報が表示されます。
[ユーザースクリプトを許可] の横にある切り替えスイッチをクリックします。

拡張機能の詳細ページの [ユーザースクリプトを許可する] 切り替え — [ユーザースクリプトを許可する] の切り替え（chrome://extensions/?id=abc...）

API の可用性を確認する

すべての Chrome バージョンで動作するため、userScripts API が有効になっているかどうかを確認するには、次のチェックをおすすめします。このチェックでは、API が利用可能な場合に常に成功する chrome.userScripts() メソッドの呼び出しを試みます。この呼び出しがエラーをスローした場合、API は使用できません。

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    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 の対象外です。

InjectionResult

Chrome 135 以降

プロパティ

documentId

文字列

インジェクションに関連付けられたドキュメント。
エラー

文字列省略可

エラー（ある場合）。error と result は相互に排他的です。
frameId

数値

インジェクションに関連付けられたフレーム。
件の結果

任意の省略可

スクリプト実行の結果。

InjectionTarget

Chrome 135 以降

プロパティ

allFrames

ブール値（省略可）

スクリプトをタブ内のすべてのフレームに挿入するかどうか。デフォルトは false です。frameIds が指定されている場合、これは true にできません。
documentIds

string[] 省略可

挿入する特定の documentId の ID。frameIds が設定されている場合、この値は設定しないでください。
frameIds

number[] 省略可

挿入する特定のフレームの ID。
tabId

数値

挿入先のタブの ID。

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

文字列省略可

Chrome 133 以降

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

ScriptSource

プロパティ

コード

文字列省略可

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

文字列省略可

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

UserScriptFilter

プロパティ

ids

string[] 省略可

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

UserScriptInjection

Chrome 135 以降

プロパティ

injectImmediately

ブール値（省略可）

ターゲットでできるだけ早くインジェクションをトリガーするかどうか。スクリプトがターゲットに到達するまでにページがすでに読み込まれている可能性があるため、ページ読み込み前に挿入が行われるとは限りません。
js

ScriptSource[]

ターゲットに挿入されるスクリプトのソースを定義する ScriptSource オブジェクトのリスト。
ターゲット

InjectionTarget

スクリプトを挿入するターゲットを指定する詳細。
世界

ExecutionWorld 省略可

スクリプトを実行する JavaScript の「世界」。デフォルト値は USER_SCRIPT です。
worldId

文字列省略可

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

WorldProperties

プロパティ

csp

文字列省略可

ワールド csp を指定します。デフォルトは `ISOLATED` 世界の CSP です。
メッセージング

ブール値（省略可）

メッセージング API が公開されているかどうかを指定します。デフォルト値は false です。
worldId

文字列省略可

Chrome 133 以降

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

メソッド

configureWorld()

chrome.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

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

パラメータ

プロパティ

WorldProperties

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

戻り値

Promise<void>

execute()

Chrome 135 以降

chrome.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

スクリプトをターゲットコンテキストに挿入します。デフォルトでは、スクリプトは document_idle で実行されます。ページがすでに読み込まれている場合は、すぐに実行されます。injectImmediately プロパティが設定されている場合、ページが読み込みを完了していなくても、スクリプトは待機せずに挿入されます。スクリプトが Promise に評価されると、ブラウザは Promise が確定するのを待ってから、結果の値を返します。

パラメータ

インジェクション

UserScriptInjection

戻り値

Promise<InjectionResult[]>

getScripts()

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

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

パラメータ

フィルタ

UserScriptFilter 省略可

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

戻り値

Promise<RegisteredUserScript[]>

getWorldConfigurations()

Chrome 133 以降

chrome.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

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

戻り値

Promise<WorldProperties[]>

register()

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

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

パラメータ

スクリプト

RegisteredUserScript[]

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

戻り値

Promise<void>

resetWorldConfiguration()

Chrome 133 以降

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

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

パラメータ

worldId

文字列省略可

リセットするユーザースクリプトワールドの ID。省略すると、デフォルトのワールド構成がリセットされます。

戻り値

Promise<void>

unregister()

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

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

パラメータ

フィルタ

UserScriptFilter 省略可

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

戻り値

Promise<void>

update()

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

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

パラメータ

スクリプト

RegisteredUserScript[]

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

戻り値

Promise<void>

chrome.userScripts コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

説明

権限

対象

コンセプトと使用方法

userScripts API の使用を有効にする

Chrome バージョン 138 より前（デベロッパー モードの切り替え）

Chrome バージョン 138 以降（[ユーザー スクリプトを許可] 切り替え）

API の可用性を確認する

分離された世界で作業する

メッセージ

拡張機能の更新

例

スクリプトを登録する

型

ExecutionWorld

列挙型

InjectionResult

プロパティ

InjectionTarget

プロパティ

RegisteredUserScript

プロパティ

ScriptSource

プロパティ

UserScriptFilter

プロパティ

UserScriptInjection

プロパティ

WorldProperties

プロパティ

メソッド

configureWorld()

パラメータ

戻り値

execute()

パラメータ

戻り値

getScripts()

パラメータ

戻り値

getWorldConfigurations()

戻り値

register()

パラメータ

戻り値

resetWorldConfiguration()

パラメータ

戻り値

unregister()

パラメータ

戻り値

update()

パラメータ

戻り値

chrome.userScripts

Chrome バージョン 138 より前（デベロッパーモードの切り替え）

Chrome バージョン 138 以降（[ユーザースクリプトを許可] 切り替え）