chrome.debugger

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ć jedną lub więcej kart do interakcji z siecią instrumentu, debugować JavaScript, modyfikować DOM i CSS oraz wykonywać inne czynności. Użyj właściwości tabId Debuggee, aby kierować reklamy na karty z użyciem parametru sendCommand, i kieruj zdarzenia według parametru tabId z wywołań onEvent.

Uprawnienia

debugger

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

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

Pojęcia i zastosowanie

Po połączeniu interfejs API chrome.debugger umożliwia wysyłanie poleceń protokołu narzędzi deweloperskich w Chrome (CDP) do określonego celu. Szczegółowy opis platformy CDP wykracza poza zakres tej dokumentacji. Aby dowiedzieć się więcej o tej usłudze, zapoznaj się z oficjalną dokumentacją CDP.

Cele

Docelowe to elementy, które są debugowane, np. karta, iframe lub worker. Każdy cel jest identyfikowany za pomocą identyfikatora UUID i ma powiązany typ (np. iframe, shared_worker i inne).

W ramach celu może występować wiele kontekstów wykonywania – na przykład iframe’y w tym samym procesie nie mają unikalnego celu, ale są reprezentowane jako różne konteksty, do których można uzyskać dostęp z jednego celu.

Domeny z ograniczeniami

Ze względów bezpieczeństwa interfejs API chrome.debugger nie zapewnia dostępu do wszystkich domen protokołów w narzędziach dewelopera Chrome. Dostępne domeny to: Dostępność, audyt, CacheStorage, konsola, CSS, baza danych, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio i WebAuthn.

Praca z ramkami

Nie ma mapowania ramek na jeden do jednego na cele. Na jednej karcie może być wiele ramek tego samego procesu, które mają ten sam element docelowy, ale używają różnych kontekstów wykonania. Z drugiej strony nowy cel może zostać utworzony dla ramki iframe spoza procesu.

Aby dołączyć do wszystkich ramek, musisz osobno obsłużyć każdy typ ramki:

• Nasłuchuj zdarzenia Runtime.executionContextCreated, aby identyfikować nowe konteksty wykonywania powiązane z tymi samymi ramkami procesu.

• Aby dołączyć do powiązanych celów, wykonaj czynności, które pozwolą zidentyfikować ramki poza procesem.

Dołączanie do powiązanych celów

Po połączeniu się z docelową strukturą możesz połączyć się z dalszymi powiązanymi celami, w tym z ramami podrzędnymi poza procesem lub powiązanymi pracownikami.

Od wersji 125 Chrome interfejs API chrome.debugger obsługuje sesje płaskie. Dzięki temu możesz dodawać dodatkowe cele jako podrzędne do głównej sesji debugera i wysyłać do nich wiadomości bez konieczności ponownego wywołania funkcji chrome.debugger.attach. Zamiast tego możesz dodać właściwość sessionId podczas wywołania funkcji chrome.debugger.sendCommand, aby wskazać obiekt podrzędny, do którego chcesz wysłać polecenie.

Aby automatycznie dołączać do procesów potomnych ramki podrzędne spoza procesu, 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 }]
});

Funkcja automatycznego dołączania działa tylko w przypadku klatek, które są widoczne dla obiektu docelowego. Ogranicza się to do klatek, które są bezpośrednimi podrzędnymi klatek powiązanych z tym obiektem. Na przykład w hierarchii ramek A -> B -> C (gdzie wszystkie są w różnych domenach) wywołanie funkcji Target.setAutoAttach dla celu powiązanego z ramką A spowoduje również dołączenie sesji do ramki B. Nie jest to jednak funkcja rekurencyjna, więc aby B mogło połączyć sesję z C, musi też wywołać funkcję Target.setAutoAttach.

Przykłady

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

Typy

Debuggee

Identyfikator debugowanego obiektu. Należy podać identyfikator tabId, extensionId lub targetId

Właściwości

• extensionId

  string opcjonalny

  Identyfikator rozszerzenia, które chcesz debugować. Dołączanie do strony w tle 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

  string opcjonalny

  Nieprzejrzysty identyfikator debugowanego celu.

DebuggerSession

Chrome w wersji 125 lub nowszej

