Расширение инструментов разработчика

Примечание: Эта страница описывает API инструментов разработчика, как они существуют в Firefox 55. Хотя API основаны на API инструментов разработчика Chrome, всё ещё много функций не реализовано в Firefox и, следовательно, здесь не документированы. Чтобы увидеть, какие функции отсутствуют, обратитесь к разделу Ограничения API инструментов разработчика.

Вы можете использовать API WebExtensions для расширения встроенных инструментов разработчика браузера. Чтобы создать расширение инструментов разработчика, включите ключ "devtools_page" в manifest.json:

"devtools_page": "devtools/devtools-page.html"

Значение этого ключа — URL, указывающий на HTML-файл, который включён в ваше расширение. URL должен быть относительным к файлу manifest.json.

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

Страница инструментов разработчика

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

На странице инструментов разработчика нет видимого DOM, но она может содержать JavaScript-источники с помощью <script> тегов. Источники должны быть включены в само расширение. Источники получают доступ к:

Обычным API DOM, доступным через глобальный объект window
Тем же API WebExtension, что и в скриптах содержимого
API инструментов разработчика:

Обратите внимание, что страница инструментов разработчика не получает доступа к другим API WebExtension, и страница фонового процесса не получает доступа к API инструментов разработчика. Вместо этого страница инструментов разработчика и страница фонового процесса должны обмениваться данными с помощью API обмена сообщениями runtime. Вот пример:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>DevTools Extension</title>
  </head>
  <body>
    <script src="devtools.js"></script>
  </body>
</html>

Файл devtools.js будет содержать фактический код, создающий ваши расширения инструментов разработчика.

Создание панелей

Окно инструментов разработчика содержит ряд отдельных инструментов — отладчик JavaScript, монитор сети и так далее. Строка вкладок в верхней части позволяет пользователю переключаться между различными инструментами. Окно, содержащее пользовательский интерфейс каждого инструмента, называется "панелью".

Используя API devtools.panels.create(), вы можете создать свою собственную панель в окне инструментов разработчика:

browser.devtools.panels.create(
  "My Panel",                      // title
  "/icons/star.png",               // icon
  "/devtools/panel/panel.html"     // content
).then((newPanel) => {
  newPanel.onShown.addListener(initialisePanel);
  newPanel.onHidden.addListener(unInitialisePanel);
});

Это принимает три обязательных аргумента: заголовок панели, значок и содержимое. Он возвращает Promise, который разрешается в объект devtools.panels.ExtensionPanel, представляющий новую панель.

Взаимодействие с целевым окном

Инструменты разработчика всегда привязаны к конкретной вкладке браузера. Это называется "целью" для инструментов разработчика или "окном, которое просматривается". Вы можете взаимодействовать с окном, которое просматривается, с помощью API devtools.inspectedWindow.

Запуск кода в целевом окне

API devtools.inspectedWindow.eval() предоставляет один способ запуска кода в просматриваемом окне.

Это несколько похоже на использование tabs.executeScript() для вставки скрипта содержимого, но с одним важным отличием:

в отличие от скриптов содержимого, скрипты, загруженные с помощью devtools.inspectedWindow.eval(), не получают «чистый вид DOM»: то есть они могут видеть изменения на странице, внесённые скриптами страницы.

Примечание: «Чистый вид DOM» — это функция безопасности, призванная предотвратить злонамеренным страницам обманывать расширения, переопределяя поведение функций DOM. Это означает, что вам нужно быть очень осторожным при использовании eval() и использовать обычный скрипт содержимого, если это возможно.

Скрипты, загруженные с помощью devtools.inspectedWindow.eval(), также не видят никаких JavaScript-переменных, определённых скриптами содержимого.

Работа со скриптами содержимого

Документ инструментов разработчика не имеет прямого доступа к tabs.executeScript(), поэтому, если вам нужно вставить скрипт содержимого, документ инструментов разработчика должен отправить сообщение скрипту фонового процесса, попросив его вставить скрипт. devtools.inspectedWindow.tabId предоставляет идентификатор целевой вкладки: документ инструментов разработчика может передать его скрипту фонового процесса, а скрипт фонового процесса, в свою очередь, может передать его в tabs.executeScript():

// devtools-panel.js

const scriptToAttach = "document.body.innerHTML = 'Hi from the devtools';";

window.addEventListener("click", () => {
  browser.runtime.sendMessage({
    tabId: browser.devtools.inspectedWindow.tabId,
    script: scriptToAttach
  });
});

// background.js

function handleMessage(request, sender, sendResponse) {
  browser.tabs.executeScript(request.tabId, {
    code: request.script
  });
}

browser.runtime.onMessage.addListener(handleMessage);

Если вам нужно обмениваться сообщениями между скриптами содержимого, выполняемыми в целевом окне, и документом инструментов разработчика, рекомендуется использовать runtime.connect() и runtime.onConnect для установки подключения между страницей фонового процесса и документом инструментов разработчика. Страница фонового процесса может затем поддерживать отображение соответствий между идентификаторами вкладок и объектами runtime.Port, и использовать это для маршрутизации сообщений между двумя областями.

The background page tab ID is connected to the content script on the content page by a runtime.sendmessage() object. The Port of the background page is connected to the port of the Devtools document by a port.postMessage() object.

Ограничения API инструментов разработчика

Эти API основаны на API инструментов разработчика Chrome, но многие функции всё ещё отсутствуют по сравнению с Chrome. В этом разделе перечислены функции, которые ещё не реализованы, по состоянию на Firefox 54. Обратите внимание, что API инструментов разработчика активно развиваются, и мы ожидаем добавить поддержку большинства из них в будущих выпусках.

devtools.inspectedWindow

Следующее не поддерживается:

inspectedWindow.getResources()
inspectedWindow.onResourceAdded
inspectedWindow.onResourceContentCommitted

Ни один из вариантов для inspectedWindow.eval() не поддерживается.

Скрипты, вставленные с помощью inspectedWindow.eval(), не могут использовать все вспомогательные функции командной строки консоли, но $0 и inspect() поддерживаются (начиная с Firefox 55).

devtools.panels

Следующее не поддерживается:

panels.elements
panels.sources
panels.setOpenResourceHandler()
panels.openResource()
panels.ExtensionPanel.createStatusBarButton()
panels.Button
panels.ElementsPanel
panels.SourcesPanel

Примеры

Репозиторий webextensions-examples на GitHub содержит несколько примеров расширений, которые используют панели инструментов разработчика:

devtools-panels используют панели инструментов разработчика:

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools