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

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

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

<ph type="x-smartling-placeholder">
</ph> 拡張機能ページ（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() の基本的な呼び出しを示しています。最初の引数は、登録するスクリプトを定義するオブジェクトの配列です。ここに示されている以外にも多くのオプションがあります。

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

型

ExecutionWorld

ユーザースクリプトを内部で実行する JavaScript 環境。

列挙型

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

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

RegisteredUserScript

プロパティ

allFrames

ブール値（省略可）

true の場合、タブの最上位フレームでなくても、すべてのフレームに挿入されます。各フレームは個別に URL 要件の確認が行われます。URL の要件を満たしていない場合、子フレームには挿入されません。デフォルトは false で、トップフレームのみが一致します。
excludeGlobs

文字列 [] 省略可

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

文字列 [] 省略可

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

文字列

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

文字列 [] 省略可

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

ScriptSource[]

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

文字列 [] 省略可

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

RunAt （省略可）

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

ExecutionWorld （省略可）

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

ScriptSource

プロパティ

コード

文字列（省略可）

挿入する JavaScript コードを含む文字列。file または code のいずれかを指定する必要があります。
あなた宛てに表示されます。

文字列（省略可）

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

UserScriptFilter

プロパティ

ids

文字列 [] 省略可

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

WorldProperties

プロパティ

CSP

文字列（省略可）

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

ブール値（省略可）

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

メソッド

configureWorld()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

プロパティ

WorldProperties

ユーザースクリプトの世界設定が含まれています。
callback

関数（省略可）

callback パラメータは次のようになります。
```
() => void
```

戻り値

約束 <void>

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

getScripts()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

フィルタ

UserScriptFilter 省略可

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

関数（省略可）

callback パラメータは次のようになります。
```
(scripts: RegisteredUserScript[]) => void
```
- スクリプト
  
  RegisteredUserScript[]

戻り値

Promise<RegisteredUserScript[]>

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

register()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

スクリプト

RegisteredUserScript[]

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

関数（省略可）

callback パラメータは次のようになります。
```
() => void
```

戻り値

約束 <void>

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

unregister()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

フィルタ

UserScriptFilter 省略可

指定すると、一致するユーザースクリプトのみが登録解除されます。
callback

関数（省略可）

callback パラメータは次のようになります。
```
() => void
```

戻り値

約束 <void>

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

update()

<ph type="x-smartling-placeholder"></ph> 約束

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

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

パラメータ

スクリプト

RegisteredUserScript[]

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

関数（省略可）

callback パラメータは次のようになります。
```
() => void
```

戻り値

約束 <void>

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

chrome.userScripts

説明

権限

可用性

コンセプトと使用方法

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

隔離された環境で作業する

メッセージ

拡張機能の更新

例

スクリプトを登録する

型

ExecutionWorld

列挙型

RegisteredUserScript

プロパティ

ScriptSource

プロパティ

UserScriptFilter

プロパティ

WorldProperties

プロパティ

メソッド

configureWorld()

パラメータ

戻り値

getScripts()

パラメータ

戻り値

register()

パラメータ

戻り値

unregister()

パラメータ

戻り値

update()

パラメータ

戻り値

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