--- title: DevTools API slug: Tools/DevToolsAPI translation_of: Tools/DevToolsAPI original_slug: Outils/DevToolsAPI ---
{{ToolsSidebar}}{{Obsolete_Header}}
Warning:("L'API des outils de développement est en cours de développement. Si vous rencontrez des incohérences, merci de les signaler à l'équipe des outils de développement de Firefox.")
Bien que cette api soit toujours en développement, il existe des parties de l'Inspecteur et du Debogueur qui sont d’ores et déjà utilisable.
L'API des outils de développements fournit une manière d'enregistrer et d'accéder aux outils de développement dans Firefox.
En terme d'interface utilisateur, chaque outil enregistré existe dans son propre onglet (Appelé également panneau). Ces onglets sont situés dans une boîte appelée Boite à outils. Une boîte à outils peut être hébergée dans un navigateur (en bas ou sur le coté) ou peut être dans propre fenêtre (la boîte à outils est alors dite détachée). Une boîte à outils (et tous les outils qu'elle contient) est reliée à une Cible qui est l'objet que les outils sont en train de déboguer. Une cible le plus souvent une page web (un onglet), mais peut être autre chose, comme une fenêtre chrome un onglet distant.
En terme de code, chaque outil doit fournir un objet ToolDefinition. Une définition est un objet JS léger qui fournit différentes informations sur l'outil (par exemple son nom et son icône), ainsi qu'une méthode build qui sera utilisée plus tard pour lancer une instance de cet outil. L'objet global gDevTools fournit des méthodes pour enregistrer une définition d'outil et pour accéder aux instances d'outils. Une instance d'outil est appelée un ToolPanel. Le ToolPanel est construit seulement lorsque l'outil est sélectionné (non pas quand la boîte à outils est ouverte). Il n'y a aucun mayen de "fermer/détruire" un ToolPannel. La façon de fermer un ToolPanel est de fermer la boîte à outils qui le contient. Tous les objets sus-mentionnés implémentent l'interface EventEmitter.
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.
target
hostType
Toolbox.HostType
constants.zoomValue
The Toolbox constructor contains following constant properties.
Toolbox.HostType.BOTTOM
Toolbox.HostType.SIDE
Toolbox.HostType.WINDOW
Toolbox.HostType.CUSTOM
getCurrentPanel()
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-changed
ready
Toolbox
is ready to use.select(toolId)
{toolId}-selected
event.{toolId}-init(frame)
{toolId}-build(panel)
{toolId}-ready(panel)
{toolId}-selected(panel)
{toolId}-destroy(panel)
destroy
Toolbox
is about to be destroyed.destroyed
Toolbox
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.
id
url
label
icon
should be specified.tooltip
panelLabel
ordinal
visibilityswitch
devtools.{id}.enabled
icon
highlightedicon
{icon}
iconOnly
invertIconForLightTheme
key
modifiers
preventClosingOnKey
inMenu
menuLabel
{label}
accesskey
Here'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();