DevTools API

Avertissement: 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.

Introduction

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.

API

gDevTools

Méthodes	Description
`void registerTool(toolDefinition)`	Enregistre un nouvel outil, et construit un nouveau panneau dans chaque boîte à outils existante.
`void unregisterTool(toolId)`	Dé-enregistre un outil. Détruit tous les panneaux ouverts.
`Map(toolId,toolDefinition) getToolDefinitions()`	Obtient une copie du toolID:toolDefinition Map interne.
`Toolbox openToolbox(target, host=null, toolId=null)`	Ouvre une boîte à outils pour la cible spécifiée. Si l'hôte n'est pas défini, Toolbox décidera ou ouvrir la boîte à outils (sur le côté de la fenêtre, en bas, ou dans sa propre fenêtre). Si toolId n'est pas défini, Toolbox décidera lequel ouvrir par défaut.
`void closeToolbox(target)`	Ferme une boîte à outils.
`Toolbox openToolboxForTab(tab, toolId=null)`	Ouvre une boîte à outils pour l'onglet donné. Un onglet cible est construit en interne.
`void toggleToolboxForTab(tab, toolId=null)`	Ouvre/ferme la boîte à outils pour l'onglet donné.
`Map(Target,Toolbox) getToolboxes()`	Obtien une copie du target:toolbox Map interne.
`Toolbox getToolboxForTarget(target)`	Récupère la boîte à outils d'une cible donnée.
`ToolPanel getPanelForTarget(tooldId, target)`	Récupère l'instance d'un outil pour une cible donnée.
Évènements	Description
`tool-registered`	Un outil a été enregistré. `[toolId]`
`tool-unregistered`	Un outil a été dé-enregistré. `[toolId]`
`toolbox-ready`	Un outil a été ouvert. `[Toolbox]`
`toolbox-destroy`	Un processus de destruction de boîte à outils a été lancé.`[xul:tab]`
`toolbox-destroyed`	Une boîte à outils a été fermé (tous les panneaux ont également été détruits)`. [xul:tab]`
`{tooldId}-ready`	Un outil a été activé.. `[Toolbox, ToolPanel]`
`{tooldId}-destroy`	Un outil est sur le point d'être détruit. `[Toolbox, ToolPanel]`

Boîte à outils

Méthodes	Description
`Map(toolId, toolPanel) getToolPanels()`	Obtient une copie du toolId:panel Map interne.
`Target target`
`HostType hostType`	L'endroit où se situe la boîte à outils.
`toolId currentToolId`	Le toolId de l'outil sélectionné.
`void selectTool(toolId)`	Sélectionne un outil
`Node getNotificationBox()`	Récupère la notificationbox aux alentours (utile pour notifier un utilisateur même lorsque l'outil n'est pas visible).
`void destroy()`	Ferme la boîte à outils.
Évènements	Description
`ready`	La boîte à outils est prête à être utilisée.
`{toolId}-ready`	Un outil est prêt à être utilisé.
`{toolId}-destroy`	Un outil est sur le point d'être détruit.
`host-changed`	La position de la boîte à outils a changé.
`destroy`	La boîte à outils est sur le point d'être détruite.
`destroyed`	La boite à outils a été fermée.
`select`	Un nouvel outil a été sélectionné. `[toolId]`
`{toolId}-selected`	L'outil {toolId} a été sélectionné.

ToolDefinition

Methodes	Description
`String id`	Un identifiant unique. Ne doit pas contenir d'espaces (il sera utilisé comme identifiant).
`String icon`	L'URL de l'icône.
`String label`	Le nom de l'outil. Affiché dans le menu outils de Firefox et dans l'onglet de la boîte à outils.
`String key`	La touche (key) principale de keybinding.
`Number ordinal`	La position de l'onglet de l'outil dans la boîte à outils (la valeur par défaut est 99).
`String modifiers`	Les modificateurs de keybinding principaux.
`String accesskey`	Clé d'accès au menu.
`Boolean inMenu`	Si l'outil est listé dans le menu Développement ou non.
`Boolean isTargetSupported(Target)`	Si la cible n'est pas supportée, la boîte à outils cachera alors l'outil.
`String url`	Un outil existe dans sa propre iframe. La boîte à outils va charger cette URL.
`ToolPanel build(iframeWindow, Toolbox)`	Cette fonction est appelée lorsque l'utilisateur sélectionne un outil. Elle n'est appelée qu'une fois que ToolDefinition.url est chargé.

