chrome.debugger

Opis

Interfejs chrome.debugger API służy jako alternatywny transport dla protokołu zdalnego debugowania Chrome. Użyj chrome.debugger, aby dołączyć do co najmniej 1 karty 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 właściwością sendCommand i kierować zdarzenia według właściwoś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 CDP znajdziesz w oficjalnej dokumentacji CDP.

Cele

Obiekty docelowe to elementy, które są debugowane. Mogą to być karty, elementy iframe lub procesy robocze. Każdy element docelowy jest identyfikowany za pomocą identyfikatora 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 kilka 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 się 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 określić 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 docelowy element wie, czyli tylko w przypadku 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

    string 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

    string 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 podczas przekazywania do sendCommand określono sessionId, jest ono kierowane do sesji protokołu podrzędnego w sesji debugowania głównego.

Właściwości

  • extensionId

    string 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

    string 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

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

  • extensionId

    string opcjonalny

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

  • faviconUrl

    string opcjonalny

    Docelowy adres URL favikony.

  • id

    ciąg znaków

    Identyfikator miejsca docelowego.

  • tabId

    number opcjonalny

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

  • tytuł

    ciąg znaków

    Tytuł strony docelowej.

  • Typ celu.

  • URL

    ciąg znaków

    Docelowy adres 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 w wersji 96 lub nowszej

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 w wersji 96 lub nowszej

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

Zwraca listę dostępnych celów debugowania.

Zwroty

  • Promise<TargetInfo[]>

    Chrome w wersji 96 lub nowszej

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 w wersji 96 lub nowszej

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