扩展开发者工具

开发者工具扩展程序通过添加到扩展程序的开发者工具页面访问开发者工具专用扩展程序 API，从而向 Chrome 开发者工具添加功能。

架构图，显示了开发者工具页面与受检查窗口和 Service Worker 之间的通信。该图显示了 Service Worker 与内容脚本之间的通信，以及对扩展程序 API 的访问。DevTools 页面可以访问 DevTools API，例如创建面板。
开发者工具扩展程序架构。

特定于开发者工具的扩展程序 API 包括以下内容：

开发者工具页面

当开发者工具窗口打开时，开发者工具扩展程序会创建其开发者工具页面的实例，只要窗口处于打开状态，该实例就会一直存在。此页面有权访问 DevTools API 和扩展程序 API，并且可以执行以下操作：

开发者工具页面可以直接访问扩展程序 API。这包括能够使用消息传递与 Service Worker 进行通信。

创建 DevTools 扩展程序

如需为扩展程序创建开发者工具页面，请在扩展程序清单中添加 devtools_page 字段：

{
  "name": ...
  "version": "1.0",
  "devtools_page": "devtools.html",
  ...
}

devtools_page 字段必须指向 HTML 网页。由于开发者工具页面必须位于扩展程序的本地，因此我们建议使用相对网址来指定该页面。

chrome.devtools API 的成员仅在开发者工具窗口打开时可供该窗口内加载的网页使用。内容脚本和其他扩展程序页面无法访问这些 API。

开发者工具界面元素：面板和侧边栏窗格

除了常见的扩展程序界面元素（例如浏览器操作、上下文菜单和弹出式窗口）之外，开发者工具扩展程序还可以向开发者工具窗口添加界面元素：

  • 面板是指顶级标签页，例如“元素”“来源”和“网络”面板。
  • 侧边栏窗格会显示与面板相关的补充界面。“元素”面板上的“样式”“计算样式”和“事件监听器”窗格是边栏窗格的示例。根据您使用的 Chrome 版本以及开发者工具窗口的停靠位置，您的边栏窗格可能类似于以下示例图片：
开发者工具窗口，其中显示了“元素”面板和“样式”侧边栏窗格。
显示“元素”面板和“样式”边栏窗格的开发者工具窗口。

每个面板都是一个独立的 HTML 文件，可以包含其他资源（JavaScript、CSS、图片等）。如需创建基本面板，请使用以下代码：

chrome.devtools.panels.create("My Panel",
    "MyPanelIcon.png",
    "Panel.html",
    function(panel) {
      // code invoked on panel creation
    }
);

在面板或侧边栏窗格中执行的 JavaScript 可以访问与开发者工具页面相同的 API。

如需创建基本边栏窗格，请使用以下代码：

chrome.devtools.panels.elements.createSidebarPane("My Sidebar",
    function(sidebar) {
        // sidebar initialization code here
        sidebar.setObject({ some_data: "Some data to show" });
});

您可以通过以下几种方式在边栏窗格中显示内容：

  • HTML 内容：调用 setPage() 以指定要在窗格中显示的 HTML 网页。
  • JSON 数据：将 JSON 对象传递给 setObject()。
  • JavaScript 表达式：将表达式传递给 setExpression()。开发者工具会在所检查页面的上下文中评估表达式，然后显示返回值。

对于 setObject() 和 setExpression()，该窗格都会显示在开发者工具控制台中显示的值。不过，setExpression() 可让您显示 DOM 元素和任意 JavaScript 对象，而 setObject() 仅支持 JSON 对象。

在扩展组件之间通信

以下部分介绍了一些有用的方法，可让开发者工具扩展程序组件相互通信。

注入内容脚本

如需注入内容脚本，请使用 scripting.executeScript()：

// DevTools page -- devtools.js
chrome.scripting.executeScript({
  target: {
    tabId: chrome.devtools.inspectedWindow.tabId
  },
  files: ["content_script.js"]
});

您可以使用 inspectedWindow.tabId 属性检索检查窗口的标签页 ID。

如果内容脚本已注入，您可以使用消息传递 API 与其通信。

在检查窗口中评估 JavaScript

您可以使用 inspectedWindow.eval() 方法在检查页面的上下文中执行 JavaScript 代码。您可以从 DevTools 页面、面板或侧边栏窗格调用 eval() 方法。

默认情况下，表达式是在网页主框架的上下文中进行评估的。 inspectedWindow.eval() 使用与在开发者工具控制台中输入的代码相同的脚本执行上下文和选项，这使得在使用 eval() 时可以访问开发者工具控制台实用程序 API 功能。例如，使用它来检查 HTML 文档的 <head> 部分中的第一个脚本元素：

