chrome.devtools.inspectedWindow

説明

chrome.devtools.inspectedWindow API を使用して検査対象ウィンドウを操作します。検査対象ページのタブ ID の取得、検査対象ウィンドウのコンテキストでコードの評価、ページの再読み込み、ページ内のリソースのリストの取得を行います。

Developer Tools API の一般的な概要については、DevTools API の概要をご覧ください。

tabId プロパティは、chrome.tabs.* API 呼び出しで使用できるタブ識別子を提供します。ただし、セキュリティ上の考慮事項により、chrome.tabs.* API はデベロッパー ツール拡張ページには公開されません。タブ ID をバックグラウンド ページに渡し、そこから chrome.tabs.* API 関数を呼び出す必要があります。

reload メソッドを使用して、検査対象のページを再読み込みできます。また、呼び出し元は、ユーザー エージェント文字列のオーバーライド、ページ読み込みの早い段階で挿入されるスクリプト、キャッシュされたリソースの再読み込みを強制するオプションを指定できます。

getResources 呼び出しと onResourceContent イベントを使用して、検査対象ページ内のリソース（ドキュメント、スタイルシート、スクリプト、画像など）のリストを取得します。Resource クラスの getContent メソッドと setContent メソッドを onResourceContentCommitted イベントとともに使用して、外部エディタなどによるリソース コンテンツの変更をサポートできます。

マニフェスト

この API を使用するには、次のキーをマニフェストで宣言する必要があります。

"devtools_page"

検査対象のウィンドウでコードを実行する

eval メソッドを使用すると、拡張機能は検査対象のページのコンテキストで JavaScript コードを実行できます。この方法は、適切なコンテキストで使用すれば強力で、不適切に使用すると危険です。eval メソッドが提供する特定の機能が必要な場合を除き、tabs.executeScript メソッドを使用します。

eval メソッドと tabs.executeScript メソッドの主な違いは次のとおりです。

  • eval メソッドは、評価対象のコードに隔離された環境を使用しないため、コードは検査対象ウィンドウの JavaScript の状態にアクセスできます。検査対象のページの JavaScript 状態にアクセスする必要がある場合は、このメソッドを使用します。
  • 評価されるコードの実行コンテキストには、Developer Tools Console API が含まれます。たとえば、このコードでは inspect と $0 を使用できます。
  • 評価されたコードは、拡張機能のコールバックに渡される値を返す場合があります。戻り値は有効な JSON オブジェクトである必要があります（含まれるのは、プリミティブ JavaScript 型と、他の JSON オブジェクトへの非巡回参照のみです）。検査対象のページから受け取ったデータを処理する際は特に注意してください。実行コンテキストは基本的に検査対象のページによって制御されるため、悪意のあるページは拡張機能に返されるデータに影響する可能性があります。

1 つのページに複数の JavaScript 実行コンテキストが含まれる場合があります。各フレームには独自のコンテキストと、そのフレームでコンテンツ スクリプトを実行している拡張機能ごとに追加のコンテキストがあります。

デフォルトでは、eval メソッドは検査対象ページのメインフレームのコンテキストで実行されます。

eval メソッドは、オプションとして 2 番目の引数を取ります。これを使用すると、コードを評価するコンテキストを指定できます。この options オブジェクトには、以下のキーを 1 つ以上含めることができます。

frameURL
検査対象ページのメインフレーム以外のフレームを指定するために使用します。
contextSecurityOrigin
ウェブオリジンに従って、指定されたフレーム内のコンテキストを選択するために使用します。
useContentScriptContext
true の場合、拡張機能のコンテンツ スクリプトと同じコンテキストでスクリプトを実行します。（拡張機能独自のウェブ組織をコンテキスト セキュリティ オリジンとして指定する場合と同じです）。これは、コンテンツ スクリプトとデータを交換するために使用できます。

例

次のコードは、検査対象のページで使用されている jQuery のバージョンを確認します。

chrome.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

この API を試すには、chrome-extension-samples リポジトリから devtools API の例をインストールします。

型

Resource

検査対象のページ内のリソース（ドキュメント、スクリプト、画像など）。

プロパティ

  • URL

    文字列

    リソースの URL。

  • getContent

    void

    リソースのコンテンツを取得します。

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

    (callback: function)=> {...}

    • callback

      機能

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

      (content: string,encoding: string)=>void

      • を積極的に紹介

        文字列

        リソースのコンテンツ（エンコードされている可能性あり）。

      • encoding

        文字列

        コンテンツがエンコードされていない場合は空になり、エンコードされていない場合はエンコード名になります。現在サポートされているのは base64 のみです。

  • setContent

    void

    リソースの内容を設定します。

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

    (content: string,commit: boolean,callback?: function)=> {...}

    • を積極的に紹介

      文字列

      リソースの新しいコンテンツ。現在サポートされているのは、テキストタイプのリソースのみです。

    • commit

      boolean

      ユーザーがリソースの編集を完了し、リソースの新しいコンテンツを保持する必要がある場合は true、ユーザーがリソースを編集中に送信された軽微な変更の場合は false に設定します。

    • callback

      関数（省略可）

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

      (error?: object)=>void

      • error

        オブジェクト 省略可

        リソース コンテンツが正常に設定された場合は未定義に設定されます。それ以外の場合は、エラーを示します。

