chrome.debugger

Opis

Interfejs API chrome.debugger służy jako alternatywny środek transportu dla protokołu zdalnego debugowania w Chrome. Przy użyciu elementu chrome.debugger możesz dołączyć do co najmniej 1 karty w celu instrumentowania interakcji w sieci, debugowania JavaScriptu, zmieniania DOM i CSS oraz wykonywania innych działań. Użyj właściwości tabId Debuggee, aby kierować na karty z parametrem sendCommand i kierować zdarzenia według parametru tabId z onEvent wywołań zwrotnych.

Uprawnienia

debugger

Aby korzystać z tego interfejsu API, musisz zadeklarować uprawnienia "debugger" w pliku manifestu rozszerzenia.

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

Pojęcia i wykorzystanie

Po podłączeniu interfejs API chrome.debugger umożliwia wysyłanie protokołu Narzędzi deweloperskich w Chrome polecenia (CDP) do danego miejsca docelowego. Precyzyjne omówienie CDP nie mieści się w zakresie tej dokumentacji. Aby dowiedzieć się więcej o CDP, zapoznaj się z oficjalna dokumentacja CDP.

Cele

Cele reprezentują element, który jest właśnie debugowany. Może to być karta, w elemencie iframe lub instancji roboczej. Każdy cel jest identyfikowany przez UUID i ma powiązany identyfikator typ (na przykład iframe, shared_worker i inne).

W obrębie środowiska docelowego może być wiele kontekstów wykonania – na przykład ten sam elementów iframe procesu nie otrzymują unikalnej wartości docelowej, ale są reprezentowane jako różnych kontekstów, do których można uzyskać dostęp z jednego miejsca docelowego.

Domeny z ograniczeniami

Ze względów bezpieczeństwa interfejs API chrome.debugger nie zapewnia dostępu do wszystkich Narzędzi deweloperskich w Chrome Protocol Domains (Domeny protokołu). Dostępne domeny: Ułatwienia dostępu, Kontrole, CacheStorage, Konsola, CSS, baza danych, debuger, DOM, DOMDebugger, DOMSnapshot Emulacja, pobieranie, IO, dane wejściowe, Inspektor, dziennik, sieć, nakładka, Strona, Wydajność, Profiler, Środowisko wykonawcze, Miejsce na dane, Miejsce docelowe, Śledzenie, WebAudio i WebAuthn.

Praca z ramkami

Nie ma jednego mapowania klatek na elementy docelowe. Na jednej karcie wiele takich samych ramek procesu może mieć ten sam cel, ale używać innej kontekstu wykonania. Z drugiej strony nowy cel może być utworzony dla elementu iframe poza procesem.

Aby załączyć je do wszystkich ramek, musisz obchodzić się z każdym z nich oddzielnie:

  • Wykrywaj zdarzenie Runtime.executionContextCreated, aby zidentyfikować nowe kontekstach wykonania powiązanych z tymi samymi ramkami procesów.

  • Postępuj zgodnie z instrukcjami, aby załączyć go do powiązanych celów, aby: identyfikować klatki poza procesem.

Po połączeniu z celem możesz utworzyć połączenie z dalszymi powiązanymi celami łącznie z ramkami podrzędnymi poza procesem lub powiązanymi instancjami roboczymi.

Od wersji Chrome 125 interfejs API chrome.debugger obsługuje stałe sesje. Ten umożliwia dodanie kolejnych celów jako elementów podrzędnych do głównej sesji debugowania. możesz wysłać do tej osoby wiadomość bez potrzeby wykonywania kolejnego połączenia z numerem chrome.debugger.attach. Zamiast tego: możesz dodać właściwość sessionId podczas wywoływania funkcji chrome.debugger.sendCommand do wskazać podrzędne środowisko docelowe, do którego chcesz wysłać polecenie.

Aby automatycznie dołączać pliki do nieprzetworzonych klatek podrzędnych, najpierw dodaj detektor zdarzenie 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 opcja flatten ustawiona na true:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykładowy interfejs API debugowania ze strony chrome-extension-samples. z repozytorium.

Typy

Debuggee

Identyfikator debugowania. Musisz określić identyfikator tabId, identyfikator rozszerzenia lub identyfikator docelowy

Właściwości

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia, które chcesz debugować. Dołączenie do strony rozszerzenia w tle jest możliwe tylko wtedy, gdy jest używany przełącznik wiersza poleceń --silent-debugger-extension-api.

  • tabId

    liczba opcjonalnie

    Identyfikator karty, którą chcesz debugować.

  • targetId

    ciąg znaków opcjonalny

    Nieczytelny identyfikator celu debugowania.

