开发者工具可通过添加到 Chrome 开发者工具中的页面来访问开发者工具专用的扩展程序 API,从而为 Chrome 开发者工具添加功能。
特定于开发者工具的扩展程序 API 包含以下内容:
“开发者工具”页面
当开发者工具窗口打开时,开发者工具扩展程序会创建一个其开发者工具页面实例,只要窗口处于打开状态,该页面就会一直存在。此页面可以访问开发者工具 API 和扩展程序 API,还可以执行以下操作:
- 使用
devtools.panels
API 创建面板并与之互动,包括将其他扩展程序页面作为面板或边栏添加到开发者工具窗口。 - 使用
devtools.inspectedWindow
API 获取所检查窗口的相关信息,并评估所检查窗口中的代码。 - 使用
devtools.network
API 获取有关网络请求的信息。 - 使用
devtools.recorder
API 扩展“Recorder”面板。
“开发者工具”页面可以直接访问扩展程序 API。这包括能够使用消息传递与 Service Worker 通信。
创建开发者工具扩展程序
如需为您的扩展程序创建开发者工具页面,请在扩展程序清单中添加 devtools_page
字段:
{
"name": ...
"version": "1.0",
"devtools_page": "devtools.html",
...
}
devtools_page
字段必须指向 HTML 网页。由于开发者工具页面必须是您的扩展程序的本地页面,因此我们建议您使用相对网址指定该页面。
chrome.devtools
API 的成员仅适用于在开发者工具窗口中加载的页面(当该窗口打开时)。内容脚本和其他扩展程序页面无权访问这些 API。
DevTools 界面元素:面板和边栏窗格
除了常见的扩展程序界面元素(例如浏览器操作、上下文菜单和弹出式窗口)之外,DevTools 扩展程序还可以向开发者工具窗口添加界面元素:
- 面板是顶级标签页,如“元素”“来源”和“网络”面板。
- 边栏窗格会显示与面板相关的补充界面。“元素”面板上的“样式”“计算的样式”和“事件监听器”窗格都是边栏窗格的示例。您的边栏窗格可能如以下示例图片所示,具体取决于您使用的 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 代码。您可以从开发者工具页面、面板或边栏窗格调用 eval()
方法。
默认情况下,系统会在页面的主框架上下文中对表达式求值。
inspectedWindow.eval()
使用与在开发者工具控制台中输入的代码相同的脚本执行上下文和选项,以允许在使用 eval()
时访问开发者工具 Console Utilities API 功能。例如,SOAK 使用它来检查元素:
chrome.devtools.inspectedWindow.eval(
"inspect($$('head script[data-soak=main]')[0])",
function(result, isException) { }
);
您也可以在调用 inspectedWindow.eval()
时将 useContentScriptContext
设置为 true
,以便在与内容脚本相同的上下文中评估表达式。如需使用此选项,请在调用 eval()
之前使用静态内容脚本声明,具体方法是调用 executeScript()
或在 manifest.json
文件中指定内容脚本。上下文脚本上下文加载后,您还可以使用此选项注入其他内容脚本。
将所选元素传递到内容脚本
内容脚本无法直接访问当前所选元素。不过,您使用 inspectedWindow.eval()
执行的任何代码都可以访问开发者工具控制台和控制台实用程序 API。例如,在求值代码中,您可以使用 $0
访问所选元素。
如需将所选元素传递到内容脚本,请执行以下操作:
在内容脚本中创建一个将所选元素作为参数的方法。
function setSelectedElement(el) { // do something with the selected element }
使用带有
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.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 Extension - 使用在托管网页中运行的多个帮助程序来查询 DOM/JS 状态,并将其发送回自定义面板。
- React DevTools Extension - 使用渲染程序的子模块来重复使用开发者工具界面组件。
- Ember Inspector - 带有适用于 Chrome 和 Firefox 的适配器的共享扩展程序核心。
- Coquette-inspect - 基于 React 的整洁扩展程序,已将调试代理注入主机页面。
- 示例扩展程序会提供更多值得安装、试用和学习的扩展程序。
更多信息
要了解扩展程序可以使用的标准 API,请参阅 chrome.* API 和 Web API。
向我们提供反馈!您的意见和建议有助于我们改进 API。
示例
您可以在示例中找到使用开发者工具 API 的示例。