Эта страница переведена с помощью Cloud Translation API.

chrome.debugger

Описание

API chrome.debugger служит альтернативным транспортом для протокола удаленной отладки Chrome. Используйте chrome.debugger для подключения к одной или нескольким вкладкам для управления сетевым взаимодействием, отладки JavaScript, изменения DOM и CSS и многого другого. Используйте свойство tabId Debuggee для выбора вкладок с помощью sendCommand и маршрутизации событий по tabId из обратных вызовов onEvent .

Разрешения

debugger

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

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

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

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

Цели

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

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

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

По соображениям безопасности API chrome.debugger не предоставляет доступ ко всем доменам протокола Chrome DevTools. Доступные домены: доступность , аудит , CacheStorage , консоль , CSS , база данных , отладчик , DOM , DOMDebugger , DOMSnapshot , эмуляция , выборка, ввод- вывод , ввод , инспектор , журнал , сеть , наложение , страница , производительность , профилировщик , среда выполнения , хранилище. , 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 }]
});

Примеры

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

Типы

Debuggee

Идентификатор отладчика. Необходимо указать tabId, ExtensionId или TargetId.

Характеристики

идентификатор расширения
строка необязательна
Идентификатор расширения, которое вы собираетесь отлаживать. Присоединение к фоновой странице расширения возможно только при использовании переключателя командной строки --silent-debugger-extension-api .
идентификатор табуляции
номер необязательно
Идентификатор вкладки, которую вы собираетесь отлаживать.
идентификатор цели
строка необязательна
Непрозрачный идентификатор цели отладки.

DebuggerSession

Хром 125+

Идентификатор сеанса отладчика. Необходимо указать один из tabId, ExtensionId или TargetId. Кроме того, можно указать необязательный идентификатор сеанса. Если sessionId указан для аргументов, отправленных из onEvent , это означает, что событие поступает из сеанса дочернего протокола в сеансе корневого отлаживаемого объекта. Если sessionId указан при передаче sendCommand , он нацелен на сеанс дочернего протокола в сеансе корневого отлаживаемого объекта.

Характеристики

идентификатор расширения
строка необязательна
Идентификатор расширения, которое вы собираетесь отлаживать. Присоединение к фоновой странице расширения возможно только при использовании переключателя командной строки --silent-debugger-extension-api .
идентификатор сеанса
строка необязательна
Непрозрачный идентификатор сеанса протокола Chrome DevTools. Идентифицирует дочерний сеанс в корневом сеансе, указанном tabId, ExtensionId или TargetId.
идентификатор табуляции
номер необязательно
Идентификатор вкладки, которую вы собираетесь отлаживать.
идентификатор цели
строка необязательна
Непрозрачный идентификатор цели отладки.

DetachReason

Хром 44+

Причина прекращения соединения.

Перечисление

"target_closed"

"cancelled_by_user"

TargetInfo

Отладка целевой информации

Характеристики

прикрепил
логическое значение
True, если отладчик уже подключен.
идентификатор расширения
строка необязательна
Идентификатор расширения, определенный, если type = 'background_page'.
faviconUrl
строка необязательна
Целевой URL-адрес значка.
идентификатор
нить
Идентификатор цели.
идентификатор табуляции
номер необязательно
Идентификатор вкладки, определенный, если type == 'page'.
заголовок
нить
Заголовок целевой страницы.
тип
ТаргетИнфоТип
Тип цели.
URL
нить
Целевой URL.

TargetInfoType

Хром 44+

Тип цели.

Перечисление

"страница"

"фоновая_страница"

"работник"

"другой"

Методы

attach()

Обещать

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

Присоединяет отладчик к заданной цели.

Параметры

цель
Отладчик
Цель отладки, к которой вы хотите подключиться.
требуемая версия
нить
Требуемая версия протокола отладки («0.1»). К отлаживаемому продукту можно подключиться только с соответствующей основной версией и большей или равной младшей версией. Список версий протокола можно получить здесь .
перезвонить
функция необязательна
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 96+
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

detach()

Обещать

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

Отключает отладчик от заданной цели.

Параметры

цель
Отладчик
Цель отладки, от которой вы хотите отсоединиться.
перезвонить
функция необязательна
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 96+
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getTargets()

Обещать

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

Возвращает список доступных целей отладки.

Параметры

перезвонить
функция необязательна
Параметр callback выглядит так:
```
(result: TargetInfo[]) => void
```
- результат
  ТаргетИнфо []
  Массив объектов TargetInfo, соответствующих доступным целям отладки.

Возврат

Обещание< TargetInfo []>
Хром 96+
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

sendCommand()

Обещать

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

Отправляет данную команду в цель отладки.

Параметры

цель
Сеанс отладчика
Цель отладки, которой вы хотите отправить команду.
метод
нить
Имя метода. Должен быть одним из методов, определенных протоколом удаленной отладки .
командаПарамс
объект необязательный
Объект JSON с параметрами запроса. Этот объект должен соответствовать схеме параметров удаленной отладки для данного метода.
перезвонить
функция необязательна
Параметр callback выглядит так:
```
(result?: object) => void
```
- результат
  объект необязательный
  JSON-объект с ответом. Структура ответа варьируется в зависимости от имени метода и определяется атрибутом return описания команды в протоколе удаленной отладки.

Возврат

Обещание<объект | не определено>
Хром 96+
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onDetach

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

Вызывается, когда браузер завершает сеанс отладки для вкладки. Это происходит, когда вкладка закрывается или для прикрепленной вкладки вызывается Chrome DevTools.

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(source: Debuggee, reason: DetachReason) => void
```
- источник
  Отладчик
- причина
  DetachReason

onEvent

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

Вызывается всякий раз, когда цель отладки выдает событие инструментирования.

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(source: DebuggerSession, method: string, params?: object) => void
```
- источник
  Сеанс отладчика
- метод
  нить
- параметры
  объект необязательный