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 または挿入するターゲットを指定できます。 。

必須フィールドは 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 について詳しくは、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 の実行結果は拡張機能に渡されます。単一の結果 指定することもできます。メインフレームは、常に最初のインデックスとして 結果の配列;順序は非決定的になります。

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 は処理を待機します。 それを決済し、その結果を返すことを約束します。

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

    文字列 [] 省略可

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

CSSInjection

プロパティ

  • css

    文字列（省略可）

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

  • ファイル

    文字列 [] 省略可

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

  • オリジン

    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

    文字列 [] 省略可

    Chrome 106 以降

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

  • frameIds

    数値 [] 省略可

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

  • tabId

    数値

    挿入先のタブの ID。

RegisteredContentScript

Chrome 96 以降

プロパティ

  • allFrames

    ブール値（省略可）

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

  • css

    文字列 [] 省略可

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

  • excludeMatches

    文字列 [] 省略可

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

  • id

    文字列

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

  • JS

    文字列 [] 省略可

    一致するページに挿入される JavaScript ファイルのリスト。これらはこの配列に出現する順序で挿入されます。

  • matchOriginAsFallback

    ブール値（省略可）

    Chrome 119 以降

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

  • 一致

    文字列 [] 省略可

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

  • persistAcrossSessions

    ブール値（省略可）

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

  • runAt

    RunAt （省略可）

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

  • 世界

    ExecutionWorld （省略可）

    Chrome 102 以降

    JavaScript の「世界」指定します。デフォルトは ISOLATED です。

ScriptInjection

プロパティ

  • args

    any[] 省略可

    Chrome 92 以降

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

  • ファイル

    文字列 [] 省略可

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

  • injectImmediately

    ブール値（省略可）

    Chrome 102 以降

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

  • ターゲット

    InjectionTarget

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

  • 世界

    ExecutionWorld （省略可）

    Chrome 95 以降

    JavaScript の「世界」指定します。デフォルトは ISOLATED です。

  • func

    void（省略可）

    Chrome 92 以降

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

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

    () => {...}

StyleOrigin

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

列挙型

「AUTHOR」

「ユーザー」

メソッド

executeScript()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

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

パラメータ

  • インジェクション

    ScriptInjection

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

  • callback

    関数（省略可）

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

    (results: InjectionResult[]) => void

戻り値

  • Promise&lt;InjectionResult[]&gt;

    Chrome 90 以降

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

getRegisteredContentScripts()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 96 以降 をご覧ください。
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

パラメータ

戻り値

  • Promise&lt;RegisteredContentScript[]&gt;

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

insertCSS()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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

パラメータ

  • インジェクション

    CSSInjection

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 90 以降

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

registerContentScripts()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 96 以降 をご覧ください。
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

パラメータ

  • スクリプト

    RegisteredContentScript[]

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

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

removeCSS()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 90 以降 をご覧ください。
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

パラメータ

  • インジェクション

    CSSInjection

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

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

unregisterContentScripts()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 96 以降 をご覧ください。
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

パラメータ

  • フィルタ

    ContentScriptFilter 省略可

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

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

updateContentScripts()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 96 以降 をご覧ください。
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

パラメータ

  • スクリプト

    RegisteredContentScript[]

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

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