Les extensions DevTools ajoutent des fonctionnalités aux outils pour les développeurs Chrome en accédant aux API d'extension propres aux outils de développement via une page d'outils de développement ajoutée à l'extension.
Les API d'extension spécifiques aux outils de développement incluent les éléments suivants:
Page "Outils de développement"
Lorsqu'une fenêtre "Outils de développement" s'ouvre, une extension d'outils de développement crée une instance de sa page "Outils de développement" qui existe tant que cette fenêtre est ouverte. Cette page a accès aux API DevTools et aux API d'extension, et permet d'effectuer les opérations suivantes:
- Créez des panneaux et interagissez dessus à l'aide des API
devtools.panels. Vous pouvez par exemple ajouter d'autres pages d'extension sous forme de panneaux ou de barres latérales dans la fenêtre "Outils de développement". - Obtenez des informations sur la fenêtre inspectée et évaluez le code dans la fenêtre inspectée à l'aide des API
devtools.inspectedWindow. - Obtenez des informations sur les requêtes réseau à l'aide des API
devtools.network. - Étendre le panneau Enregistreur à l'aide des API
devtools.recorder
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 "Outils de développement" pour votre extension, ajoutez le champ devtools_page dans le fichier manifeste de l'extension:
{
"name": ...
"version": "1.0",
"devtools_page": "devtools.html",
...
}
Le champ devtools_page doit pointer vers une page HTML. Étant donné que la page "Outils de développement" doit se trouver en local dans 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 la fenêtre "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 la barre latérale
En plus des éléments d'interface utilisateur habituels de l'extension, tels que les actions du navigateur, les menus contextuels et les pop-ups, une extension DevTools peut ajouter des éléments d'UI à la fenêtre DevTools:
- Un panneau est un onglet de premier niveau, tel que les panneaux "Éléments", "Sources" et "Réseau".
- Un volet de barre latérale présente une UI supplémentaire liée à un panneau. Les volets "Styles", "Styles calculés" et "Écouteurs d'événements" du panneau "Éléments" sont des exemples de volets de barre latérale. Selon la version de Chrome que vous utilisez et l'emplacement de la fenêtre "Outils de développement", les volets de vos barres latérales peuvent se présenter comme suit:
Chaque panneau correspond à son propre fichier HTML, qui peut inclure d'autres ressources (JavaScript, CSS, images, etc.). 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 la 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(). Les outils de développement évaluent l'expression dans le contexte de la page inspectée, puis affichent la valeur renvoyée.
Pour setObject() et setExpression(), le volet affiche la valeur telle qu'elle apparaît dans la console DevTools. Toutefois, setExpression() vous permet d'afficher des éléments DOM et des objets JavaScript arbitraires, tandis que setObject() n'est compatible qu'avec les objets JSON.
Communication entre les composants d'extension
Les sections suivantes décrivent quelques méthodes utiles pour permettre aux composants d'extension des outils de développement de 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 propriété inspectedWindow.tabId.
Si un script de contenu a déjà été injecté, vous pouvez utiliser des API de messagerie pour communiquer avec lui.
Évaluer JavaScript dans la fenêtre inspectée
Vous pouvez utiliser la méthode inspectedWindow.eval() pour exécuter du code JavaScript dans le contexte de la page inspectée. Vous pouvez appeler la méthode eval() à partir d'une page, d'un panneau ou d'un volet de la barre latérale des outils de développement.
Par défaut, l'expression est évaluée dans le contexte du frame principal de la page.
inspectedWindow.eval() utilise le même contexte d'exécution de script et les mêmes options que le code saisi dans la console DevTools, ce qui permet d'accéder aux fonctionnalités de l'API Console Utilitaires de DevTools 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 script de 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 n'a pas d'accès direct à l'élément actuellement sélectionné. Cependant, tout code que vous exécutez à l'aide de inspectedWindow.eval() a accès à la console DevTools et aux API Console Utilitaires. Par exemple, dans le code évalué, vous pouvez utiliser $0 pour accéder à l'élément sélectionné.
Pour transmettre l'élément sélectionné à un script de contenu, procédez comme suit:
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 }Appelez la méthode à partir de la page "Outils de développement" à l'aide de
inspectedWindow.eval()avec l'optionuseContentScriptContext: true.chrome.devtools.inspectedWindow.eval("setSelectedElement($0)", { useContentScriptContext: true });
L'option useContentScriptContext: true indique que l'expression doit être évaluée dans le même contexte que les scripts de contenu pour pouvoir 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 aurez besoin d'une référence à son objet window. Récupérez la fenêtre iFrame d'un panneau à partir du gestionnaire d'événements panel.onShown:
extensionPanel.onShown.addListener(function (extPanelWindow) {
extPanelWindow instanceof Window; // true
extPanelWindow.postMessage( // …
});
Envoyer les messages des scripts injectés vers la page "Outils de développement"
Le code injecté directement dans la page sans script de contenu, y compris en ajoutant une balise <script> ou en appelant inspectedWindow.eval(), ne peut pas envoyer de messages à la page DevTools avec runtime.sendMessage(). Nous vous recommandons plutôt de combiner le script injecté avec un script de contenu pouvant servir d'intermédiaire et d'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);
});
Vous trouverez d'autres techniques de transmission de messages sur GitHub.
Détecter quand les outils de développement s'ouvrent et se ferment
Pour savoir si la fenêtre "Outils de développement" est ouverte, ajoutez un écouteur onConnect au service worker et appelez connect() depuis la page "Outils de développement". Étant donné que la fenêtre "Outils de développement" peut être ouverte pour chaque onglet, vous pouvez recevoir plusieurs événements de connexion. Pour savoir si une fenêtre des outils de développement est ouverte, comptez les événements de connexion 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 "Outils de développement" 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 DevTools
Les exemples présentés sur cette page proviennent des pages suivantes:
- Polymer Devtools Extension : utilise de nombreux assistants exécutés sur la page hôte pour interroger l'état DOM/JS à renvoyer au panneau personnalisé.
- React DevTools Extension : utilise un sous-module du moteur de rendu pour réutiliser les composants de l'UI DevTools.
- Ember Inspector : noyau de l'extension partagée avec des adaptateurs pour Chrome et Firefox.
- Coquette-inspect : extension propre basée sur React avec un agent de débogage injecté dans la page hôte.
- Les exemples d'extensions proposent des extensions plus intéressantes à installer, à tester et à utiliser.
En savoir plus
Pour en savoir plus sur les API standards que les extensions peuvent utiliser, consultez chrome*. des API et des API Web.
Donnez-nous votre avis. Vos commentaires et suggestions nous aident à améliorer les API.
Exemples
Vous trouverez des exemples d'utilisation des API DevTools dans la section Exemples.