Opis
Interfejs chrome.debugger API służy jako alternatywny transport dla protokołu zdalnego debugowania w Chrome. Użyj chrome.debugger, aby dołączyć do co najmniej 1 karty i instrumentować interakcje sieciowe, debugować JavaScript, zmieniać DOM i CSS oraz wykonywać inne czynności. Użyj właściwości Debuggee tabId, aby kierować zdarzenia do kart z wartością sendCommand i kierować zdarzenia według wartości tabId z wywołań zwrotnych onEvent.
Uprawnienia
debuggerAby korzystać z tego interfejsu API, musisz zadeklarować uprawnienie "debugger" w pliku manifestu rozszerzenia.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Ograniczenia zasad dotyczących przedsiębiorstw
Na urządzeniach firmowych niektóre zasady mogą ograniczać możliwość dołączania debugera przez rozszerzenia za pomocą modelu „wszystko albo nic” w momencie dołączania (browser.debugger.attach()):
- Ograniczenia dotyczące hostów: jeśli zasada przedsiębiorstwa
ExtensionSettingskonfiguruje zablokowanych hostów (runtime_blocked_hosts) dla rozszerzenia,browser.debugger.attach()jest blokowany na wszystkich platformach docelowych z błędem"Host access is restricted by policy."(nawet jeśli poszczególne źródła znajdują się wruntime_allowed_hosts). - Zasady dotyczące zrzutów ekranu i DLP: jeśli zasady przedsiębiorstwa
DisableScreenshotsuniemożliwiają robienie zrzutów ekranu lub do docelowego elementu mają zastosowanie reguły zapobiegania utracie danych (DLP), funkcjabrowser.debugger.attach()kończy się niepowodzeniem i wyświetla błąd"Screenshot capture is restricted by policy.".
Pojęcia i użycie
Po dołączeniu interfejs API browser.debugger umożliwia wysyłanie poleceń protokołu narzędzi deweloperskich w Chrome (CDP) do danego elementu docelowego. Szczegółowe wyjaśnienie CDP wykracza poza zakres tej dokumentacji. Więcej informacji o CDP znajdziesz w oficjalnej dokumentacji CDP.
Cele
Obiekty docelowe reprezentują coś, co jest debugowane – może to być karta, element iframe lub proces roboczy. Każdy element docelowy jest identyfikowany przez UUID i ma powiązany typ (np. iframe, shared_worker itp.).
W ramach jednego celu może występować wiele kontekstów wykonania. Na przykład ramki iframe w tym samym procesie nie mają unikalnego celu, ale są reprezentowane jako różne konteksty, do których można uzyskać dostęp z poziomu jednego celu.
Domeny z ograniczeniami
Ze względów bezpieczeństwa interfejs browser.debugger API nie zapewnia dostępu do wszystkich domen protokołu Narzędzi deweloperskich w Chrome. Dostępne domeny to: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Runtime, Storage, Target, Tracing, WebAudio i WebAuthn.
Praca z ramkami
Nie ma mapowania klatek na cele w stosunku 1:1. W ramach jednej karty wiele ramek tego samego procesu może mieć ten sam cel, ale używać innego kontekstu wykonania. Z drugiej strony w przypadku ramki iframe działającej w innym procesie można utworzyć nowy cel.
Aby dołączyć do wszystkich ramek, musisz osobno obsłużyć każdy typ ramki:
Nasłuchuj zdarzenia
Runtime.executionContextCreated, aby identyfikować nowe konteksty wykonania powiązane z tymi samymi ramkami procesu.Aby zidentyfikować klatki poza procesem, wykonaj czynności opisane w sekcji Dołączanie do powiązanych elementów docelowych.
Dołączanie do powiązanych celów
Po połączeniu się z elementem docelowym możesz połączyć się z kolejnymi powiązanymi elementami docelowymi, w tym z ramkami podrzędnymi działającymi poza procesem lub powiązanymi procesami roboczymi.
Od Chrome 125 interfejs browser.debugger API obsługuje sesje płaskie. Dzięki temu możesz dodawać dodatkowe cele jako elementy podrzędne do głównej sesji debugowania i wysyłać do nich wiadomości bez konieczności wykonywania kolejnego wywołania funkcji browser.debugger.attach. Zamiast tego możesz dodać właściwość sessionId podczas wywoływania browser.debugger.sendCommand, aby wskazać urządzenie docelowe dziecka, do którego chcesz wysłać polecenie.
Aby automatycznie dołączać do ramek podrzędnych działających w osobnych procesach, najpierw dodaj detektor zdarzeń Target.attachedToTarget:
browser.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 browser.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 browser.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Automatyczne dołączanie działa tylko w przypadku ramek, o których wie element docelowy. Ogranicza się to do ramek, które są bezpośrednimi elementami podrzędnymi ramki z nim powiązanej. Na przykład w przypadku hierarchii ramek A –> B –> C (gdzie wszystkie są współdzielone) wywołanie Target.setAutoAttach dla elementu docelowego powiązanego z ramką A spowoduje, że sesja zostanie też dołączona do ramki B. Nie jest to jednak działanie rekurencyjne, więc w przypadku B należy też wywołać funkcję Target.setAutoAttach, aby dołączyć sesję do C.
Przykłady
Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu API debugera z repozytorium chrome-extension-samples.
Typy
Debuggee
Identyfikator debugowanego procesu. Musisz podać tabId, extensionId lub targetId.
Właściwości
-
extensionId
ciąg znaków opcjonalny
Identyfikator rozszerzenia, które chcesz debugować. Dołączanie do strony tła rozszerzenia jest możliwe tylko wtedy, gdy używany jest przełącznik wiersza poleceń
--silent-debugger-extension-api. -
tabId
number opcjonalny
Identyfikator karty, którą chcesz debugować.
-
targetId
ciąg znaków opcjonalny
Nieprzezroczysty identyfikator celu debugowania.
DebuggerSession
Identyfikator sesji debugera. Musisz podać jeden z tych identyfikatorów: tabId, extensionId lub targetId. Dodatkowo można podać opcjonalny identyfikator sesji. Jeśli w przypadku argumentów wysyłanych z onEvent określono sessionId, oznacza to, że zdarzenie pochodzi z sesji protokołu podrzędnego w ramach sesji głównej debugowanego procesu. Jeśli podczas przekazywania do funkcji sendCommand określono identyfikator sessionId, funkcja ta będzie kierowana do sesji protokołu podrzędnego w ramach sesji debugowania głównego.
Właściwości
-
extensionId
ciąg znaków opcjonalny
Identyfikator rozszerzenia, które chcesz debugować. Dołączanie do strony tła rozszerzenia 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 narzędzi deweloperskich w Chrome. Identyfikuje sesję podrzędną w sesji głównej zidentyfikowanej przez tabId, extensionId lub targetId.
-
tabId
number opcjonalny
Identyfikator karty, którą chcesz debugować.
-
targetId
ciąg znaków opcjonalny
Nieprzezroczysty identyfikator celu debugowania.
DetachReason
Przyczyna zakończenia połączenia.
Typ wyliczeniowy
„target_closed”
„canceled_by_user”
TargetInfo
Informacje o celu debugowania
Właściwości
-
podłączony
wartość logiczna
Wartość „true”, jeśli debuger jest już dołączony.
-
extensionId
ciąg znaków opcjonalny
Identyfikator rozszerzenia zdefiniowany, jeśli typ to „background_page”.
-
faviconUrl
ciąg znaków opcjonalny
Docelowy adres URL favikony.
-
id
tekst
Identyfikator miejsca docelowego.
-
tabId
number opcjonalny
Identyfikator karty, zdefiniowany, jeśli type == 'page'.
-
tytuł
tekst
Tytuł strony docelowej.
-
typ
Typ celu.
-
URL
tekst
Docelowy adres URL.
TargetInfoType
Typ celu.
Typ wyliczeniowy
„page”
"background_page"
„worker”
„other”
Metody
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
): Promise<void>
Dołącza debuger do danego celu.
Parametry
-
cel
Cel debugowania, do którego chcesz się dołączyć.
-
requiredVersion
tekst
Wymagana wersja protokołu debugowania („0.1”). Do debugowanego programu można dołączyć tylko wtedy, gdy jego wersja główna jest zgodna z wersją główną debugera, a wersja podrzędna jest od niej większa lub równa. Listę wersji protokołu znajdziesz tutaj.
Zwroty
-
Promise<void>
Chrome 96 lub nowszaZwraca obietnicę po zakończeniu operacji dołączania (powodzeniem lub niepowodzeniem). Obietnica jest spełniona bez wartości. Jeśli dołączenie się nie powiedzie, obietnica zostanie odrzucona.
detach()
chrome.debugger.detach(
target: Debuggee,
): Promise<void>
Odłącza debuger od danego miejsca docelowego.
Parametry
-
cel
Cel debugowania, od którego chcesz się odłączyć.
Zwroty
-
Promise<void>
Chrome 96 lub nowszaZwraca obietnicę po zakończeniu operacji odłączania (z powodzeniem lub nie). Obietnica jest spełniona bez wartości. Jeśli odłączenie się nie powiedzie, obietnica zostanie odrzucona.
getTargets()
chrome.debugger.getTargets(): Promise<TargetInfo[]>
Zwraca listę dostępnych celów debugowania.
Zwroty
-
Promise<TargetInfo[]>
Chrome 96 lub nowsza
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
): Promise<object | undefined>
Wysyła podane polecenie do celu debugowania.
Parametry
-
cel
Cel debugowania, do którego chcesz wysłać polecenie.
-
method
tekst
Nazwa metody. Musi to być jedna z metod zdefiniowanych w protokole zdalnego debugowania.
-
commandParams
obiekt opcjonalny
Obiekt JSON z parametrami żądania. Ten obiekt musi być zgodny ze schematem parametrów debugowania zdalnego dla danej metody.
Zwroty
-
Promise<object | undefined>
Chrome 96 lub nowszaTreść odpowiedzi. Jeśli podczas publikowania wiadomości wystąpi błąd, obietnica zostanie odrzucona.
Wydarzenia
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Wywoływane, gdy przeglądarka kończy sesję debugowania karty. Dzieje się tak, gdy karta jest zamykana lub gdy dla dołączonej karty wywoływane są Narzędzia deweloperskie w Chrome.
Parametry
-
callback
funkcja
Parametr
callbackwygląda tak:(source: Debuggee, reason: DetachReason) => void
-
źródło
-
powód,
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Wywoływane za każdym razem, gdy występuje zdarzenie instrumentacji problemów z elementem docelowym debugowania.
Parametry
-
callback
funkcja
Parametr
callbackwygląda tak:(source: DebuggerSession, method: string, params?: object) => void
-
źródło
-
method
tekst
-
params
obiekt opcjonalny
-