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

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

  TargetInfoType

  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

  Debugowanie

  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

  Debugowanie

  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

    TargetInfo[]

    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

  DebuggerSession

  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

• wywołanie zwrotne

  funkcja

  Parametr callback wygląda tak:

  (source: Debuggee, reason: DetachReason) => void

  • source

    Debugowanie

  • powód

    DetachReason

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

    DebuggerSession

  • method

    string,

  • params

    obiekt opcjonalnie