Descrição
A API chrome.debugger
serve como um transporte alternativo para o protocolo de depuração remota do Chrome. Use chrome.debugger
para anexar a uma ou mais guias para instrumentar a interação de rede, depurar o JavaScript, modificar o DOM e o CSS e muito mais. Use a propriedade tabId
de Debuggee
para segmentar guias com sendCommand
e rotear eventos por tabId
de callbacks de onEvent
.
Permissões
debugger
Observação de segurança
Por motivos de segurança, a API chrome.debugger
não fornece acesso a todos os domínios de protocolo do Chrome DevTools. Os domínios disponíveis são: Accessibility,
Auditorias, CacheStorage, Console,
CSS, Database, Debugger, DOM,
DOMDebugger, DOMSnapshot,
DOMSnapshot, Emulação}DatabaseDatabase.WebAudioWebAuthn
Manifesto
É necessário declarar a permissão "debugger"
no manifesto da extensão para usar a API.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Exemplos
Para testar essa API, instale o exemplo da API debugger no repositório chrome-extension-samples.
Tipos
Debuggee
Identificador do depurado. É necessário especificar tabId, extensionId ou targetId
Propriedades
-
extensionId
string opcional
O ID da extensão que você quer depurar. A anexação a uma página de segundo plano da extensão só é possível quando a chave da linha de comando
--silent-debugger-extension-api
é usada. -
tabId
número opcional
O ID da guia que você pretende depurar.
-
targetId
string opcional
O ID opaco do destino de depuração.
DebuggerSession
Identificador de sessão do depurador. Um dos tabId, extensionId ou targetId deve ser especificado. Além disso, um sessionId opcional pode ser fornecido. Se sessionId for especificado para argumentos enviados de onEvent
, isso significa que o evento vem de uma sessão de protocolo filha na sessão de depurado raiz. Se sessionId for especificado quando transmitido para sendCommand
, ele vai segmentar uma sessão de protocolo filha na sessão de depurado raiz.
Propriedades
-
extensionId
string opcional
O ID da extensão que você quer depurar. A anexação a uma página de segundo plano da extensão só é possível quando a chave da linha de comando
--silent-debugger-extension-api
é usada. -
sessionId
string opcional
O ID opaco da sessão do protocolo do Chrome DevTools. Identifica uma sessão filha dentro da sessão raiz identificada por tabId, extensionId ou targetId.
-
tabId
número opcional
O ID da guia que você pretende depurar.
-
targetId
string opcional
O ID opaco do destino de depuração.
DetachReason
Motivo do encerramento da conexão.
Tipo enumerado
"target_closed"
"canceled_by_user"
TargetInfo
Depurar informações do destino
Propriedades
-
sempre que o disco for anexado
boolean
Verdadeiro se o depurador já estiver anexado.
-
extensionId
string opcional
O código da extensão, definido se o tipo for 'background_page'.
-
faviconUrl
string opcional
URL do favicon de destino.
-
id
string
ID do destino.
-
tabId
número opcional
O ID da guia, definido se o tipo == 'page'.
-
title
string
Título da página de destino.
-
Tipo
Tipo de segmentação.
-
url
string
URL de destino.
TargetInfoType
Tipo de segmentação.
Tipo enumerado
"background_page"
Métodos
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Anexa o depurador ao destino especificado.
Parâmetros
-
destino
Destino de depuração ao qual você quer anexar.
-
requiredVersion
string
Versão necessária do protocolo de depuração ("0.1"). Só é possível anexar ao depurado com a versão principal correspondente e com a versão secundária maior ou igual. Confira a lista das versões do protocolo aqui.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Remove o depurador do destino especificado.
Parâmetros
-
destino
Destino de depuração do qual você quer se desconectar.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Retorna a lista de destinos de depuração disponíveis.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: TargetInfo[]) => void
-
resultado
Matriz de objetos TargetInfo correspondentes aos destinos de depuração disponíveis.
-
Retorna
-
Promise<TargetInfo[]>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Envia o comando especificado ao destino de depuração.
Parâmetros
-
destino
Destino de depuração para onde você quer enviar o comando.
-
method
string
Nome do método. Precisa ser um dos métodos definidos pelo protocolo de depuração remota.
-
commandParams
objeto opcional
Objeto JSON com parâmetros de solicitação. Esse objeto precisa estar em conformidade com o esquema de parâmetros da depuração remota para um determinado método.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result?: object) => void
-
resultado
objeto opcional
Objeto JSON com a resposta. A estrutura da resposta varia de acordo com o nome do método e é definida pelo atributo "returns" da descrição do comando no protocolo de depuração remota.
-
Retorna
-
Promise<object | undefined>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
Eventos
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Disparado quando o navegador encerra a sessão de depuração da guia. Isso acontece quando a guia está sendo fechada ou quando o Chrome DevTools está sendo invocado para a guia anexada.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(source: Debuggee, reason: DetachReason) => void
-
source
-
reason
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Disparado sempre que o destino de depuração emitir um evento de instrumentação.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
string
-
params
objeto opcional
-