chrome.debugger

Beschreibung

Die chrome.debugger API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome. Verwenden Sie chrome.debugger, um einen oder mehrere Tabs hinzuzufügen, um die Netzwerkinteraktion zu instrumentieren, JavaScript-Fehler zu beheben, das DOM und CSS zu ändern und vieles mehr. Verwende die Debuggee-Eigenschaft tabId, um ein Targeting auf Tabs mit sendCommand vorzunehmen und Ereignisse nach tabId aus onEvent-Callbacks weiterzuleiten.

Berechtigungen

debugger

Du musst die Berechtigung "debugger" im Manifest deiner Erweiterung deklarieren, um diese API verwenden zu können.

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

Konzepte und Verwendung

Nach dem Hinzufügen der chrome.debugger API können Sie das Chrome DevTools Protocol senden. (CDP) an ein bestimmtes Ziel. Eine ausführliche Erläuterung des CDP fällt nicht in den Aufgabenbereich. für diese Dokumentation. Weitere Informationen zu CDP finden Sie in der offizielle CDP-Dokumentation.

Ziele

Ziele stellen etwas dar, das gerade geprüft wird, z. B. ein Tab, iFrame oder Worker. Jedes Ziel wird durch eine UUID identifiziert und hat eine zugehörige Typ (z. B. iframe oder shared_worker).

Innerhalb eines Ziels kann es mehrere Ausführungskontexte geben, z. B. denselben Prozess-iFrames erhalten kein eindeutiges Ziel, sondern werden Kontexte, auf die von einem einzelnen Ziel aus zugegriffen werden kann.

Eingeschränkte Domains

Aus Sicherheitsgründen bietet die chrome.debugger API nicht auf alle Chrome-Entwicklertools Zugriff Protokolldomains. Folgende Domains sind verfügbar: Barrierefreiheit im Internet, Audits, CacheStorage, Console, CSS, Datenbank, Debugger, DOM DOMDebugger, DOMSnapshot, Emulation, Abrufen, E/A, Eingabe Inspector, Protokoll, Netzwerk, Overlay, Seite, Leistung, Profiler, Laufzeit, Speicher, Ziel, Tracing WebAudio und WebAuthn.

Mit Rahmen arbeiten

Es gibt keine 1:1-Zuordnung von Frames zu Zielen. Auf einem einzelnen Tab Mehrere dieselben Prozessframes haben möglicherweise dasselbe Ziel, verwenden aber ein anderes Ausführungskontext. Andererseits kann ein neues Ziel die für einen Out-of-Process-iFrame erstellt wurden.

Um sie an allen Frames anzubringen, müssen Sie jeden Frame-Typ separat handhaben:

• Auf das Ereignis Runtime.executionContextCreated warten, um neue zu identifizieren Ausführungskontexte, die mit denselben Prozess-Frames verknüpft sind.

• Folgen Sie der Anleitung zum Anhängen an zugehörige Ziele, um Out-of-Process-Frames zu identifizieren.

An zugehörige Ziele anhängen

Nachdem Sie eine Verbindung zu einem Ziel hergestellt haben, sollten Sie eine Verbindung zu weiteren verwandten Zielen herstellen einschließlich untergeordneter Out-of-Process-Frames oder zugehöriger Worker.

Ab Chrome 125 unterstützt die chrome.debugger API Flat Sessions. Dieses können Sie Ihrer Haupt-Debugger-Sitzung zusätzliche Ziele als untergeordnete Ziele hinzufügen. Nachrichten senden, ohne chrome.debugger.attach noch einmal anrufen zu müssen. Stattdessen kannst du eine sessionId-Property hinzufügen, wenn du chrome.debugger.sendCommand für und geben Sie das untergeordnete Ziel an, an das Sie einen Befehl senden möchten.

Fügen Sie zum automatischen Anhängen an untergeordnete Frames außerhalb der Verarbeitung zunächst einen Listener für Das Target.attachedToTarget-Ereignis:

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

Aktivieren Sie dann automatisches Anhängen, indem Sie den Befehl Target.setAutoAttach mit ist die Option flatten auf true festgelegt:

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

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das Debugger API-Beispiel aus chrome-extension-samples. zu erstellen.

Typen

Debuggee

Die ID der zu debuggenden Komponente. Es muss entweder „tabId“, „extensionId“ oder „targetId“ angegeben werden

Attribute

• extensionId

  String optional

  Die ID der Erweiterung, die Sie debuggen möchten. Das Anhängen an eine Erweiterungshintergrundseite ist nur bei Verwendung des --silent-debugger-extension-api-Befehlszeilenparameters möglich.

• tabId

  Zahl optional

  Die ID des Tabs, auf dem Sie Fehler beheben möchten.

• targetId

  String optional

  Die intransparente ID des Fehlerbehebungsziels.

DebuggerSession

Chrome 125 oder höher

Debugger-Sitzungs-ID. Es muss entweder „tabId“, „extensionId“ oder „targetId“ angegeben werden. Außerdem kann eine optionale sessionId angegeben werden. Wenn für Argumente, die von onEvent gesendet werden, „sessionId“ angegeben ist, stammt das Ereignis aus einer Sitzung mit einem untergeordneten Protokoll in der Sitzung der zu debuggenden Root-Komponente. Wenn bei der Übergabe an sendCommand die sessionId angegeben wird, wird eine untergeordnete Protokollsitzung innerhalb der Sitzung der zu debuggenden Root-Komponente verwendet.