DebuggerSession

Chrome w wersji 125 lub nowszej .

Identyfikator sesji debugera. Należy określić identyfikator tabId, identyfikator rozszerzenia lub identyfikator docelowy. Możesz też podać opcjonalny identyfikator sesji. Jeśli parametr sessionId jest określony w przypadku argumentów wysyłanych z metody onEvent, oznacza to, że zdarzenie pochodzi z sesji protokołu podrzędnego w ramach sesji debugowania głównego. Jeśli parametr sessionId jest określony podczas przekazywania do sendCommand, to kierowanie odbywa się na sesję 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łączenie do strony rozszerzenia w tle jest możliwe tylko wtedy, gdy jest używany przełącznik wiersza poleceń --silent-debugger-extension-api.

  • sessionId

    ciąg znaków opcjonalny

    Nieprzezroczysty identyfikator sesji protokołu deweloperskiego w Chrome. Identyfikuje sesję podrzędną w ramach sesji głównej identyfikowanej za pomocą identyfikatora tabId, identyfikatora rozszerzenia lub identyfikatora docelowego.

  • tabId

    liczba opcjonalnie

    Identyfikator karty, którą chcesz debugować.

  • targetId

    ciąg znaków opcjonalny

    Nieczytelny identyfikator celu debugowania.

DetachReason

Chrome w wersji 44 lub nowszej .

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ść prawda, jeśli debuger jest już podłączony.

  • extensionId

    ciąg znaków opcjonalny

    Identyfikator rozszerzenia określony, jeśli typ = „background_page”.

  • faviconUrl

    ciąg znaków opcjonalny

    Docelowy adres URL favikony.

  • id

    ciąg znaków

    Identyfikator elementu docelowego.

  • tabId

    liczba opcjonalnie

    Identyfikator karty określony, jeśli typ == „strona”.

  • tytuł

    ciąg znaków

    Tytuł strony docelowej.

  • Typ docelowy.

  • URL

    ciąg znaków

    Docelowy adres URL.

TargetInfoType

Chrome w wersji 44 lub nowszej .

Typ docelowy.

Typ wyliczeniowy

"strona"

"background_page"

"worker"

"inna"

Metody

attach()

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

Podłącza debuger do danego miejsca docelowego.

Parametry

  • Cel debugowania, do którego chcesz dołączyć.

  • requiredVersion

    ciąg znaków

    Wymagana wersja protokołu debugowania („0.1”). Do debugera można dołączyć tylko z pasującą wersją główną i wersją podrzędną większą lub równą. Listę wersji protokołów można znaleźć tutaj.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

detach()

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

Odłącza debuger od podanego miejsca docelowego.

Parametry

  • Cel debugowania, od którego chcesz się odłączyć.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getTargets()

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

Zwraca listę dostępnych celów debugowania.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (result: TargetInfo[]) => void

    • wynik

      TargetInfo[]

      Tablica obiektów TargetInfo odpowiadających dostępnym celom debugowania.

Zwroty

  • Promise&lt;TargetInfo[]&gt;

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

sendCommand()

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

Wysyła podane polecenie do środowiska docelowego debugowania.

Parametry

  • Cel debugowania, do którego chcesz wysłać polecenie.

  • method

    ciąg znaków

    Nazwa metody. Powinna być jedną z metod zdefiniowanych przez protokół zdalnego debugowania.

  • commandParams

    obiekt opcjonalny

    Obiekt JSON z parametrami żądania. Ten obiekt musi być zgodny ze schematem parametrów zdalnego debugowania dla danej metody.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (result?: object) => void

    • wynik

      obiekt opcjonalny

      Obiekt JSON z odpowiedzią. Struktura odpowiedzi zależy od nazwy metody i jest zdefiniowana przez argumenty „returns” w polu opisu polecenia w protokole zdalnego debugowania.

Zwroty

  • Promise&lt;object | niezdefiniowane>

    Chrome w wersji 96 lub nowszej, .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 na karcie. Dzieje się tak, gdy zamykasz kartę lub wywołujesz Narzędzia deweloperskie w Chrome dla dołączonej karty.

Parametry

onEvent

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

Uruchamiany za każdym razem, gdy debugowanie problemów docelowych jest zdarzeniem instrumentacji.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (source: DebuggerSession, method: string, params?: object) => void

    • źródło

      DebuggerSession

    • method

      ciąg znaków

    • parametry

      obiekt opcjonalny