プロパティ

tabId

検査対象のタブの ID。この ID は chrome.tabs.* で使用できます。API.

タイプ

数値

Methods

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
)

JavaScript 式を、検査対象ページのメインフレームのコンテキストで評価します。式は、JSON 準拠のオブジェクトと評価される必要があります。そうでない場合、例外がスローされます。eval 関数は、評価中に発生した DevTools 側のエラーまたは JavaScript 例外をレポートできます。いずれの場合も、コールバックの result パラメータは undefined です。DevTools 側のエラーの場合、isException パラメータは null ではなく、isError が true に、code がエラーコードに設定されます。JavaScript エラーが発生した場合、isException は true に設定され、value はスローされたオブジェクトの文字列値に設定されます。

パラメータ

  • 式

    文字列

    評価する式。

  • オプション

    オブジェクト 省略可

    オプション パラメータには 1 つ以上のオプションを含めることができます。

    • frameURL

      string（省略可）

      指定すると、指定した URL と URL が一致する iframe で式が評価されます。デフォルトでは、式は検査対象ページのトップフレームで評価されます。

    • scriptExecutionContext

      string（省略可）

      Chrome 107 以降

      指定したオリジンに一致する拡張機能のコンテンツ スクリプトのコンテキストで式を評価します。指定した場合、scriptExecutionContext は useContentScriptContext の「true」設定をオーバーライドします。

    • useContentScriptContext

      ブール値（省略可）

      検査対象のページにコンテンツ スクリプトがすでに挿入されている場合は、呼び出し元の拡張機能のコンテンツ スクリプトのコンテキストで式を評価します。それ以外の場合、式は評価されず、isError フィールドが true に設定され、code フィールドが E_NOTFOUND に設定されているオブジェクトに例外パラメータが設定され、コールバックが呼び出されます。

  • callback

    関数（省略可）

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

    (result: object,exceptionInfo: object)=>void

    • 件の結果

      オブジェクト

      評価の結果。

    • exceptionInfo

      オブジェクト

      式の評価中に例外が発生した場合の詳細を提供するオブジェクト。

      • コード

        文字列

        式が評価される前に DevTools 側でエラーが発生した場合に設定します。

      • description

        文字列

        式が評価される前に DevTools 側でエラーが発生した場合に設定します。

      • 詳細

        任意 []

        式が評価される前に DevTools 側でエラーが発生した場合に設定され、エラーの原因に関する詳細情報を提供するために description の文字列に代入できる値の配列を含みます。

      • isError

        boolean

        式が評価される前に DevTools 側でエラーが発生した場合に設定します。

      • isException

        boolean

        評価されたコードが処理できない例外を生成する場合に設定します。

      • value

        文字列

        評価されたコードが処理できない例外を生成する場合に設定します。

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
)

検査対象のページからリソースのリストを取得します。

パラメータ

  • callback

    機能

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

    (resources: Resource[])=>void

    • リソース

      リソース[]

      ページ内のリソース。

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
)

検査対象のページを再読み込みします。

パラメータ

  • reloadOptions

    オブジェクト 省略可

    • ignoreCache

      ブール値（省略可）

      true の場合、ローダは、load イベントが発生する前に読み込まれた検査対象ページリソースすべてについて、キャッシュをバイパスします。この効果は、検査対象のウィンドウまたはデベロッパー ツール ウィンドウで Ctrl+Shift+R キーを押す場合と類似しています。

    • injectedScript

      string（省略可）

      指定すると、検査対象ページのすべてのフレームで、読み込み直後に、フレームのスクリプトよりも前にスクリプトが挿入されます。スクリプトは、ユーザーが Ctrl+R を押した場合など、その後の再読み込みでは挿入されません。

    • userAgent

      string（省略可）

      指定すると、この文字列によって、検査対象のページのリソースの読み込み中に送信される User-Agent HTTP ヘッダーの値がオーバーライドされます。この文字列は、検査対象のページ内で実行中のスクリプトに返される navigator.userAgent プロパティの値をオーバーライドします。

イベント

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

検査対象のページに新しいリソースが追加されると呼び出されます。

パラメータ

  • callback

    機能

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

    (resource: Resource)=>void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

リソースの新しいリビジョンが commit されたときに呼び出されます（ユーザーがリソースの編集済みのバージョンをデベロッパー ツールに保存した場合など）。

パラメータ

  • callback

    機能

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

    (resource: Resource,content: string)=>void