chrome.debugger

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 jednej lub kilku kart do obsługi interakcji z siecią, debugowania JavaScript, mutacji DOM i CSS itp. Użyj interfejsu Debuggee tabId, aby ustawić kierowanie na karty z sendCommand i kierowanie zdarzeń tabId z wywołań zwrotnych onEvent.

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.

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

Chrome 125 i nowsze wersje

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

Chrome 44 i nowsze wersje

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

Chrome 44 i nowsze wersje

Typ docelowy.

Typ wyliczeniowy

"background_page"

Metody

attach()

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

Dołącza debuger do podanego celu.

Parametry

  • 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 wersje

    Obietnice 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()

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

Odłącza debuger od podanego celu.

Parametry

  • 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 wersje

    Obietnice 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()

Obietnica
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 wersje

    Obietnice 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()

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

Wysyła podane polecenie do celu debugowania.

Parametry

  • 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 wersje

    Obietnice 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

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