Attribute

• extensionId

  String optional

  Die ID der Erweiterung, die Sie debuggen möchten. Das Anhängen an eine Erweiterungshintergrundseite ist nur bei Verwendung des --silent-debugger-extension-api-Befehlszeilenparameters möglich.

• sessionId

  String optional

  Die intransparente ID der Sitzung mit dem Chrome-Entwicklertools-Protokoll. Kennzeichnet eine untergeordnete Sitzung innerhalb der Stammsitzung, die durch tabId, Erweiterungs-ID oder targetId identifiziert wird.

• tabId

  Zahl optional

  Die ID des Tabs, auf dem Sie Fehler beheben möchten.

• targetId

  String optional

  Die intransparente ID des Fehlerbehebungsziels.

DetachReason

Chrome (ab Version 44)

Grund für Verbindungsabbruch.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Zielinformationen zur Fehlerbehebung

Attribute

• Hinzugefügt

  boolean

  "True", wenn der Debugger bereits angehängt ist.

• extensionId

  String optional

  Die Erweiterungs-ID, die definiert wird, wenn type = 'background_page'.

• faviconUrl

  String optional

  Ziel-Favicon-URL.

• id

  String

  Ziel-ID.

• tabId

  Zahl optional

  Die TAB-ID, definiert, wenn type == 'page'.

• Titel

  String

  Titel der Landingpage.

• Typ

  TargetInfoType

  Zieltyp.

• URL

  String

  Ziel-URL

TargetInfoType

Chrome (ab Version 44)

Zieltyp.

Enum

„Seite“

"background_page"

"Mitarbeiter"

"Sonstiges"

Methoden

attach()

<ph type="x-smartling-placeholder"></ph> Versprechen

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

Hängt den Debugger an das angegebene Ziel an.

Parameter

• Ziel

  Zu debuggende Komponente

  Debugging-Ziel, an das Sie anhängen möchten.

• requiredVersion

  String

  Erforderliche Version des Debugging-Protokolls ("0.1") Die zu debuggende Komponente kann nur mit einer übereinstimmenden Hauptversion und einer höheren oder gleichen Nebenversion an die zu debuggende Komponente angehängt werden. Eine Liste der Protokollversionen finden Sie hier.

• callback

  Funktion optional

  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

  () => void

Gibt Folgendes zurück:

• Versprechen<void>

  Chrome 96 und höher

  Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

detach()

<ph type="x-smartling-placeholder"></ph> Versprechen

chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

Trennt den Debugger vom angegebenen Ziel.

Parameter

• Ziel

  Zu debuggende Komponente

  Debuggingziel, von dem Sie die Verbindung trennen möchten

• callback

  Funktion optional

  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

  () => void

Gibt Folgendes zurück:

• Versprechen<void>

  Chrome 96 und höher

  Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getTargets()

<ph type="x-smartling-placeholder"></ph> Versprechen

chrome.debugger.getTargets(
  callback?: function,
)

Gibt die Liste der verfügbaren Fehlerbehebungsziele zurück

Parameter

• callback

  Funktion optional

  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

  (result: TargetInfo[]) => void

  • Ergebnis

    TargetInfo[]

    Array von TargetInfo-Objekten, die den verfügbaren Debug-Zielen entsprechen.

Gibt Folgendes zurück:

• Promise&lt;TargetInfo[]&gt;

  Chrome 96 und höher

  Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

sendCommand()

<ph type="x-smartling-placeholder"></ph> Versprechen

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

Sendet den angegebenen Befehl an das Debugging-Ziel.

Parameter

• Ziel

  DebuggerSession

  Debugging-Ziel, an das Sie den Befehl senden möchten.

• method

  String

  Methodenname. Sollte eine der durch das Remote-Debugging-Protokoll definierten Methoden sein.

• commandParams

  Objekt optional

  JSON-Objekt mit Anfrageparametern. Dieses Objekt muss dem Remote-Debugging-Parameter-Schema für die jeweilige Methode entsprechen.

• callback

  Funktion optional

  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

  (result?: object) => void

  • Ergebnis

    Objekt optional

    JSON-Objekt mit der Antwort. Die Struktur der Antwort variiert je nach Methodenname und wird durch die "returns"- Attribut der Befehlsbeschreibung im Remote-Debugging-Protokoll.

Gibt Folgendes zurück:

• Promise&lt;object | nicht definiert>

  Chrome 96 und höher

  Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

Ereignisse

onDetach

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

Wird ausgelöst, wenn der Browser die Debugging-Sitzung für den Tab beendet Dies geschieht, wenn entweder der Tab geschlossen oder die Chrome-Entwicklertools für den angehängten Tab aufgerufen werden.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

  (source: Debuggee, reason: DetachReason) => void

  • source

    Zu debuggende Komponente

  • reason

    DetachReason

onEvent

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

Wird ausgelöst, wenn beim Debugging des Ziels Probleme mit dem Instrumentierungsereignis auftreten.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

  • source

    DebuggerSession

  • method

    String

  • params

    Objekt optional