chrome.debugger

Описание

Разрешения

Для использования этого API необходимо объявить разрешение "debugger" в манифесте вашего расширения.

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

Концепции и использование

После подключения API chrome.debugger позволяет отправлять команды Chrome DevTools Protocol (CDP) заданному целевому объекту. Подробное описание CDP выходит за рамки данной документации. Подробнее о CDP можно узнать в официальной документации CDP .

Цели

Цели представляют собой отлаживаемый объект, например вкладку, iframe или воркер. Каждая цель идентифицируется UUID и имеет связанный с ней тип (например, iframe , shared_worker и т. д.).

В рамках одной цели может быть несколько контекстов выполнения — например, одни и те же фреймы процесса не получают уникальную цель, а вместо этого представлены как разные контексты, к которым можно получить доступ из одной цели.

Ограниченные домены

Из соображений безопасности API chrome.debugger не предоставляет доступ ко всем доменам протокола Chrome DevTools. Доступны следующие домены: 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 и WebAuthn .

Работа с кадрами

Кадры не имеют однозначного соответствия с целями. В пределах одной вкладки несколько кадров одного и того же процесса могут использовать одну и ту же цель, но разный контекст выполнения . С другой стороны, для внепроцессного iframe может быть создана новая цель.

Чтобы прикрепить ко всем рамкам, необходимо обрабатывать каждый тип рамы отдельно:

• Прослушивайте событие Runtime.executionContextCreated , чтобы определить новые контексты выполнения, связанные с теми же кадрами процесса.

• Выполните шаги по присоединению к связанным целям , чтобы определить кадры, выходящие за рамки процесса.

Прикрепить к связанным целям

После подключения к цели вам может потребоваться подключиться к другим связанным целям, включая дочерние фреймы вне процесса или связанные с ними рабочие процессы.

Начиная с Chrome 125, API chrome.debugger поддерживает плоские сеансы. Это позволяет добавлять дополнительные цели в качестве дочерних элементов к основному сеансу отладчика и отправлять им сообщения без необходимости повторного вызова chrome.debugger.attach . Вместо этого можно добавить свойство sessionId при вызове chrome.debugger.sendCommand , чтобы указать дочернюю цель, которой требуется отправить команду.

Чтобы автоматически прикрепляться к дочерним фреймам вне процесса, сначала добавьте прослушиватель для события 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");   } }); 

Затем включите автоматическое присоединение , отправив команду Target.setAutoAttach с опцией flatten , установленной на true :

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {   autoAttach: true,   waitForDebuggerOnStart: false,   flatten: true,   filter: [{ type: "iframe", exclude: false }] }); 

Функция автоматического присоединения прикрепляется только к кадрам, о которых знает целевой объект, то есть к кадрам, являющимся непосредственными потомками связанного с ним объекта. Например, при иерархии фреймов A -> B -> C (где все фреймы кросс-источниковые), вызов Target.setAutoAttach для целевого объекта, связанного с A, приведёт к тому, что сеанс также будет прикреплён к объекту B. Однако это не рекурсивно, поэтому для присоединения сеанса к объекту C также необходимо вызвать Target.setAutoAttach для объекта B.

Примеры

Чтобы опробовать этот API, установите пример API отладчика из репозитория chrome-extension-samples .

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

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

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

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

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