chrome.debugger

説明

chrome.debugger API は、Chrome のリモート デバッグ プロトコルの代替トランスポートとして機能します。chrome.debugger を使用して 1 つ以上のタブにアタッチし、ネットワーク インタラクションの測定、JavaScript のデバッグ、DOM と CSS の変更などを行います。Debuggee プロパティの tabId を使用して、sendCommand でタブをターゲットにし、onEvent コールバックからの tabId でイベントをルーティングします。

権限

debugger

この API を使用するには、拡張機能のマニフェストで "debugger" 権限を宣言する必要があります。

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

コンセプトと使用方法

接続すると、chrome.debugger API を使用して Chrome DevTools Protocol を送信できます。 （CDP）コマンドを特定のターゲットに追加します。CDP の詳細な説明はサポート範囲外 をご覧ください。CDP の詳細については、 公式 CDP ドキュメントをご覧ください。

ターゲット

ターゲットはデバッグ中の内容を表します。たとえば、タブ、 アップロードできます各ターゲットは UUID で識別され、関連付けられた （iframe、shared_worker など）。

ターゲット内には、同じものなど、複数の実行コンテキストが存在する場合があります。 プロセスの iframe には固有のターゲットは設定されず、代わりに 1 つのターゲットからアクセスできる さまざまなコンテキストに分けられます

制限付きドメイン

セキュリティ上の理由から、chrome.debugger API では一部の Chrome DevTools にはアクセスできません。 学びます。利用可能なドメインは、ユーザー補助、 監査、CacheStorage、コンソール、 CSS、Database、Debugger、DOM、 DOMDebugger、DOMSnapshot、 エミュレーション、取得、IO、入力、 インスペクタ、ログ、ネットワーク、オーバーレイ ページ、パフォーマンス、プロファイラ、 ランタイム、ストレージ、ターゲット、トレース、 WebAudio、WebAuthn。

フレームを操作する

フレームとターゲットの 1 対 1 のマッピングはありません。1 つのタブで 複数の同じプロセス フレームが同じターゲットを共有し、異なる 実行コンテキスト。一方、新たな標的となるのは プロセス外の iframe 用に作成されました

すべてのフレームにアタッチするには、各タイプのフレームを個別に処理する必要があります。

  • Runtime.executionContextCreated イベントをリッスンして、新しいイベントを識別する 同じプロセス フレームに関連付けられた実行コンテキストを分類することはできません。

  • 関連するターゲットにアタッチする手順に沿って、以下を行います。 プロセス外のフレームの特定に役立ちます

ターゲットに接続した後で、さらに関連するターゲットに接続できます プロセス外の子フレームや関連ワーカーなどを含みます

Chrome 125 以降では、chrome.debugger API でフラット セッションがサポートされます。この を使用すると、子としてターゲットをメインのデバッガ セッションに追加できます。 もう一度 chrome.debugger.attach に電話をかけずにメッセージを送信できます。代わりに chrome.debugger.sendCommand を呼び出すときに sessionId プロパティを追加して、 コマンドを送信する子ターゲットを特定します。

プロセス外の子フレームに自動的にアタッチするには、まず、 Target.attachedToTarget イベントを使用します。

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

次に、次のように Target.setAutoAttach コマンドを送信して自動アタッチを有効にします。 flatten オプションを true に設定した場合:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

例

この API を試すには、chrome-extension-samples からデバッガ API の例をインストールしてください。 できます。

型

Debuggee

デバッグ対象の識別子。tabId、extensionId、targetId のいずれかを指定する必要があります

プロパティ

  • extensionId

    文字列（省略可）

    デバッグする拡張機能の ID。拡張機能の背景ページへの接続は、--silent-debugger-extension-api コマンドライン スイッチを使用している場合にのみ可能です。

  • tabId

    数値（省略可）

    デバッグするタブの ID。

  • targetId

    文字列（省略可）

    デバッグ ターゲットの不透明な ID。

DebuggerSession

Chrome 125 以降

デバッガ セッション ID。tabId、extensionId、targetId のいずれかを指定する必要があります。また、オプションの sessionId を指定することもできます。onEvent から送信された引数に sessionId が指定されている場合、イベントはルート デバッグ対象セッション内の子プロトコル セッションから送信されていることを意味します。sendCommand に渡されるときに sessionId を指定すると、ルート デバッグ対象セッション内の子プロトコル セッションがターゲットになります。

