Beschrijving
De chrome.debugger
API dient als alternatief transport voor het protocol voor foutopsporing op afstand van Chrome. Gebruik chrome.debugger
om aan een of meer tabbladen te koppelen om netwerkinteractie te instrumenteren, JavaScript te debuggen, de DOM en CSS te muteren, en meer. Gebruik de Debuggee
eigenschap tabId
om tabbladen te targeten met sendCommand
en gebeurtenissen te routeren op tabId
vanuit onEvent
callbacks.
Machtigingen
debugger
U moet de "debugger"
machtiging opgeven in het manifest van uw extensie om deze API te kunnen gebruiken.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Concepten en gebruik
Eenmaal gekoppeld, kunt u met de chrome.debugger
API Chrome DevTools Protocol (CDP)-opdrachten naar een bepaald doel verzenden. Het CDP diepgaand uitleggen valt buiten het bestek van deze documentatie. Voor meer informatie over CDP kunt u de officiële CDP-documentatie raadplegen.
Doelstellingen
Doelen vertegenwoordigen iets waarvoor fouten worden opgespoord; dit kan een tabblad, een iframe of een werker zijn. Elk doel wordt geïdentificeerd door een UUID en heeft een bijbehorend type (zoals iframe
, shared_worker
en meer).
Binnen een doel kunnen er meerdere uitvoeringscontexten zijn; dezelfde proces-iframes krijgen bijvoorbeeld geen uniek doel, maar worden in plaats daarvan weergegeven als verschillende contexten die toegankelijk zijn vanuit één enkel doel.
Beperkte domeinen
Om veiligheidsredenen biedt de chrome.debugger
API geen toegang tot alle Chrome DevTools Protocol-domeinen. De beschikbare domeinen zijn: Toegankelijkheid , Audits , CacheStorage , Console , CSS , Database , Debugger , DOM , DOMDebugger , DOMSnapshot , Emulatie , Fetch , IO , Input , Inspector , Log , Netwerk , Overlay , Pagina , Prestaties , Profiler , Runtime , Opslag , Target , Tracing , WebAudio en WebAuthn .
Werk met kaders
Er is geen één-op-één toewijzing van frames aan doelen. Binnen één tabblad kunnen meerdere dezelfde procesframes hetzelfde doel delen, maar een andere uitvoeringscontext gebruiken. Aan de andere kant kan er een nieuw doel worden gemaakt voor een iframe dat niet meer wordt verwerkt.
Om aan alle frames te bevestigen, moet u elk type frame afzonderlijk behandelen:
Luister naar de gebeurtenis
Runtime.executionContextCreated
om nieuwe uitvoeringscontexten te identificeren die aan dezelfde procesframes zijn gekoppeld.Volg de stappen om aan gerelateerde doelen te koppelen om frames die buiten het proces vallen te identificeren.
Koppel aan gerelateerde doelen
Nadat u verbinding heeft gemaakt met een doel, wilt u mogelijk verbinding maken met verdere gerelateerde doelen, waaronder onderliggende frames die niet in behandeling zijn of bijbehorende werkkrachten.
Vanaf Chrome 125 ondersteunt de chrome.debugger
API platte sessies. Hierdoor kunt u extra doelen als onderliggende doelen toevoegen aan uw hoofdfoutopsporingssessie en hen een bericht sturen zonder dat u opnieuw chrome.debugger.attach
hoeft aan te roepen. In plaats daarvan kunt u een sessionId
eigenschap toevoegen wanneer u chrome.debugger.sendCommand
aanroept om het onderliggende doel te identificeren waarnaar u een opdracht wilt verzenden.
Om automatisch te koppelen aan onderliggende frames die niet worden verwerkt, voegt u eerst een luisteraar toe voor de gebeurtenis 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");
}
});
Schakel vervolgens automatisch koppelen in door de opdracht Target.setAutoAttach
te verzenden met de optie flatten
ingesteld op true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Voorbeelden
Als u deze API wilt uitproberen, installeert u het debugger-API-voorbeeld uit de chrome-extension-samples- repository.
Soorten
Debuggee
Debuggee-ID. TabId, extensionId of targetId moeten worden opgegeven
Eigenschappen
- extensieId
tekenreeks optioneel
De id van de extensie waarvoor u fouten wilt opsporen. Het koppelen aan een extensie-achtergrondpagina is alleen mogelijk als de opdrachtregeloptie
--silent-debugger-extension-api
wordt gebruikt. - tabId
nummer optioneel
De ID van het tabblad waarvoor u fouten wilt opsporen.
- doelID
tekenreeks optioneel
De ondoorzichtige ID van het foutopsporingsdoel.
DebuggerSession
Identificatie van de foutopsporingssessie. Er moet een van tabId, extensionId of targetId worden opgegeven. Bovendien kan een optionele sessionId worden opgegeven. Als sessionId is opgegeven voor argumenten die worden verzonden vanuit onEvent
, betekent dit dat de gebeurtenis afkomstig is van een onderliggende protocolsessie binnen de root debuggee-sessie. Als sessionId wordt opgegeven wanneer het wordt doorgegeven aan sendCommand
, richt het zich op een onderliggende protocolsessie binnen de root-debuggee-sessie.
Eigenschappen
- extensieId
tekenreeks optioneel
De id van de extensie waarvoor u fouten wilt opsporen. Het koppelen aan een extensie-achtergrondpagina is alleen mogelijk als de opdrachtregeloptie
--silent-debugger-extension-api
wordt gebruikt. - sessieId
tekenreeks optioneel
De ondoorzichtige ID van de Chrome DevTools Protocol-sessie. Identificeert een onderliggende sessie binnen de hoofdsessie, geïdentificeerd door tabId, extensionId of targetId.
- tabId
nummer optioneel
De ID van het tabblad waarvoor u fouten wilt opsporen.
- doelID
tekenreeks optioneel
De ondoorzichtige ID van het foutopsporingsdoel.
DetachReason
Reden voor beëindiging van de verbinding.
Enum
"doel_gesloten" "geannuleerd_door_gebruiker"
TargetInfo
Debug doelinformatie
Eigenschappen
- bijgevoegd
Booleaans
Waar als debugger al is aangesloten.
- extensieId
tekenreeks optioneel
De extensie-ID, gedefinieerd als type = 'background_page'.
- faviconUrl
tekenreeks optioneel
Doelfavicon-URL.
- Identiteitskaart
snaar
Doel-ID.
- tabId
nummer optioneel
De tabblad-ID, gedefinieerd als type == 'pagina'.
- titel
snaar
Titel van doelpagina.
- type
Doeltype.
- URL
snaar
Doel-URL.
TargetInfoType
Doeltype.
Enum
"pagina" "achtergrond_pagina" "werknemer" "ander"
Methoden
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Koppelt debugger aan het opgegeven doel.
Parameters
- doel
Foutopsporing in het doel waaraan u wilt koppelen.
- vereiste versie
snaar
Vereiste versie van het foutopsporingsprotocol ("0.1"). Men kan alleen aan de debuggee koppelen met een overeenkomende hoofdversie en een grotere of gelijke secundaire versie. Een lijst met de protocolversies kunt u hier verkrijgen.
- terugbellen
functie optioneel
De
callback
parameter ziet er als volgt uit:() => void
Retouren
Beloof <nietig>
Chroom 96+Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Ontkoppelt debugger van het opgegeven doel.
Parameters
- doel
Foutopsporing in het doel waarvan u zich wilt losmaken.
- terugbellen
functie optioneel
De
callback
parameter ziet er als volgt uit:() => void
Retouren
Beloof <nietig>
Chroom 96+Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Retourneert de lijst met beschikbare foutopsporingsdoelen.
Parameters
- terugbellen
functie optioneel
De
callback
parameter ziet er als volgt uit:(result: TargetInfo[]) => void
- resultaat
DoelInfo []
Array van TargetInfo-objecten die overeenkomen met de beschikbare foutopsporingsdoelen.
Retouren
Beloof < DoelInfo []>
Chroom 96+Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Stuurt het opgegeven commando naar het foutopsporingsdoel.
Parameters
- doel
Foutopsporing in het doel waarnaar u de opdracht wilt verzenden.
- methode
snaar
Naam van methode. Moet een van de methoden zijn die zijn gedefinieerd door het protocol voor foutopsporing op afstand .
- commandoParams
object optioneel
JSON-object met aanvraagparameters. Dit object moet voldoen aan het parameterschema voor foutopsporing op afstand voor een bepaalde methode.
- terugbellen
functie optioneel
De
callback
parameter ziet er als volgt uit:(result?: object) => void
- resultaat
object optioneel
JSON-object met het antwoord. De structuur van het antwoord varieert afhankelijk van de naam van de methode en wordt gedefinieerd door het attribuut 'returns' van de opdrachtbeschrijving in het protocol voor foutopsporing op afstand.
Retouren
Belofte<object | ongedefinieerd>
Chroom 96+Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.
Evenementen
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Wordt geactiveerd wanneer de browser de foutopsporingssessie voor het tabblad beëindigt. Dit gebeurt wanneer het tabblad wordt gesloten of Chrome DevTools wordt aangeroepen voor het bijgevoegde tabblad.
Parameters
- terugbellen
functie
De
callback
parameter ziet er als volgt uit:(source: Debuggee, reason: DetachReason) => void
- bron
- reden
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Wordt geactiveerd wanneer foutopsporing in de instrumentatiegebeurtenis van doelproblemen optreedt.
Parameters
- terugbellen
functie
De
callback
parameter ziet er als volgt uit:(source: DebuggerSession, method: string, params?: object) => void
- bron
- methode
snaar
- parameters
object optioneel