chrome.devtools.inspectedWindow.eval(
  "inspect($$('head script')[0])",
  function(result, isException) { }
);

您还可以在调用 inspectedWindow.eval() 时将 useContentScriptContext 设置为 true，以便在与内容脚本相同的上下文中评估表达式。如需使用此选项，请在调用 eval() 之前使用静态内容脚本声明，方法是调用 executeScript() 或在 manifest.json 文件中指定内容脚本。在内容脚本上下文加载后，您还可以使用此选项注入其他内容脚本。

将所选元素传递给内容脚本

内容脚本无法直接访问当前所选元素。不过，您使用 inspectedWindow.eval() 执行的任何代码都可以访问开发者工具控制台和控制台实用程序 API。例如，在评估的代码中，您可以使用 $0 访问所选元素。

如需将所选元素传递给内容脚本，请执行以下操作：

  1. 在内容脚本中创建一个方法，该方法将所选元素作为实参。

    function setSelectedElement(el) {
    // do something with the selected element
}

  2. 使用 useContentScriptContext: true 选项通过开发者工具页面调用该方法 inspectedWindow.eval()。

    chrome.devtools.inspectedWindow.eval("setSelectedElement($0)",
    { useContentScriptContext: true });

useContentScriptContext: true 选项指定表达式必须在与内容脚本相同的上下文中进行评估，因此它可以访问 setSelectedElement 方法。

获取参考面板的 window

如需从开发者工具面板调用 postMessage()，您需要引用其 window 对象。通过 panel.onShown 事件处理脚本获取面板的 iframe 窗口：

extensionPanel.onShown.addListener(function (extPanelWindow) {
    extPanelWindow instanceof Window; // true
    extPanelWindow.postMessage( // …
});

将消息从注入的脚本发送到开发者工具页面

直接注入到网页中且没有内容脚本的代码（包括通过附加 <script> 标记或调用 inspectedWindow.eval() 的代码）无法使用 runtime.sendMessage() 向开发者工具页面发送消息。我们建议您将注入的脚本与可充当中间媒介的内容脚本相结合，并使用 window.postMessage() 方法。以下示例使用上一部分中的后台脚本：

// injected-script.js

window.postMessage({
  greeting: 'hello there!',
  source: 'my-devtools-extension'
}, '*');

// content-script.js

window.addEventListener('message', function(event) {
  // Only accept messages from the same frame
  if (event.source !== window) {
    return;
  }

  var message = event.data;

  // Only accept messages that we know are ours. Note that this is not foolproof
  // and the page can easily spoof messages if it wants to.
  if (typeof message !== 'object' || message === null ||
      message.source !== 'my-devtools-extension') {
    return;
  }

  chrome.runtime.sendMessage(message);
});

您可以在 GitHub 上找到其他替代的消息传递技术。

检测开发者工具何时打开和关闭

如需跟踪开发者工具窗口是否处于打开状态，请向 Service Worker 添加 onConnect 监听器，并从开发者工具页面调用 connect()。由于每个标签页都可以打开自己的开发者工具窗口，因此您可能会收到多个连接事件。如需跟踪是否有任何开发者工具窗口处于打开状态，请统计连接和断开连接事件，如以下示例所示：

// background.js
var openCount = 0;
chrome.runtime.onConnect.addListener(function (port) {
    if (port.name == "devtools-page") {
      if (openCount == 0) {
        alert("DevTools window opening.");
      }
      openCount++;

      port.onDisconnect.addListener(function(port) {
          openCount--;
          if (openCount == 0) {
            alert("Last DevTools window closing.");
          }
      });
    }
});

DevTools 页面会创建如下连接：

// devtools.js

// Create a connection to the service worker
const serviceWorkerConnection = chrome.runtime.connect({
    name: "devtools-page"
});

// Send a periodic heartbeat to keep the port open.
setInterval(() => {
  port.postMessage("heartbeat");
}, 15000);

开发者工具扩展程序示例

本页中的示例来自以下页面：

  • Polymer Devtools 扩展程序 - 使用在宿主网页中运行的许多辅助程序来查询 DOM/JS 状态，以便发送回自定义面板。
  • React DevTools 扩展程序 - 使用渲染器的子模块来重用开发者工具界面组件。
  • Ember Inspector - 共享的扩展程序核心，包含适用于 Chrome 和 Firefox 的适配器。
  • Coquette-inspect - 一款基于 React 的简洁扩展程序，可将调试代理注入到宿主页面中。
  • 示例扩展程序包含更多值得安装、试用和学习的扩展程序。

更多信息

如需了解扩展程序可使用的标准 API，请参阅 chrome.* API 和 Web API。

欢迎提供反馈意见！您的意见和建议有助于我们改进 API。

示例

您可以在示例中找到使用开发者工具 API 的示例。