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

chrome.scripting

説明

chrome.scripting API を使用して、さまざまなコンテキストでスクリプトを実行します。

権限

scripting

対象

Chrome 88 以降 MV3 以降

マニフェスト

chrome.scripting API を使用するには、マニフェストで "scripting" 権限と、スクリプトを挿入するページのホスト権限を宣言します。"host_permissions" キーまたは "activeTab" 権限を使用します。これにより、一時的なホスト権限が付与されます。次の例では、activeTab 権限を使用しています。

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

コンセプトと使用方法

chrome.scripting API を使用して、ウェブサイトに JavaScript と CSS を挿入できます。これは、コンテンツスクリプトでできることと似ています。ただし、chrome.scripting 名前空間を使用すると、拡張機能は実行時に決定を行うことができます。

インジェクションターゲット

target パラメータを使用して、JavaScript または CSS を挿入するターゲットを指定できます。

必須フィールドは tabId のみです。デフォルトでは、インジェクションは指定されたタブのメインフレームで実行されます。

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

指定したタブのすべてのフレームで実行するには、allFrames ブール値を true に設定します。

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

個々のフレーム ID を指定して、タブの特定のフレームに挿入することもできます。フレーム ID の詳細については、chrome.webNavigation API をご覧ください。

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

注: "frameIds" プロパティと "allFrames" プロパティの両方を指定することはできません。

注入されたコード

拡張機能は、外部ファイルまたはランタイム変数を使用して、挿入するコードを指定できます。

ファイル

ファイルは、拡張機能のルートディレクトリからの相対パスである文字列として指定されます。次のコードは、ファイル script.js をタブのメインフレームに挿入します。

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

ランタイム関数

scripting.executeScript() で JavaScript を挿入するときに、ファイルではなく実行する関数を指定できます。この関数は、現在の拡張機能コンテキストで使用可能な関数変数である必要があります。

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

この問題を回避するには、args プロパティを使用します。

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

ランタイム文字列

ページ内で CSS を挿入する場合は、css プロパティで使用する文字列を指定することもできます。このオプションは scripting.insertCSS() でのみ使用できます。scripting.executeScript() を使用して文字列を実行することはできません。

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

結果を処理する

JavaScript の実行結果が拡張機能に渡されます。フレームごとに 1 つの結果が含まれます。メインフレームは結果の配列の最初のインデックスであることが保証されます。他のすべてのフレームは非決定論的な順序になります。

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() は結果を返しません。

Promise

スクリプト実行の結果の値が Promise の場合、Chrome は Promise が確定するまで待機し、結果の値を返します。

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

例

すべての動的コンテンツスクリプトの登録を解除する

次のスニペットには、拡張機能が以前に登録したすべての動的コンテンツスクリプトの登録を解除する関数が含まれています。

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

chrome.scripting API を試すには、Chrome 拡張機能のサンプルリポジトリからスクリプトサンプルをインストールします。

型

ContentScriptFilter

Chrome 96 以降

プロパティ

ids

string[] 省略可

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

CSSInjection

プロパティ

css

文字列省略可

挿入する CSS を含む文字列。files と css のいずれか 1 つを指定する必要があります。
ファイル

string[] 省略可

挿入する CSS ファイルのパス。拡張機能のルートディレクトリを基準とする相対パスです。files と css のいずれか 1 つを指定する必要があります。
origin

StyleOrigin 省略可

挿入のスタイル生成元。デフォルトは 'AUTHOR' です。
ターゲット

InjectionTarget

CSS を挿入するターゲットを指定する詳細。

ExecutionWorld

Chrome 95 以降

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

列挙型

「ISOLATED」
この拡張機能に固有の実行環境である分離されたワールドを指定します。

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

InjectionResult

プロパティ

documentId

文字列

Chrome 106 以降

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

数値

Chrome 90 以降

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

任意の省略可

スクリプト実行の結果。

InjectionTarget

プロパティ

allFrames

ブール値（省略可）

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

string[] 省略可

Chrome 106 以降

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

number[] 省略可

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

数値

挿入先のタブの ID。

RegisteredContentScript

Chrome 96 以降

プロパティ

allFrames

ブール値（省略可）

true を指定すると、タブの最上位のフレームでなくても、すべてのフレームに挿入されます。各フレームは URL 要件について個別にチェックされます。URL 要件が満たされていない場合、子フレームに挿入されることはありません。デフォルトは false で、最上位のフレームのみが一致します。
css

string[] 省略可

一致するページに挿入する CSS ファイルのリスト。これらは、この配列に表示される順に、ページの DOM が構築または表示される前に挿入されます。
excludeMatches

string[] 省略可

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

文字列

API 呼び出しで指定されたコンテンツスクリプトの ID。生成されたスクリプト ID の接頭辞として予約されているため、先頭に「_」を使用することはできません。
js

string[] 省略可

一致するページに挿入される JavaScript ファイルのリスト。これらは、この配列に表示されている順序で挿入されます。
matchOriginAsFallback

ブール値（省略可）

Chrome 119 以降

