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ć do jednej lub kilku kart i instrumentować interakcje sieciowe, debugować JavaScript, modyfikować DOM i CSS oraz wykonywać inne czynności. Użyj właściwości Debuggee tabId, aby kierować zdarzenia na karty z wartością sendCommand i kierować zdarzenia według wartości tabId z wywołań zwrotnych onEvent.

Uprawnienia

debugger

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

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

Pojęcia i zastosowanie

Po dołączeniu chrome.debugger API umożliwia wysyłanie poleceń protokołu Narzędzi deweloperskich w Chrome (CDP) do danego miejsca docelowego. Szczegółowe wyjaśnienie działania platformy CDP wykracza poza zakres tej dokumentacji. Więcej informacji o platformie CDP znajdziesz w oficjalnej dokumentacji.

Cele

Obiekty docelowe to elementy, które są debugowane. Mogą to być karty, ramki iframe lub procesy robocze. Każdy element docelowy jest identyfikowany przez UUID i ma powiązany typ (np. iframe, shared_worker itp.).

W ramach jednego miejsca docelowego może występować wiele kontekstów wykonania. Na przykład ramki iframe w tym samym procesie nie otrzymują unikalnego miejsca docelowego, ale są reprezentowane jako różne konteksty, do których można uzyskać dostęp z jednego miejsca docelowego.

Domeny z ograniczeniami

Ze względów bezpieczeństwa interfejs chrome.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, Profiler, 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ć ramki poza procesem, wykonaj czynności opisane w sekcji Dołączanie do powiązanych elementów docelowych.

Po połączeniu z celem możesz połączyć się z kolejnymi powiązanymi celami, w tym z ramkami podrzędnymi działającymi poza procesem lub powiązanymi procesami roboczymi.

Od Chrome 125 interfejs chrome.debugger API obsługuje sesje płaskie. Dzięki temu możesz dodawać dodatkowe elementy docelowe jako podrzędne do głównej sesji debugowania i wysyłać do nich wiadomości bez konieczności wykonywania kolejnego wywołania funkcji chrome.debugger.attach. Zamiast tego możesz dodać właściwość sessionId podczas wywoływania funkcji chrome.debugger.sendCommand, aby zidentyfikować docelowe urządzenie dziecka, do którego chcesz wysłać polecenie.

Aby automatycznie dołączać do ramek podrzędnych działających 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 }]
});

Automatyczne dołączanie działa tylko w przypadku ramek, o których wie element docelowy. Dotyczy to tylko ramek, które są bezpośrednimi elementami podrzędnymi ramki powiązanej z tym elementem. Na przykład w hierarchii ramek A –> B –> C (gdzie wszystkie są z innej domeny) wywołanie Target.setAutoAttach w przypadku elementu docelowego powiązanego z ramką A spowoduje, że sesja zostanie też dołączona do ramki B. Nie jest to jednak funkcja rekurencyjna, więc w przypadku połączenia B z C należy też wywołać funkcję Target.setAutoAttach.

Przykłady

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

Typy

Debuggee

Identyfikator debugowanego obiektu. Należy określić 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 debugowanego celu.

DebuggerSession

Chrome 125 lub nowsza

Identyfikator sesji debugera. Musisz określić 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 identyfikator sessionId jest określony podczas przekazywania do funkcji sendCommand, jest on kierowany 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. Wskazuje 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 debugowanego celu.

DetachReason

Chrome 44 lub nowszy

Przyczyna zakończenia połączenia.

Typ wyliczeniowy

„target_closed”

„canceled_by_user”

TargetInfo

Informacje o obiekcie debugowania

Właściwości

  • podłączony

    Wartość logiczna

    Wartość Prawda, jeśli debuger jest już dołączony.

  • extensionId

    ciąg znaków opcjonalny

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

  • faviconUrl

    ciąg znaków opcjonalny

    Docelowy adres URL favikony.

  • id

    ciąg znaków

    Identyfikator miejsca docelowego.

  • tabId

    number opcjonalny

    Identyfikator karty, zdefiniowany, jeśli typ == „page”.

  • tytuł

    ciąg znaków

    Tytuł strony docelowej.

  • Typ celu.

  • URL

    ciąg znaków

    Docelowy URL.

TargetInfoType

Chrome 44 lub nowszy

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 elementu docelowego.

Parametry

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

  • requiredVersion

    ciąg znaków

    Wymagana wersja protokołu debugowania („0.1”). Do debugowanego programu można dołączyć tylko debuger o pasującej wersji głównej i wersji podrzędnej równej lub nowszej. Listę wersji protokołu znajdziesz tutaj.

Zwroty

  • Promise<void>

    Chrome 96 lub nowsza wersja

    Zwraca obietnicę po zakończeniu operacji dołączania (powodzeniem lub niepowodzeniem). Obietnica zostaje 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

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

Zwroty

  • Promise<void>

    Chrome 96 lub nowsza wersja

    Zwraca obietnicę po zakończeniu operacji odłączania (powodzeniem lub niepowodzeniem). Obietnica zostaje 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 wersja

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

Wysyła podane polecenie do celu debugowania.

Parametry

  • 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

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

    Treść odpowiedzi. Jeśli podczas publikowania wiadomości wystąpi błąd, obietnica zostanie odrzucona.

Wydarzenia

onDetach

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

Uruchamiane, gdy przeglądarka zakończy sesję debugowania karty. Dzieje się tak, gdy zamykana jest karta lub gdy w przypadku dołączonej karty wywoływane są Narzędzia deweloperskie w Chrome.

Parametry

onEvent

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

Uruchamiane za każdym razem, gdy wystąpi zdarzenie instrumentacji związane z problemami z elementem docelowym debugowania.

Parametry

  • callback

    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