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"));

コードの挿入

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

ファイル

ファイルは、拡張機能のルート ディレクトリからの相対パスである文字列として指定します。次のコードは、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(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

    string（省略可）

    挿入する CSS を含む文字列です。files または css のいずれか 1 つのみを指定する必要があります。

  • ファイル

    string[] 省略可

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

  • 出所

    StyleOrigin 省略可

    インジェクションのスタイルの起点。デフォルトは 'AUTHOR' です。

  • ターゲット

    InjectionTarget

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

ExecutionWorld

Chrome 95 以降

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

Enum

"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 以降

    サポートされていないスキーム（about:、data:、blob:、filesystem:）が URL に含まれているフレームにスクリプトを挿入できるかどうかを示します。このような場合は、URL の生成元を確認して、スクリプトを挿入する必要があるかどうかを判断します。オリジンが null の場合（data: URL の場合と同様）、使用されるオリジンは、現在のフレームを作成したフレームか、このフレームへのナビゲーションを開始したフレームです。なお、これは親フレームではない可能性があります。

  • 一致

    string[] 省略可

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

  • persistAcrossSessions

    ブール値（省略可）

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

  • runAt

    RunAt（省略可）

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

  • 世界

    ExecutionWorld 省略可

    Chrome 102 以降

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

ScriptInjection

プロパティ

  • args

    any[] 省略可

    Chrome 92 以降

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

  • ファイル

    string[] 省略可

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

  • injectImmediately

    ブール値（省略可）

    Chrome 102 以降

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

  • ターゲット

    InjectionTarget

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

  • 世界

    ExecutionWorld 省略可

    Chrome 95 以降

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

  • func

    void 省略可

    Chrome 92 以降

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

    func 関数は次のようになります。 

    ()=> {...}

StyleOrigin

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

Enum

Methods

executeScript()

Promise 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

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

パラメータ

  • インジェクション

    ScriptInjection

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

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (results: InjectionResult[])=>void

戻り値

  • Promise<InjectionResult[]>

    Chrome 90 以降

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

getRegisteredContentScripts()

Promise Chrome 96 以降 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

パラメータ

戻り値

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

insertCSS()

Promise 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

パラメータ

  • インジェクション

    CSSInjection

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

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

    Chrome 90 以降

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

registerContentScripts()

Promise Chrome 96 以降 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

パラメータ

  • スクリプト

    RegisteredContentScript[]

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

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

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

removeCSS()

Promise Chrome 90 以降 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

パラメータ

  • インジェクション

    CSSInjection

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

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

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

unregisterContentScripts()

Promise Chrome 96 以降 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

パラメータ

  • フィルタ

    ContentScriptFilter 省略可

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

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

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

updateContentScripts()

Promise Chrome 96 以降 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

パラメータ

  • スクリプト

    RegisteredContentScript[]

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

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    ()=>void

戻り値

  • Promise<void>

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