プロパティ

  • extensionId

    文字列（省略可）

    デバッグする拡張機能の ID。拡張機能の背景ページへの接続は、--silent-debugger-extension-api コマンドライン スイッチを使用している場合にのみ可能です。

  • sessionId

    文字列（省略可）

    Chrome DevTools プロトコル セッションの不透明な ID。tabId、extensionId、targetId のいずれかで識別されるルート セッション内の子セッションを識別します。

  • tabId

    数値（省略可）

    デバッグするタブの ID。

  • targetId

    文字列（省略可）

    デバッグ ターゲットの不透明な ID。

DetachReason

Chrome 44 以降

接続終了の理由。

列挙型

"target_closed"

"canceled_by_user"

TargetInfo

デバッグ ターゲット情報

プロパティ

  • 接続済み

    ブール値

    デバッガがすでにアタッチされている場合は true。

  • extensionId

    文字列（省略可）

    type = 'background_page' の場合に定義される拡張機能の ID。

  • faviconUrl

    文字列（省略可）

    対象のファビコンの URL。

  • id

    文字列

    ターゲット ID。

  • tabId

    数値（省略可）

    type == 'page' の場合に定義されるタブ ID。

  • title

    文字列

    ターゲット ページのタイトル。

  • ターゲット タイプ。

  • URL

    文字列

    ターゲット URL。

TargetInfoType

Chrome 44 以降

ターゲット タイプ。

列挙型

"ページ"

"background_page"

"worker"

「その他」

メソッド

attach()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

指定されたターゲットにデバッガをアタッチします。

パラメータ

  • ターゲット

    デバッグ対象

    アタッチするデバッグ ターゲット。

  • requiredVersion

    文字列

    必要なデバッグ プロトコル バージョン（「0.1」）。一致するメジャー バージョン以上およびマイナー バージョン以上のデバッグ対象にのみアタッチできます。プロトコル バージョンのリストはこちらで確認できます。

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

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

detach()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

指定されたターゲットからデバッガを切断します。

パラメータ

  • ターゲット

    デバッグ対象

    切断するデバッグ ターゲット。

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

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

getTargets()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.debugger.getTargets(
  callback?: function,
)

使用可能なデバッグ ターゲットのリストを返します。

パラメータ

  • callback

    関数（省略可）

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

    (result: TargetInfo[]) => void

    • 件の結果

      TargetInfo[]

      使用可能なデバッグ ターゲットに対応する TargetInfo オブジェクトの配列。

戻り値

  • Promise&lt;TargetInfo[]&gt;

    Chrome 96 以降

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

sendCommand()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

指定されたコマンドをデバッグ ターゲットに送信します。

パラメータ

  • ターゲット

    DebuggerSession

    コマンドの送信先にするデバッグ ターゲット。

  • method

    文字列

    メソッド名。リモート デバッグ プロトコルで定義されたメソッドのいずれかを指定する必要があります。

  • commandParams

    オブジェクト（省略可）

    リクエスト パラメータを含む JSON オブジェクト。このオブジェクトは、指定されたメソッドのリモート デバッグ パラメータ スキームに準拠している必要があります。

  • callback

    関数（省略可）

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

    (result?: object) => void

    • 件の結果

      オブジェクト（省略可）

      レスポンスを含む JSON オブジェクト。レスポンスの構造はメソッド名によって異なり、「戻り値」によって定義される属性を、リモート デバッグ プロトコルでのコマンドの説明の時点で指定する必要があります。

戻り値

  • Promise&lt;object |未定義>

    Chrome 96 以降

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

イベント

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

ブラウザがタブのデバッグ セッションを終了すると呼び出されます。これは、タブが閉じられているか、接続されたタブに対して Chrome DevTools が呼び出されている場合に発生します。

パラメータ

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

デバッグ ターゲットがインストルメンテーション イベントを発行するたびに呼び出されます。

パラメータ

  • callback

    関数

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

    (source: DebuggerSession, method: string, params?: object) => void

    • ソース

      DebuggerSession

    • method

      文字列

    • params

      オブジェクト（省略可）