Descrizione
L'API chrome.debugger
funge da trasporto alternativo per il protocollo di debug remoto di Chrome. Usa chrome.debugger
per aggiungere un link a una o più schede allo strumento dell'interazione con la rete, eseguire il debug di JavaScript, modificare DOM e CSS e altro ancora. Utilizza la proprietà Debuggee
tabId
per scegliere come target le schede con sendCommand
e indirizzare gli eventi in base a tabId
da onEvent
callback.
Autorizzazioni
debugger
Per usare questa API, devi dichiarare l'autorizzazione "debugger"
nel manifest dell'estensione.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Concetti e utilizzo
Una volta collegata, l'API chrome.debugger
ti consente di inviare comandi Chrome DevTools Protocol (CDP) a una determinata destinazione. Una spiegazione approfondita di CDP non rientra nell'ambito di questa documentazione. Per saperne di più, consulta la documentazione ufficiale di CDP.
Destinazioni
Le destinazioni rappresentano qualcosa di cui è in corso il debug, ad esempio una scheda, un iframe o un worker. Ogni target è identificato da un UUID e ha un tipo associato (come iframe
, shared_worker
e altro).
All'interno di un target possono esserci più contesti di esecuzione, ad esempio gli iframe dello stesso processo non ricevono un target univoco, ma sono rappresentati come contesti diversi a cui è possibile accedere da un singolo target.
Domini con restrizioni
Per motivi di sicurezza, l'API chrome.debugger
non fornisce l'accesso a tutti i domini del protocollo di Chrome DevTools. I domini disponibili sono: Accessibility,
Audits, CacheStorage, Console,
CSS, Database, Debugger, DOM,
DOMDebugger, DOMSnapshot,
Emulazione,DOMSnapshotWebAudioWebAuthn
Utilizza i frame
Non esiste una mappatura uno a uno dei frame alle destinazioni. All'interno di una singola scheda, più frame dello stesso processo possono condividere lo stesso target, ma utilizzare un contesto di esecuzione diverso. È possibile, invece, creare un nuovo target per un iframe out-of-process.
Per attaccare a tutti i frame, devi gestire ogni tipo di cornice separatamente:
Ascolta l'evento
Runtime.executionContextCreated
per identificare nuovi contesti di esecuzione associati agli stessi frame del processo.Segui i passaggi per il collegamento alle destinazioni correlate per identificare i frame out-of-process.
Allega a target correlati
Dopo aver eseguito la connessione a una destinazione, potresti voler connetterti ad altre destinazioni correlate, tra cui frame secondari out-of-process o worker associati.
A partire da Chrome 125, l'API chrome.debugger
supporta le sessioni fisse. Questo
consente di aggiungere ulteriori target come elementi secondari alla sessione principale del debugger e
invia messaggi senza bisogno di un'altra chiamata a chrome.debugger.attach
. Puoi invece aggiungere una proprietà sessionId
durante la chiamata a chrome.debugger.sendCommand
per identificare il target figlio a cui vuoi inviare un comando.
Per collegarti automaticamente a frame secondari fuori processo, aggiungi prima un listener per l'evento 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");
}
});
Quindi, abilita il collegamento automatico inviando il comando Target.setAutoAttach
con l'opzione flatten
impostata su true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Esempi
Per provare questa API, installa l'esempio di API di debug dal repository chrome-extension-samples.
Tipi
Debuggee
Identificatore debuggee. È necessario specificare tabId, ExtensionsId o targetId
Proprietà
-
extensionId
stringa facoltativo
L'ID dell'estensione di cui vuoi eseguire il debug. Il collegamento a una pagina in background di un'estensione è possibile solo quando viene utilizzata l'opzione della riga di comando
--silent-debugger-extension-api
. -
tabId
numero facoltativo
L'ID della scheda di cui vuoi eseguire il debug.
-
targetId
stringa facoltativo
L'ID opaco della destinazione di debug.
DebuggerSession
Identificatore di sessione debugger. È necessario specificare tabId, ExtensionsId o targetId. Inoltre, è possibile fornire un sessionId facoltativo. Se sessionId è specificato per gli argomenti inviati da onEvent
, significa che l'evento proviene da una sessione del protocollo figlio all'interno della sessione principale del debuggee. Se sessionId viene specificato quando viene trasmesso a sendCommand
, scegli come target una sessione di protocollo figlio all'interno della sessione principale del debuggee.
Proprietà
-
extensionId
stringa facoltativo
L'ID dell'estensione di cui vuoi eseguire il debug. Il collegamento a una pagina in background di un'estensione è possibile solo quando viene utilizzata l'opzione della riga di comando
--silent-debugger-extension-api
. -
sessionId
stringa facoltativo
L'ID opaco della sessione del protocollo Chrome DevTools. Identifica una sessione secondaria all'interno della sessione principale identificata da tabId, ExtensionsId o targetId.
-
tabId
numero facoltativo
L'ID della scheda di cui vuoi eseguire il debug.
-
targetId
stringa facoltativo
L'ID opaco della destinazione di debug.
DetachReason
Motivo dell'interruzione della connessione.
Enum
"target_closed"
"canceled_by_user"
TargetInfo
Informazioni sulla destinazione di debug
Proprietà
-
collegato
boolean
True se il debugger è già collegato.
-
extensionId
stringa facoltativo
L'ID dell'estensione, definito se type = "background_page".
-
faviconUrl
stringa facoltativo
Scegli come target l'URL della favicon.
-
id
stringa
ID target.
-
tabId
numero facoltativo
L'ID scheda, definito se type == 'page'.
-
title
stringa
Titolo della pagina di destinazione.
-
Tipo
Tipo di target.
-
url
stringa
URL di destinazione.
TargetInfoType
Tipo di target.
Enum
"background_page"
Metodi
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Collega il debugger alla destinazione specificato.
Parametri
-
target
Destinazione di debug a cui vuoi eseguire il collegamento.
-
requiredVersion
stringa
Versione del protocollo di debug obbligatoria ("0.1"). È possibile eseguire il collegamento all'oggetto del debug solo con la versione principale corrispondente e la versione secondaria uguale o superiore. Un elenco delle versioni di protocollo è disponibile qui.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Stacca il debugger dal target specificato.
Parametri
-
target
Destinazione di debug da cui eseguire lo scollegamento.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Restituisce l'elenco delle destinazioni di debug disponibili.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: TargetInfo[]) => void
-
risultato
Array di oggetti TargetInfo corrispondenti alle destinazioni di debug disponibili.
-
Ritorni
-
Promise<TargetInfo[]>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Invia il comando specificato alla destinazione di debug.
Parametri
-
target
Destinazione di debug a cui vuoi inviare il comando.
-
method
stringa
Nome del metodo. Deve essere uno dei metodi definiti dal protocollo di debug remoto.
-
commandParams
oggetto facoltativo
Oggetto JSON con parametri di richiesta. Questo oggetto deve essere conforme allo schema dei parametri di debug remoto per un determinato metodo.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result?: object) => void
-
risultato
oggetto facoltativo
JSON con la risposta. La struttura della risposta varia a seconda del nome del metodo ed è definita dall'attributo "returns" della descrizione del comando nel protocollo di debug remoto.
-
Ritorni
-
Promise<object | undefined>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
Eventi
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Attivato quando il browser termina la sessione di debug per la scheda. Questo accade quando la scheda viene chiusa o Chrome DevTools viene richiamato per la scheda collegata.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(source: Debuggee, reason: DetachReason) => void
-
source
-
motivo
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Attivato quando viene eseguito il debug dell'evento di strumentazione relativo ai problemi della destinazione.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
stringa
-
params
oggetto facoltativo
-