{{obsolete_header()}}
{{ warning("DevTools APIはまだWIPです。 矛盾がある場合は、Firefox Developer Toolsチームにお知らせください。") }}
この API は現在進行中ですが、現在使用可能なページインスペクタとデバッガの使用可能な部分があります。
DevTools API は、Firefox の開発者ツールを登録してアクセスする方法を提供します。
In terms of User Interface, each registered tool lives in its own tab (we call one tab a panel). These tabs are located in a box we call a Toolbox. A toolbox can be hosted within a browser tab (at the bottom or on the side), or in its own window (we say that the toolbox is undocked). A Toolbox (and all the tools it contains) is linked to a Target, which is the object the tools are debugging. A target is usually a web page (a tab), but can be other things (a chrome window, a remote tab,…).
In terms of code, each tool has to provide a ToolDefinition object. A definition is a JS light object that exposes different information about the tool (like its name and its icon), and a build method that will be used later-on to start an instance of this tool. The gDevTools global object provides methods to register a tool definition and to access tool instances. An instance of a tool is called a ToolPanel. The ToolPanel is built only when the tool is selected (not when the toolbox is opened). There is no way to "close/destroy" a ToolPanel. The only way to close a toolPanel is to close its containing toolbox. All these objects implement the EventEmitter interface.
The gDevTools API can be used to register new tools, themes and handle toolboxes for different tabs and windows. To use the gDevTools API from an add-on, it can be imported with following snippet
const { gDevTools } = require("resource:///modules/devtools/gDevTools.jsm");registerTool(toolDefinition)toolDefinition {ToolDefinition} - An object that contains information about the tool. See {{anch("ToolDefinition")}} for details.unregisterTool(tool)tool {ToolDefinition|String} - The tool definition object or the id of the tool to unregister.registerTheme(themeDefinition)themeDefinition {ThemeDefinition} - An object that contains information about the theme.unregisterTheme(theme)theme {ThemeDefinition|String} - The theme definition object or the theme identifier.showToolbox(target [, toolId [, hostType [, hostOptions]]])target {Target} - The target the toolbox will debug.toolId {String} - The tool that should be activated. If unspecified the previously active tool is shown.hostType {String} - The position the toolbox will be placed. One of bottom, side, window, custom. See {{anch("HostType")}} for details.hostOptions {Object} - An options object passed to the selected host. See {{anch("HostType")}} for details.getToolbox(target)target {Target} - The target the toolbox is debugging.closeToolbox(target)target {Target} - The target of the toolbox that should be closed.getDefaultTools()getAdditionalTools()getToolDefinition(toolId)toolId {String} - The ID of the tool.getToolDefinitionMap()getToolDefinitionArray()getThemeDefinition(themeId)ThemeDefinition object for the theme with the given id.themeId {String} - The ID of the theme.ThemeDefinition object if the theme exists, null otherwise.getThemeDefinitionMap()ThemeDefinition map for available themes.getThemeDefinitionArray()ThemeDefinition objects for avialble themes.Following events are emitted by the gDevTools object via the {{anch("EventEmitter")}} interface.
tool-registered(toolId)tool-unregistered(tool)theme-registered(themeId)theme-unregistered(theme)ThemeDefinition object.toolbox-ready(toolbox)toolbox-destroy(target)toolbox-destoyed(target){toolId}-init(toolbox, iframe){toolId}-build(toolbox, panel)ToolDefinition.build() method.{toolId}-ready(toolbox, panel)ToolDefinition.build() method.{toolId}-destroy(toolbox, panel)ToolDefinition.build() method.A Toolbox is a frame for the {{anch("ToolPanel", "ToolPanels")}} that is debugging a specific target.
targethostTypeToolbox.HostType constants.zoomValueThe Toolbox constructor contains following constant properties.
Toolbox.HostType.BOTTOMToolbox.HostType.SIDEToolbox.HostType.WINDOWToolbox.HostType.CUSTOMgetCurrentPanel()getPanel(toolId)toolId {String} - The tool identifier.toolId is active, otherwise undefined.getPanelWhenReady(toolId)getPanel() but waits for the tool to load first. If the tool is not already loaded or currently loading the returned {{domxref("Promise")}} won't be fulfilled until something triggers the tool to load.toolId {String} - The tool identifier.getToolPanels()toolId → {{anch("ToolPanel")}} {{jsxref("Map")}} for currently loaded tools.getNotificationBox()loadTool(toolId)toolId in the background but does not activate it.toolId {String} - The tool identifier.selectTool(toolId)toolId.toolId {String} - The tool identifier.selectNextTool()Toolbox.selectPreviousTool()Toolbox.highlightTool(toolId)toolId {String} - The tool to highlight.unhighlightTool(toolId)toolId {String} - The tool to unhighlight.openSplitConsole()closeSplitConsole()toggleSplitConsole()switchHost(hostType)hostType {Toolbox.HostType} - The type of the new host.reloadTarget(force)force {Boolean} - If true the target is shift-reloaded i.e. the cache is bypassed during the reload.zoomIn()Toolbox document.zoomOut()Toolbox document.zoomReset()Toolbox document.setZoom(value)value {Number} - The zoom level such as 1.2.destroy()Toolbox is destroyed.The Toolbox object emits following events via the {{anch("EventEmitter")}} interface.
host-changedreadyToolbox is ready to use.select(toolId){toolId}-selected event.{toolId}-init(frame){toolId}-build(panel){toolId}-ready(panel){toolId}-selected(panel){toolId}-destroy(panel)destroyToolbox is about to be destroyed.destroyedToolbox has been destroyed.A ToolDefinition object contains all the required information for a tool to be shown in the toolbox.
isTargetSupported(target)target {Target} - The target to check.build(window, toolbox)window {Window} - The {{domxref("Window")}} object for frame the tool is being built into.toolbox {Toolbox} - The {{anch("Toolbox")}} the tool is being built for.onKey(panel, toolbox)panel {ToolPanel} - The {{anch("ToolPanel")}} for the tool.toolbox {Toolbox} - The toolbox for the shortcut was triggered for.The ToolDefinition object can contain following properties. Most of them are optional and can be used to customize the presense of the tool in the Browser and the Toolbox.
idurllabelicon should be specified.tooltippanelLabelordinalvisibilityswitchdevtools.{id}.enablediconhighlightedicon{icon}iconOnlyinvertIconForLightThemekeymodifierspreventClosingOnKeyinMenumenuLabel{label}accesskeyHere's a minimal definition for a tool.
let def = {
id: "my-tool",
label: "My Tool",
icon: "chrome://browser/skin/devtools/tool-webconsole.svg",
url: "about:blank",
isTargetSupported: target => true,
build: (window, toolbox) => new MyToolPanel(window, toolbox)
};
// Register it.
gDevTools.registerTool(def);
FIXME:
FIXME
The ToolPanel is an interface the toolbox uses to manage the panel of a tool. The object that ToolDefinition.build() returns should implement the methods described below.
open()toolbox.selectTool()) and events (e.g. {{anch("toolbox-ready(toolbox)", "toolbox-ready")}}) are delayed until the promise has been fulfilled.ToolPanel object once it's ready to be used.destroy()A method that is called when the toolbox is closed or the tool is unregistered. If the tool needs to perform asynchronous operations during destruction the method should return a {{domxref("Promise")}} that is resolved once the process is complete.
Return value:
A {{domxref("Promise")}} if the function performs asynchronous operations, otherwise undefined.
Here's a basic template for a ToolPanel implementation.
// In the ToolDefintion object, do
// build: (window, target) => new MyPanel(window, target),
function MyPanel(window, target) {
// The window object that has loaded the URL defined in the ToolDefinition
this.window = window;
// The Target this toolbox is debugging.
this.target = target;
// Do synchronous initialization here.
window.document.body.addEventListener("click", this.handleClick);
}
MyPanel.prototype = {
open: function() {
// Any asynchronous operations should be done here.
return this.doSomethingAsynchronous()
.then(() => this);
},
destroy: function() {
// Synchronous destruction.
this.window.document.body.removeEventListener("click", this.handleClick);
// Async destruction.
return this.destroySomethingAsynchronosly()
.then(() => console.log("destroyed"));
},
handleClick: function(event) {
console.log("Clicked", event.originalTarget);
},
};
EventEmitter is an interface many Developer Tool classes and objects implement and use to notify others about changes in their internal state.
When an event is emitted on the EventEmitter, the listeners will be called with the event name as the first argument and the extra arguments are spread as the remaining parameters.
Note: Some components use Add-on SDK event module instead of the DevTools EventEmitter. Unfortunately, their API's are a bit different and it's not always evident which one a certain component is using. The main differences between the two modules are that the first parameter for Add-on SDK events is the first payload argument instead of the event name and the once method does not return a Promise. The work for unifying the event paradigms is ongoing in {{bug(952653)}}.
The following methods are available on objects that have been decorated with the EventEmitter interface.
emit(eventName, ...extraArguments)eventName {String} - The name of the event.extraArguments {...Any} - Extra arguments that are passed to the listeners.on(eventName, listener)off(eventName, listener)once(eventName, listener)Here's a few examples using the {{anch("gDevTools")}} object.
let onInit = (eventName, toolbox, netmonitor) => console.log("Netmonitor initialized!");
// Attach a listener.
gDevTools.on("netmonitor-init", onInit);
// Remove a listener.
gDevTools.off("netmonitor-init", onInit);
// Attach a one time listener.
gDevTools.once("netmonitor-init", (eventName, toolbox, netmonitor) => {
console.log("Network Monitor initialized once!", toolbox, netmonitor);
});
// Use the Promise returned by the once method.
gDevTools.once("netmonitor-init").then(toolbox => {
// Note that the second argument is not available here.
console.log("Network Monitor initialized to toolbox", toolbox);
});
To build a sidebar in your tool, first, add a xul:tabbox where you want the sidebar to live:
<splitter class="devtools-side-splitter"/><tabbox id="mytool-sidebar" class="devtools-sidebar-tabs" hidden="true"><tabs/><tabpanels flex="1"/></tabbox>
window.setPanel(ToolPanel) function, the sidebar will call it once the document is loaded.| Method | Description |
|---|---|
new ToolSidebar(xul:tabbox, ToolPanel, uid, showTabstripe=true) |
ToolSidebar constructor |
void addTab(tabId, url, selected=false) |
Add a tab in the sidebar |
void select(tabId) |
Select a tab |
void hide() |
Hide the sidebar |
void show() |
Show the sidebar |
void toggle() |
Toggle the sidebar |
void getWindowForTab(tabId) |
Get the iframe containing the tab content |
tabId getCurrentTabID() |
Return the id of tabId of the current tab |
tabbox getTab(tabId) |
Return a tab given its id |
destroy() |
Destroy the ToolSidebar object |
| Events | Description |
new-tab-registered |
A new tab has been added |
{tabId}-ready |
Tab is loaded and can be used |
{tabId}-selected |
Tab has been selected and is visible |
{tabId}-unselected |
Tab has been unselected and is not visible |
show |
The sidebar has been opened. |
hide |
The sidebar has been closed. |
Register a tool
gDevTools.registerTool({
// FIXME: missing key related properties.
id: "inspector",
icon: "chrome://browser/skin/devtools/inspector-icon.png",
url: "chrome://browser/content/devtools/inspector/inspector.xul",
get label() {
let strings = Services.strings.createBundle("chrome://browser/locale/devtools/inspector.properties");
return strings.GetStringFromName("inspector.label");
},
isTargetSupported: function(target) {
return !target.isRemote;
},
build: function(iframeWindow, toolbox, node) {
return new InspectorPanel(iframeWindow, toolbox, node);
}
});
Open a tool, or select it if the toolbox is already open:
let target = TargetFactory.forTab(gBrowser.selectedTab);
let toolbox = gDevTools.openToolbox(target, null, "inspector");
toolbox.once("inspector-ready", function(event, panel) {
let inspector = toolbox.getToolPanels().get("inspector");
inspector.selection.setNode(target, "browser-context-menu");
});
Add a sidebar to an existing tool:
let sidebar = new ToolSidebar(xulTabbox, toolPanel, "toolId");
sidebar.addTab("tab1", "chrome://browser/content/.../tab1.xhtml", true);
sidebar.addTab("tab2", "chrome://browser/content/.../tab2.xhtml", false);
sidebar.show();