Étendre les Outils de développement

Les extensions DevTools ajoutent des fonctionnalités aux outils pour les développeurs Chrome en accédant à des outils spécifiques via une page "DevTools" ajoutée à l'extension.

<ph type="x-smartling-placeholder">
</ph> Schéma de l&#39;architecture montrant la page des outils de développement communiquant avec et le service worker. Le service worker est affiché communiquer avec les scripts de contenu et accéder aux API d&#39;extension. La page &quot;DevTools&quot; a accès aux API DevTools, par exemple pour créer des panneaux.
Architecture des extensions DevTools

Les API d'extension spécifiques aux outils de développement incluent les suivantes:

Page des outils de développement

Lorsqu'une fenêtre "DevTools" s'ouvre, une extension crée une instance de sa page "DevTools" (Outils de développement) qui tant que la fenêtre est ouverte. Cette page a accès aux API des outils de développement et aux API d'extension, et peut effectuer les opérations suivantes:

  • Créez des panneaux et interagissez avec ceux-ci à l'aide des API devtools.panels, y compris en ajoutant d'autres pages d'extensions sous forme de panneaux ou de barres latérales dans la fenêtre "DevTools".
  • Obtenez des informations sur la fenêtre inspectée et évaluez le code dans la fenêtre inspectée à l'aide de la méthode API devtools.inspectedWindow.
  • Obtenez des informations sur les requêtes réseau à l'aide des API devtools.network.
  • Étendez le panneau Enregistreur à l'aide des API devtools.recorder.
  • Obtenez des informations sur l'état d'enregistrement du panneau Performance à l'aide des API devtools.performance.

La page "Outils de développement" permet d'accéder directement aux API des extensions. Cela inclut la possibilité de communiquer avec le service worker via la transmission de messages.

Créer une extension DevTools

Pour créer une page d'outils de développement pour votre extension, ajoutez le champ devtools_page dans l'extension fichier manifeste:

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

Le champ devtools_page doit renvoyer vers une page HTML. Comme les outils de développement doit être locale pour votre extension, nous vous recommandons de la spécifier à l'aide d'une URL relative.

Les membres de l'API chrome.devtools ne sont disponibles que pour les pages chargées dans les outils de développement lorsque cette fenêtre est ouverte. Les scripts de contenu et les autres pages d'extension n'ont pas accès à ces API.

Éléments de l'interface utilisateur des outils de développement: panneaux et volets de barre latérale

En plus des éléments d'interface utilisateur habituels des extensions, tels que les actions du navigateur, les menus contextuels et les fenêtres pop-up, L'extension DevTools peut ajouter des éléments d'interface utilisateur à la fenêtre "DevTools" :

  • Un panneau est un onglet de premier niveau, comme les panneaux "Éléments", "Sources" et "Réseau".
  • Un volet de barre latérale présente une UI supplémentaire liée à un panneau. Styles, styles calculés et Les volets "Écouteurs d'événements" du panneau "Éléments" sont des exemples de volets de barre latérale. En fonction du version de Chrome que vous utilisez et où la fenêtre "Outils de développement" est ancrée, les volets de la barre latérale ressemble à l'image suivante:
Fenêtre &quot;DevTools&quot; affichant les panneaux &quot;Elements&quot; et &quot;Styles&quot; de la barre latérale
Fenêtre "DevTools" affichant les panneaux "Elements" et "Styles"

Chaque panneau est constitué de son propre fichier HTML, qui peut inclure d'autres ressources (JavaScript, CSS, images, etc.). activé). Pour créer un panneau de base, utilisez le code suivant:

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

Le code JavaScript exécuté dans un panneau ou un volet de barre latérale a accès aux mêmes API que la page "Outils de développement".

Pour créer un volet de barre latérale de base, utilisez le code suivant:

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

Il existe plusieurs façons d'afficher du contenu dans un volet de barre latérale:

  • Contenu HTML: appelez setPage() pour spécifier une page HTML à afficher dans le volet.
  • Données JSON: transmettez un objet JSON à setObject().
  • Expression JavaScript: transmettez une expression à setExpression(). DevTools évalue l'expression dans le contexte de la page inspectée, puis affiche la valeur renvoyée.

Pour setObject() et setExpression(), le volet affiche la valeur telle qu'elle apparaît dans les DevTools. Cependant, setExpression() vous permet d'afficher des éléments DOM et du code JavaScript arbitraire d'objets, tandis que setObject() n'accepte que les objets JSON.

Communication entre les composants d'extension

Les sections suivantes décrivent quelques façons utiles d'autoriser les composants de l'extension des outils de développement à communiquer entre eux.

Injecter un script de contenu

Pour injecter un script de contenu, utilisez scripting.executeScript():

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

Vous pouvez récupérer l'ID de l'onglet de la fenêtre inspectée à l'aide de la méthode inspectedWindow.tabId.

Si un script de contenu a déjà été injecté, vous pouvez utiliser les API de messagerie pour communiquer avec elle.

Évaluer JavaScript dans la fenêtre inspectée

Vous pouvez utiliser la méthode inspectedWindow.eval() pour exécuter JavaScript. dans le contexte de la page inspectée. Vous pouvez appeler la méthode eval() à partir d'une page d'outils de développement. ou un volet de barre latérale.

Par défaut, l'expression est évaluée dans le contexte du frame principal de la page. inspectedWindow.eval() utilise les mêmes options et le même contexte d'exécution de script que le code saisi dans la console DevTools, ce qui permet d'accéder aux utilitaires de la console de l'API lorsque vous utilisez eval(). Par exemple, SOAK l'utilise pour inspecter un élément:

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

Vous pouvez également définir useContentScriptContext sur true lorsque vous appelez inspectedWindow.eval() pour évaluer l'expression dans le même contexte que les scripts de contenu ; Pour utiliser cette option, utilisez une déclaration de script de contenu statique avant d'appeler eval(), soit en appelant executeScript(), soit en spécifiant un contenu dans le fichier manifest.json. Une fois le contexte du script de contexte chargé, vous pouvez également utiliser cette option pour : injecter des scripts de contenu supplémentaires.

Transmettre l'élément sélectionné à un script de contenu

Le script de contenu ne dispose pas d'un accès direct à l'élément actuellement sélectionné. Toutefois, tout code que vous exécuter à l'aide de inspectedWindow.eval() a accès aux outils de développement console et les API Console Utilitaires. Par exemple, dans le code évalué, vous pouvez utiliser $0 pour accéder sélectionné.

Pour transmettre l'élément sélectionné à un script de contenu:

  1. Créez dans le script de contenu une méthode qui utilise l'élément sélectionné comme argument.

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

  2. Appelez la méthode à partir de la page des outils de développement à l'aide de inspectedWindow.eval(). avec l'option useContentScriptContext: true.

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

L'option useContentScriptContext: true indique que l'expression doit être évaluée dans le le même contexte que les scripts de contenu, afin qu'il puisse accéder à la méthode setSelectedElement.

Obtenir le window d'un panneau de référence

Pour appeler postMessage() à partir d'un panneau d'outils de développement, vous avez besoin d'une référence à son objet window. Obtenez un fenêtre iFrame du panneau à partir du gestionnaire d'événements panel.onShown:

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

Envoyer des messages à partir de scripts injectés vers la page "Outils de développement"

Code injecté directement dans la page sans script de contenu, y compris en ajoutant un <script> ou appeler inspectedWindow.eval(), ne peut pas envoyer de messages au Page "DevTools" (Outils de développement) à l'aide de runtime.sendMessage() Nous vous recommandons plutôt combiner votre script injecté avec un script de contenu pouvant servir d'intermédiaire, et utiliser la méthode window.postMessage(). L'exemple suivant utilise le script d'arrière-plan de la section précédente:

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

D'autres techniques de transmission de messages sont disponibles sur GitHub.

Détecter quand les outils de développement s'ouvrent et se ferment

Pour savoir si la fenêtre "DevTools" est ouverte, ajoutez un écouteur onConnect. au service worker et appelez connect() depuis la page "DevTools". En effet, chaque onglet peut avoir sa propre fenêtre "DevTools" (Outils de développement) ouverte, vous pouvez recevoir plusieurs événements de connexion. Pour savoir si une fenêtre des outils de développement est ouverte, comptabilisez les événements d'association et de déconnexion comme indiqué. dans l'exemple suivant:

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

La page "DevTools" crée une connexion comme celle-ci:

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

Exemples d'extensions des outils de développement

Les exemples présentés sur cette page proviennent des pages suivantes:

  • Extension Devtools Polymer : utilise de nombreux assistants exécutés sur la page hôte pour effectuer des requêtes. État DOM/JS à renvoyer au panneau personnalisé.
  • Extension React DevTools : utilise un sous-module du moteur de rendu pour réutiliser l'interface utilisateur des outils de développement composants.
  • Ember Inspector : cœur d'extension partagé avec des adaptateurs pour Chrome et Firefox
  • Coquette-inspect : extension propre basée sur React avec injection d'un agent de débogage sur la page hôte.
  • Les exemples d'extensions proposent des extensions plus intéressantes à installer, à tester et à découvrir.

En savoir plus

Pour en savoir plus sur les API standards que les extensions peuvent utiliser, consultez chrome*. API et Web API.

Envoyez-nous vos commentaires. Vos commentaires et suggestions nous aident à améliorer les API.

Exemples

La section Exemples contient des exemples utilisant les API DevTools.