Questa pagina è stata tradotta dall'API Cloud Translation.

chrome.debugger

Descrizione

L'API chrome.debugger funge da trasporto alternativo per il protocollo di debug remoto di Chrome. Usa chrome.debugger per collegarti a una o più schede per analizzare l'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 dalle richiamate onEvent.

Autorizzazioni

debugger

Per usare questa API, devi dichiarare l'autorizzazione "debugger" nel file manifest dell'estensione.

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

Concetti e utilizzo

Una volta collegata, l'API chrome.debugger ti consente di inviare il protocollo Chrome DevTools (CDP) a una determinata destinazione. Una spiegazione approfondita del CDP non rientra nell'ambito per questa documentazione. Per saperne di più su CDP, consulta documentazione ufficiale CDP.

Destinazioni

Le destinazioni rappresentano un elemento di cui viene eseguito il debug, ad esempio una scheda, un iframe o un worker. Ogni target viene identificato da un UUID e ha un associato (ad esempio iframe, shared_worker e altri).

All'interno di un target, potrebbero esserci più contesti di esecuzione, ad esempio lo stesso gli iframe del processo non ricevono un target univoco, ma sono rappresentati come contesti diversi a cui è possibile accedere da una singola destinazione.

Domini con limitazioni

Per motivi di sicurezza, l'API chrome.debugger non fornisce accesso a tutti i Chrome DevTools Domini Protocolli. I domini disponibili sono: Accessibilità, Controlli, CacheStorage, console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulazione, Recupero, IO, Input, Ispezione, Log, Rete, Overlay, Pagina, Rendimento, Profiler, Runtime, archiviazione, destinazione, tracciamento, WebAudio e WebAuthn.

Lavora con i frame

Non esiste una mappatura 1:1 dei frame alle destinazioni. All'interno di una sola scheda, più frame di processo uguali possono condividere lo stesso target ma utilizzare un contesto di esecuzione. Un nuovo target può invece essere creato per un iframe out-of-process.

Per agganciarlo a tutte le cornici, devi gestire ogni tipo di cornice separatamente:

Ascolta l'evento Runtime.executionContextCreated per identificarne di nuovi contesti di esecuzione associati agli stessi frame di processo.
Segui i passaggi per eseguire l'associazione ai target correlati per: identificare i frame out-of-process.

Associa a target correlati

Dopo aver effettuato il collegamento a una destinazione, potrebbe essere utile stabilire un collegamento con altre destinazioni correlate inclusi i frame secondari out-of-process o i worker associati.

A partire da Chrome 125, l'API chrome.debugger supporta le sessioni piatte. Questo consente di aggiungere target aggiuntivi come elementi secondari alla sessione debugger principale invia loro un messaggio senza dover effettuare un'altra chiamata al numero chrome.debugger.attach. Invece, puoi aggiungere una proprietà sessionId quando chiami chrome.debugger.sendCommand a identificare il target figlio a cui inviare un comando.

Per collegarti automaticamente ai frame secondari out-of-process, 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 dell'API debugger da chrome-extension-samples repository Git.

Tipi

Debuggee

Identificatore debuggee. È necessario specificare tabId, extensionId o targetId

Proprietà

extensionId

stringa facoltativo

L'ID dell'estensione di cui intendi eseguire il debug. È possibile eseguire il collegamento a una pagina in background con un'estensione solo quando si utilizza 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

Chrome 125 e versioni successive .

Identificatore sessione debugger. È necessario specificare uno tra tabId, extensionId o targetId. Inoltre, è possibile fornire un sessionId facoltativo. Se sessionId viene specificato per gli argomenti inviati da onEvent, significa che l'evento proviene da una sessione di protocollo figlio all'interno della sessione di debuggee principale. Se sessionId viene specificato quando viene passato a sendCommand, sceglie come target una sessione di protocollo figlio all'interno della sessione di debuggee principale.

Proprietà

extensionId

stringa facoltativo

L'ID dell'estensione di cui intendi eseguire il debug. È possibile eseguire il collegamento a una pagina in background con un'estensione solo quando si utilizza 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, extensionId 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

Chrome 44 e versioni successive .

Motivo dell'interruzione della connessione.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informazioni sulla destinazione di debug

Proprietà

collegato

booleano

True se il debugger è già collegato.
extensionId

stringa facoltativo

L'ID dell'estensione, definito se il tipo = "background_page".
faviconUrl

stringa facoltativo

URL della favicon target.
id

stringa

ID target.
tabId

numero facoltativo

L'ID scheda, definito se il tipo == "pagina".
titolo

stringa

Titolo pagina di destinazione.
tipo

TargetInfoType

Tipo di target.
url

stringa

URL di destinazione.

TargetInfoType

Chrome 44 e versioni successive .

Tipo di target.

Enum

"pagina"

"background_page"

"worker"

"altro"

Metodi

attach()

Promesso .

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

Collega il debugger alla destinazione specificata.

Parametri

target

Debuggee

Debug della destinazione a cui vuoi collegarti.
requiredVersion

stringa

Versione del protocollo di debug obbligatoria ("0.1"). Uno può collegarsi al debuggee solo con una versione principale corrispondente e una versione secondaria superiore o uguale. L'elenco delle versioni del protocollo è disponibile qui.
callback

funzione facoltativa

Il parametro callback ha il seguente aspetto:
```
() => void
```

Resi

Promesso<void>

Chrome 96 e versioni successive .

Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

detach()

Promesso .

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

Stacca il debugger dalla destinazione specificata.

Parametri

target

Debuggee

Target di debug da cui vuoi scollegarti.
callback

funzione facoltativa

Il parametro callback ha il seguente aspetto:
```
() => void
```

Resi

Promesso<void>

Chrome 96 e versioni successive .

Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getTargets()

Promesso .

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

Restituisce l'elenco dei target di debug disponibili.

Parametri

callback

funzione facoltativa

Il parametro callback ha il seguente aspetto:
```
(result: TargetInfo[]) => void
```
- risultato
  
  TargetInfo[]
  
  Matrice di oggetti TargetInfo corrispondente alle destinazioni di debug disponibili.

Resi

Promise<TargetInfo[]>

Chrome 96 e versioni successive .

Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

sendCommand()

Promesso .

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

Invia il comando specificato alla destinazione di debug.

Parametri

target

DebuggerSession

Target 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 il metodo specificato.
callback

funzione facoltativa

Il parametro callback ha il seguente aspetto:
```
(result?: object) => void
```
- risultato
  
  oggetto facoltativo
  
  oggetto JSON con la risposta. La struttura della risposta varia a seconda del nome del metodo ed è definita dal parametro "returns" della descrizione del comando nel protocollo di debug remoto.

Resi

Promise<object | non definito>

Chrome 96 e versioni successive .

Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato 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
```
- origine
  
  Debuggee
- motivo
  
  DetachReason

onEvent

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

Attivato ogni volta che il debug del target genera un evento di strumentazione.

Parametri

callback

funzione

Il parametro callback ha il seguente aspetto:
```
(source: DebuggerSession, method: string, params?: object) => void
```
- origine
  
  DebuggerSession
- method
  
  stringa
- parametri
  
  oggetto facoltativo