Opis
Interfejs API chrome.debugger
służy jako alternatywny środek transportu dla protokołu zdalnego debugowania w Chrome. Użyj chrome.debugger
, aby dołączyć do co najmniej 1 karty, aby dodać instrument do interakcji z siecią, debugować JavaScript, mutować DOM i CSS i nie tylko. Użyj właściwości tabId
Debuggee
, aby kierować zdarzenia na karty z wartością sendCommand
i kierować zdarzenia z wywołania zwrotnego onEvent
przez tabId
.
Uprawnienia
debugger
Aby używać tego interfejsu API, musisz zadeklarować uprawnienie "debugger"
w pliku manifestu rozszerzenia.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Pojęcia i zastosowanie
Po podłączeniu interfejs API chrome.debugger
umożliwia wysyłanie do danego miejsca docelowego poleceń protokołu Chrome DevTools Protocol (CDP). Szczegółowy opis CDP nie mieści się w tej dokumentacji. Aby dowiedzieć się więcej na ten temat, zapoznaj się z oficjalną dokumentacją CDP.
Cele
Cele reprezentują coś, co jest debugowane – może to być karta, element iframe lub instancja robocza. Każdy cel jest identyfikowany przez identyfikator UUID i ma powiązany typ (np. iframe
, shared_worker
i inne).
W obrębie celu może istnieć wiele kontekstów wykonania. Na przykład elementy iframe tego samego procesu nie otrzymują unikalnego celu, ale są reprezentowane jako różne konteksty, do których można uzyskać dostęp z pojedynczego celu.
Domeny z ograniczeniami
Ze względów bezpieczeństwa interfejs API chrome.debugger
nie zapewnia dostępu do wszystkich domen protokołów Chrome DevTools. Dostępne domeny to: Accessibility,
Audits, CacheStorage, Console,
CSS, Database, Debugger, DOM,
DOMDebugger, DOMDebugger, DOMSnapshot}, DOMSnapshot}, DoSport, Emulation}.WebAudioWebAuthn
Praca z ramkami
Klatki docelowe nie są przyporządkowane indywidualnie. Na jednej karcie wiele takich samych ramek procesów może mieć ten sam cel, ale korzystać z innego kontekstu wykonania. Z drugiej strony element iframe poza procesem może zawierać nowe miejsce docelowe.
Aby móc dołączać do wszystkich klatek, musisz obsługiwać każdy typ ramki oddzielnie:
Wykrywaj zdarzenie
Runtime.executionContextCreated
, aby identyfikować nowe konteksty wykonania powiązane z tymi samymi klatkami procesów.Wykonaj te czynności, aby dołączyć do powiązanych celów w celu identyfikacji ramek poza procesem.
Dołącz do powiązanych celów
Po nawiązaniu połączenia ze środowiskiem docelowym możesz nawiązać połączenie z innymi powiązanymi elementami docelowymi, w tym ramkami podrzędnymi poza procesem lub powiązanymi instancjami roboczymi.
Od Chrome 125 interfejs API chrome.debugger
obsługuje sesje płaskie. Pozwoli Ci to dodawać kolejne cele jako elementy podrzędne do głównej sesji debugera i wysyłać do nich wiadomości bez potrzeby ponownego wywoływania funkcji chrome.debugger.attach
. Zamiast tego możesz podczas wywoływania metody chrome.debugger.sendCommand
dodać właściwość sessionId
, aby wskazać podrzędne środowisko docelowe, do którego chcesz wysłać polecenie.
Aby automatycznie dołączać do ramek podrzędnych poza procesem, najpierw dodaj odbiornik zdarzenia 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");
}
});
Następnie włącz automatyczne dołączanie, wysyłając polecenie Target.setAutoAttach
z opcją flatten
ustawioną na true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Przykłady
Aby go wypróbować, zainstaluj przykładowy interfejs API debugera z repozytorium chrome-extension-samples.
Typy
Debuggee
Identyfikator debugowania. Należy określić identyfikator tabId, identyfikator rozszerzenia lub identyfikator celu
Właściwości
-
extensionId
ciąg znaków opcjonalny
Identyfikator rozszerzenia, które chcesz debugować. Dołączenie elementu do strony w tle jest możliwe tylko wtedy, gdy używany jest przełącznik wiersza poleceń
--silent-debugger-extension-api
. -
tabId
Liczba opcjonalnie
Identyfikator karty, którą chcesz debugować.
-
targetId
ciąg znaków opcjonalny
Nieprzejrzysty identyfikator celu debugowania.
DebuggerSession
Identyfikator sesji debugera. Należy określić jeden z tych elementów: tabId, extensionsId lub targetId. Dodatkowo można podać opcjonalny identyfikator sessionId. Jeśli argument sessionId jest określony dla argumentów wysyłanych z onEvent
, oznacza to, że zdarzenie pochodzi z sesji protokołu podrzędnego w ramach głównej sesji debugowania. Jeśli identyfikator sesji zostanie określony podczas przekazywania do sendCommand
, będzie on kierowany na sesję protokołu podrzędnego w ramach głównej sesji debugowania.
Właściwości
-
extensionId
ciąg znaków opcjonalny
Identyfikator rozszerzenia, które chcesz debugować. Dołączenie elementu do strony w tle jest możliwe tylko wtedy, gdy używany jest przełącznik wiersza poleceń
--silent-debugger-extension-api
. -
sessionId
ciąg znaków opcjonalny
Nieprzejrzysty identyfikator sesji protokołu Chrome DevTools. Identyfikuje sesję podrzędną w ramach sesji głównej identyfikowanej za pomocą identyfikatora tabId, identyfikatora rozszerzenia lub identyfikatora elementu docelowego.
-
tabId
Liczba opcjonalnie
Identyfikator karty, którą chcesz debugować.
-
targetId
ciąg znaków opcjonalny
Nieprzejrzysty identyfikator celu debugowania.
DetachReason
Przyczyna zakończenia połączenia.
Typ wyliczeniowy
"target_closed"
"canceled_by_user"
TargetInfo
Informacje o miejscu docelowym debugowania
Właściwości
-
podłączony
boolean
Prawda, jeśli debuger jest już podłączony.
-
extensionId
ciąg znaków opcjonalny
Identyfikator rozszerzenia zdefiniowany, jeśli typ ma wartość 'background_page'.
-
faviconUrl
ciąg znaków opcjonalny
Adres URL favikony docelowej.
-
id
string,
Identyfikator docelowy.
-
tabId
Liczba opcjonalnie
Identyfikator karty zdefiniowany w przypadku typu == 'strona'.
-
title
string,
Tytuł strony docelowej.
-
Niestandardowy typ treści
Typ docelowy.
-
URL
string,
Docelowy URL.
TargetInfoType
Typ docelowy.
Typ wyliczeniowy
"background_page"
Metody
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Dołącza debuger do podanego celu.
Parametry
-
cel
Cel debugowania, do którego chcesz dołączyć.
-
requiredVersion
string,
Wymagana wersja protokołu debugowania („0.1”). Można dołączyć tylko do debugowanego obiektu z pasującą wersją główną i większą lub równą wersji podrzędnej. Listę wersji protokołów można znaleźć tutaj.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Odłącza debuger od podanego celu.
Parametry
-
cel
Cel debugowania, który chcesz odłączyć.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Zwraca listę dostępnych celów debugowania.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: TargetInfo[]) => void
-
wynik
Tablica obiektów TargetInfo odpowiadających dostępnym celom debugowania.
-
Zwroty
-
Promise<TargetInfo[]>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Wysyła podane polecenie do celu debugowania.
Parametry
-
cel
Cel debugowania, do którego chcesz przesłać polecenie.
-
method
string,
Nazwa metody. Musi to być jedna z metod zdefiniowanych przez protokół zdalnego debugowania.
-
commandParams
obiekt opcjonalnie
Obiekt JSON z parametrami żądania. Ten obiekt musi być zgodny ze schematem parametrów zdalnego debugowania w przypadku danej metody.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result?: object) => void
-
wynik
obiekt opcjonalnie
Obiekt JSON z odpowiedzią. Struktura odpowiedzi różni się w zależności od nazwy metody i jest definiowana przez atrybut „returns” w opisie polecenia w protokole debugowania zdalnego.
-
Zwroty
-
Promise<object | undefined>
Chrome 96 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Uruchamiane, gdy przeglądarka zakończy sesję debugowania karty. Dzieje się tak, gdy karta jest zamykana lub dla dołączonej karty wywoływane są Narzędzia deweloperskie w Chrome.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(source: Debuggee, reason: DetachReason) => void
-
source
-
powód
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Uruchamiane, gdy debugowanie problemów z instrumentacją powoduje problemy.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
string,
-
params
obiekt opcjonalnie
-