TargetType

À faire.

HostType

À faire.

ToolPanel

Méthodes	Description
`Target target`	A faire.
`Target destroy()`	A faire.
Événements	Description
`ready`	Un panneau est entierement chargé et prêt à être utilisé.
`sidebar-created`	Une sidebar a été crée pour le panneau `[ToolSidebar].`
`sidebar-destroyed`	Une sidebar a été détruite pour le panneau `[ToolSidebar]`

EventEmitter

Méthodes	Description
`on(eventName, listener)`	A faire.
`off(eventName, listener)`	A faire.
`once(eventName, listener)`	A faire.
`emit(eventName, ...extraArgs)`	A faire.
`listener function(eventName, ...extraArgs) {}`	A faire.

ToolSidebar

Pour construire une sidebar dans un outil, il faut d'abord ajouter un xul:tabbox là ou la sidebar va être :

    <splitter class="devtools-side-splitter"/>
    <tabbox id="mytool-sidebar" class="devtools-sidebar-tabs" hidden="true">
      <tabs/>
      <tabpanels flex="1"/>
    </tabbox>

Une sidebar est composée d'onglets. Chaque onglet contiendra une iframe. Par exemple dans l'Inspecteur, il y a 5 onglets (Règles, Calculé, Polices, Modèle de boîte, Animations). L'utilisateur peut sélectionner l'onglet qu'il désire.

Si la disponibilité des onglets dépend de conditions en rapport avec un outil, il est alors possible de vouloir interdire à l'utilisateur de sélectionner un onglet. Cette API fournit des méthodes pour cacher la tabstripe. Par exemple, dans la Console Web, il y a deux vues (Vue réseau et vue objet). Ces vues sont seulement disponibles dans certaines conditions contrôlées par le code de la Console Web. Ainsi, c'est à la Console Web de cacher et d'afficher la sidebar et de sélectionner le bon onglet.

Si le document chargé fournit une fonction window.setPanel(ToolPanel) , la sidebar l'appellera une fois que le document est chargé.

Methodes	Description
`new ToolSidebar(xul:tabbox, ToolPanel, uid, showTabstripe=true)`	Constructeur de ToolSidebar
`void addTab(tabId, url, selected=false)`	Ajoute un onglet à la sidebar.
`void select(tabId)`	Sélectionne un onglet.
`void hide()`	Cache la sidebar.
`void show()`	Affiche la sidebar.
`void toggle()`	Affiche/Cache la sidebar.
`void getWindowForTab(tabId)`	Récupère l'iframe contenant le contenu de l'onglet
`tabId getCurrentTabID()`	Retourne l'identifiant de la tabId de l'onglet actuel.
`tabbox getTab(tabId)`	Retourne un onglet selon l'identifiant donné.
`destroy()`	Détruit l'objet ToolSidebar.
Événements	Description
`new-tab-registered`	Un nouvel onglet à été ajouté.
`{tabId}-ready`	L'onglet est chargé et peut être utilisé.
`{tabId}-selected`	L'onglet à été sélectionné et est visible.
`{tabId}-unselected`	L'onglet à été dé-selectioné et n'est pas visible
`show`	La sidebar à été ouverte.
`hide`	La sidebar à été fermée.

Exemples

Enregistre un outil

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);
  }
});

Ouvre un outil, ou le sélectionne si la boîte à outils est déjà ouverte :

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");
});

Ajoutte une sidebar à un outil existant :

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();