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. [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

    文字列 [] 省略可

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

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

戻り値

  • Promise&lt;RegisteredUserScript[]&gt;

    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 はコールバックに渡された型と同じ型で解決されます。