URL にサポートされていないスキーム（about:、data:、blob:、filesystem: など）が含まれるフレームにスクリプトを挿入できるかどうかを示します。このような場合、URL のオリジンがチェックされ、スクリプトを挿入するかどうかが判断されます。オリジンが null の場合（data: URL の場合など）、使用されるオリジンは、現在のフレームを作成したフレームか、このフレームへのナビゲーションを開始したフレームのいずれかです。これは親フレームではない場合があります。
一致

string[] 省略可

このコンテンツスクリプトが挿入されるページを指定します。これらの文字列の構文の詳細については、一致パターンをご覧ください。registerContentScripts で指定する必要があります。
persistAcrossSessions

ブール値（省略可）

このコンテンツスクリプトが今後のセッションでも保持されるかどうかを指定します。デフォルトは true です。
runAt

RunAt 省略可

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

ExecutionWorld 省略可

Chrome 102 以降

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

ScriptInjection

プロパティ

args

any[] 省略可

Chrome 92 以降

指定された関数に渡す引数。これは、func パラメータが指定されている場合にのみ有効です。これらの引数は JSON シリアル化可能である必要があります。
ファイル

string[] 省略可

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

ブール値（省略可）

Chrome 102 以降

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

InjectionTarget

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

ExecutionWorld 省略可

Chrome 95 以降

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

void optional

Chrome 92 以降

挿入する JavaScript 関数。この関数はシリアル化され、挿入のために逆シリアル化されます。つまり、バインドされたパラメータと実行コンテキストはすべて失われます。files または func のいずれか 1 つを指定する必要があります。

func 関数は次のようになります。
```
() => {...}
```

StyleOrigin

スタイル変更の発生元。詳しくは、スタイルのオリジンをご覧ください。

列挙型

"AUTHOR"

"USER"

メソッド

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

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

パラメータ

インジェクション

ScriptInjection

挿入するスクリプトの詳細。

戻り値

Promise<InjectionResult[]>

Chrome 90 以降

getRegisteredContentScripts()

Chrome 96 以降

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

指定されたフィルタに一致する、この拡張機能の動的に登録されたすべてのコンテンツスクリプトを返します。

パラメータ

フィルタ

ContentScriptFilter 省略可

拡張機能の動的に登録されたスクリプトをフィルタするオブジェクト。

戻り値

Promise<RegisteredContentScript[]>

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

CSS スタイルシートをターゲットコンテキストに挿入します。複数のフレームが指定されている場合、挿入に失敗したフレームは無視されます。

パラメータ

インジェクション

CSSInjection

挿入するスタイルの詳細。

戻り値

Promise<void>

Chrome 90 以降

registerContentScripts()

Chrome 96 以降

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

この拡張機能の 1 つ以上のコンテンツスクリプトを登録します。

パラメータ

スクリプト

RegisteredContentScript[]

登録するスクリプトのリストが含まれます。スクリプトの解析/ファイルの検証中にエラーが発生した場合、または指定された ID がすでに存在する場合は、スクリプトは登録されません。

戻り値

Promise<void>

removeCSS()

Chrome 90 以降

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

この拡張機能によって以前に挿入された CSS スタイルシートを、ターゲットコンテキストから削除します。

パラメータ

インジェクション

CSSInjection

削除するスタイルの詳細。css、files、origin プロパティは、insertCSS を介して挿入されたスタイルシートと完全に一致している必要があります。存在しないスタイルシートを削除しようとしても、何も起こりません。

戻り値

Promise<void>

unregisterContentScripts()

Chrome 96 以降

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

この拡張機能のコンテンツスクリプトの登録を解除します。

パラメータ

フィルタ

ContentScriptFilter 省略可

指定した場合、フィルタに一致する動的コンテンツスクリプトのみを登録解除します。それ以外の場合は、拡張機能の動的コンテンツスクリプトがすべて登録解除されます。

戻り値

Promise<void>

updateContentScripts()

Chrome 96 以降

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

この拡張機能の 1 つ以上のコンテンツスクリプトを更新します。

パラメータ

スクリプト

RegisteredContentScript[]

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

戻り値

Promise<void>

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

説明

権限

対象

マニフェスト

コンセプトと使用方法

インジェクション ターゲット

注入されたコード

ファイル

ランタイム関数

ランタイム文字列

結果を処理する

Promise

例

すべての動的コンテンツ スクリプトの登録を解除する

型

ContentScriptFilter

プロパティ

CSSInjection

プロパティ

ExecutionWorld

列挙型

InjectionResult

プロパティ

InjectionTarget

プロパティ

RegisteredContentScript

プロパティ

ScriptInjection

プロパティ

StyleOrigin

列挙型

メソッド

executeScript()

パラメータ

戻り値

getRegisteredContentScripts()

パラメータ

戻り値

insertCSS()

パラメータ

戻り値

registerContentScripts()

パラメータ

戻り値

removeCSS()

パラメータ

戻り値

unregisterContentScripts()

パラメータ

戻り値

updateContentScripts()

パラメータ

戻り値

chrome.scripting

インジェクションターゲット

すべての動的コンテンツスクリプトの登録を解除する