Identyfikator sesji debugera. Należy podać jeden z tych atrybutów: tabId, extensionId lub targetId. Dodatkowo można podać opcjonalny identyfikator sesji (sessionId). Jeśli w przypadku argumentów wysyłanych z onEvent podany jest identyfikator sessionId, oznacza to, że zdarzenie pochodzi z sesji podrzędnej protokołu w ramach sesji debugowania głównej. Jeśli parametr sessionId jest przekazywany do funkcji sendCommand, jest kierowany na sesję podrzędnego protokołu w ramach sesji debugowania głównego.

Właściwości

• extensionId

  string opcjonalny

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

• sessionId

  string opcjonalny

  Nieprzejrzysty identyfikator sesji protokołu Narzędzi deweloperskich w Chrome. Identyfikuje sesję podrzędną w sesji głównej z identyfikatorem tabId, extensionId lub targetId.

• tabId

  number opcjonalny

  Identyfikator karty, którą chcesz debugować.

• targetId

  string opcjonalny

  Nieprzejrzysty identyfikator debugowanego celu.

DetachReason

Chrome 44 lub nowszy

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

  Prawda, jeśli debuger jest już podłączony.

• extensionId

  string opcjonalny

  Identyfikator rozszerzenia określony w przypadku wartości „background_page” w polu „type”.

• faviconUrl

  string opcjonalny

  Adres URL docelowej favikony.

• id

  ciąg znaków

  Identyfikator celu.

• tabId

  numer opcjonalny

  Identyfikator karty zdefiniowany, jeśli typ to „page” (strona).

• tytuł

  ciąg znaków

  Tytuł strony docelowej.

• typ

  TargetInfoType

  Typ celu.

• URL

  ciąg znaków

  Docelowy adres URL.

TargetInfoType

Chrome 44 lub nowszy

Typ celu.

Typ wyliczeniowy

„page”

"background_page"

"worker"

"inne"

Metody

attach()

Obietnice

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

Dołącza debuger do danego elementu docelowego.

Parametry

• cel

  Debuggee

  Debugowany element, do którego chcesz się podłączyć.

• requiredVersion

  ciąg znaków

  Wymagana wersja protokołu debugowania („0.1”). Można się podłączyć tylko do debugowanego procesu z odpowiednią wersją główną i co najmniej taką samą wersją podrzędną. Listę wersji protokołów znajdziesz tutaj.

• callback

  function opcjonalny

  Parametr callback ma postać:

  () => void

Zwroty

• Obietnica<void>

  Chrome 96 i nowsze

  Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

detach()

Obietnice

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

Odłącza debuger od podanego celu.

Parametry

• cel

  Debuggee

  debugowanie celu, od którego chcesz się odłączyć;

• callback

  function opcjonalny

  Parametr callback ma postać:

  () => void

Zwroty

• Obietnica<void>

  Chrome 96 i nowsze

  Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

getTargets()

Obietnice

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

Zwraca listę dostępnych miejsc docelowych debugowania.

Parametry

• callback

  function opcjonalny

  Parametr callback ma postać:

  (result: TargetInfo[]) => void

  • wynik

    TargetInfo[]

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

Zwroty

• Promise<TargetInfo[]>

  Chrome 96 i nowsze

  Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji wywołania zwrotnego.

sendCommand()

Obietnice

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 wysłać polecenie.

• method

  ciąg znaków

  Nazwa metody. Powinna to być jedna z metod zdefiniowanych przez protokół zdalnego debugowania.

• commandParams

  object opcjonalne

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

• callback

  function opcjonalny

  Parametr callback ma postać:

  (result?: object) => void

  • wynik

    object opcjonalne

    Obiekt JSON z odpowiedzią. Struktura odpowiedzi różni się w zależności od nazwy metody i jest definiowana przez atrybut „zwraca” w opisie polecenia w protokole zdalnego debugowania.

Zwroty

• Obiet albo undefined<object | undefined>

  Chrome 96 i nowsze

  Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnicy zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onDetach

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

Wywoływane, gdy przeglądarka kończy sesję debugowania na karcie. Dzieje się tak, gdy karta jest zamykana lub gdy na załączonej karcie wywoływane są narzędzia programistyczne Chrome.

Parametry

• callback

  funkcja

  Parametr callback ma postać:

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

  • źródło

    Debuggee

  • reason

    DetachReason

onEvent

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

Wywoływane, gdy debugowany obiekt wywołuje zdarzenie pomiaru.

Parametry

• callback

  funkcja

  Parametr callback ma postać:

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

  • źródło

    DebuggerSession

  • method

    ciąg znaków

  • params

    object opcjonalne