Chrome で標準化された browser.* 名前空間がサポートされるようになりました（Chrome 148 以降で利用可能）。ドキュメントは順次更新されます。詳しくは、移行ガイドをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

browser.userScripts

説明

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

権限

userScripts

ユーザースクリプト API を使用するには、browser.userScripts、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 以降 Chrome 148 以降の browser.* MV3 以降

コンセプトと使用方法

ユーザースクリプトとは、ウェブページに挿入してその外観や動作を変更するコードスニペットです。コンテンツスクリプトや browser.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 の可用性を確認する

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

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

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

ユーザースクリプトとコンテンツスクリプトは、どちらも分離されたワールドまたはメインワールドで実行できます。分離されたワールドは、ホストページや他の拡張機能からアクセスできない実行環境です。これにより、ユーザースクリプトは、ホストページや他の拡張機能のユーザースクリプトやコンテンツスクリプトに影響を与えることなく、JavaScript 環境を変更できます。逆に、ユーザースクリプト（およびコンテンツスクリプト）は、ホストページや他の拡張機能のユーザースクリプトおよびコンテンツスクリプトには表示されません。メインワールドで実行されているスクリプトは、ホストページや他の拡張機能からアクセスでき、ホストページや他の拡張機能から参照できます。ワールドを選択するには、userScripts.register() を呼び出すときに "USER_SCRIPT" または "MAIN" を渡します。

USER_SCRIPT ワールドのコンテンツセキュリティポリシーを構成するには、userScripts.configureWorld() を呼び出します。

browser.userScripts.configureWorld({
  csp: "script-src 'self'"
});

メッセージ

コンテンツスクリプトやオフスクリーンドキュメントと同様に、ユーザースクリプトはメッセージングを使用して拡張機能の他の部分と通信します（つまり、拡張機能の他の部分と同様に runtime.sendMessage() と runtime.connect() を呼び出すことができます）。ただし、これらは専用のイベントハンドラを使用して受信されます（つまり、onMessage や onConnect は使用されません）。これらのハンドラは runtime.onUserScriptMessage と runtime.onUserScriptConnect と呼ばれます。専用のハンドラを使用すると、信頼性の低いコンテキストであるユーザースクリプトからのメッセージを簡単に識別できます。

メッセージを送信する前に、messaging 引数を true に設定して configureWorld() を呼び出す必要があります。csp 引数と messaging 引数の両方を同時に渡すことができます。

browser.userScripts.configureWorld({
  messaging: true
});

拡張機能の更新

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

例

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

スクリプトを登録する

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

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

型

ExecutionWorld

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

列挙型

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

"USER_SCRIPT"
ユーザースクリプトに固有で、ページの CSP から除外される実行環境を指定します。

InjectionResult

Chrome 135 以降 Chrome 148 以降の browser.*

プロパティ

documentId

文字列

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

文字列省略可

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

数値

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

any 省略可

スクリプトの実行結果。

InjectionTarget

Chrome 135 以降 Chrome 148 以降の browser.*

プロパティ

allFrames

boolean 省略可

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

string[] 省略可

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

number[] 省略可

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

数値

挿入先のタブの ID。

RegisteredUserScript

プロパティ

allFrames

boolean 省略可

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 以降 Chrome 148 以降の browser.*

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

ScriptSource

プロパティ

コード

文字列省略可

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

文字列省略可

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

UserScriptFilter

プロパティ

ids

string[] 省略可

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

UserScriptInjection

Chrome 135 以降 Chrome 148 以降の browser.*

プロパティ

injectImmediately

boolean 省略可

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

ScriptSource[]

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

InjectionTarget

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

ExecutionWorld 省略可

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

文字列省略可

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

WorldProperties

プロパティ

csp

文字列省略可

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

boolean 省略可

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

文字列省略可

Chrome 133 以降 Chrome 148 以降の browser.*

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

メソッド

configureWorld()

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

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

パラメータ

プロパティ

WorldProperties

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

戻り値

Promise<void>

ワールドが構成されると解決される Promise。

execute()

Chrome 135 以降 Chrome 148 以降の browser.*

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

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

パラメータ

インジェクション

UserScriptInjection

戻り値

Promise<InjectionResult[]>

getScripts()

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

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

パラメータ

filter

UserScriptFilter 省略可

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

戻り値

Promise<RegisteredUserScript[]>

登録済みのスクリプトで解決される Promise。エラーが発生すると、Promise は拒否されます。

getWorldConfigurations()

Chrome 133 以降 Chrome 148 以降の browser.*

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

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

戻り値

Promise<WorldProperties[]>

登録済みのワールド構成で解決される Promise。

register()

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

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

パラメータ

スクリプト

RegisteredUserScript[]

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

戻り値

Promise<void>

スクリプトが完全に登録されると解決される Promise。エラーが発生すると、Promise は拒否されます。

resetWorldConfiguration()

Chrome 133 以降 Chrome 148 以降の browser.*

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

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

パラメータ

worldId

文字列省略可

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

戻り値

Promise<void>

構成がリセットされると解決される Promise。

unregister()

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

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

パラメータ

filter

UserScriptFilter 省略可

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

戻り値

Promise<void>

スクリプトの登録解除が完了すると解決される Promise。エラーが発生すると、Promise は拒否されます。

update()

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

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

パラメータ

スクリプト

RegisteredUserScript[]

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

戻り値

Promise<void>

スクリプトが完全に更新されると解決される Promise。エラーが発生すると、Promise は拒否されます。

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

説明

権限

対象

コンセプトと使用方法

userScripts API の使用を有効にする

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

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

API の可用性を確認する

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

メッセージ

拡張機能の更新

例

スクリプトを登録する

型

ExecutionWorld

列挙型

InjectionResult

プロパティ

InjectionTarget

プロパティ

RegisteredUserScript

プロパティ

ScriptSource

プロパティ

UserScriptFilter

プロパティ

UserScriptInjection

プロパティ

WorldProperties

プロパティ

メソッド

configureWorld()

パラメータ

戻り値

execute()

パラメータ

戻り値

getScripts()

パラメータ

戻り値

getWorldConfigurations()

戻り値

register()

パラメータ

戻り値

resetWorldConfiguration()

パラメータ

戻り値

unregister()

パラメータ

戻り値

update()

パラメータ

戻り値

browser.userScripts

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