diff options
Diffstat (limited to 'files/pt-pt/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html')
| -rw-r--r-- | files/pt-pt/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/files/pt-pt/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html b/files/pt-pt/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html new file mode 100644 index 0000000000..dc98e7fd37 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html @@ -0,0 +1,156 @@ +--- +title: Extensão das ferramentas de desenvolvimento +slug: Mozilla/Add-ons/WebExtensions/Extensão_das_ferramentas_de_desenvolvimento +translation_of: Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>Esta página descreve as APIs das <em>devtools</em> que existem no Firefox 55. Embora as APIs sejam baseadas nas <a href="https://developer.chrome.com/extensions/devtools">APIs de devtools do Chrome</a>, ainda existem muitas funcionalidades que ainda não estão implementadas no Firefox, e por isso, não estão documentadas aqui. Para ver quais as funcionalidades que estão atualmente em falta, por favor, consulte <a href="/pt-PT/Add-ons/WebExtensions/Extensão_das_ferramentas_de_desenvolvimento#Limitações_das_APIs_de_devtools">Limitações das APIs de devtools</a>.</p> +</div> + +<p>Pode utilizar as APIs das Extensões da Web para ampliar as ferramentas de desenvollvimento integradas no navegador. Para criar a extensão <em>devtools</em>, inclua a chave "<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page">devtools_page</a>" no <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a>:</p> + +<pre class="brush: json">"devtools_page": "devtools/devtools-page.html"</pre> + +<p>O valor desta chave é um URL a apontar para um ficheiro HTML que foi incorporado com a sua extensão. O URL deverá ser relativo ao próprio ficheiro manifest.json.</p> + +<p>O ficheiro HTML define uma página especial na extensão, chamada de página <em>devtools</em>.</p> + +<h2 id="A_página_devtools">A página devtools</h2> + +<p>The devtools page is loaded when the browser devtools are opened, and unloaded when it is closed. Note that because the devtools window is associated with a single tab, it's quite possible for more than one devtools window - hence more than one devtools page - to exist at the same time.</p> + +<p>The devtools page doesn't have any visible DOM, but can include JavaScript sources using <code><a href="/en-US/docs/Web/HTML/Element/script"><script></a></code> tags. The sources must be bundled with the extension itself. The sources get access to:</p> + +<ul> + <li>the normal DOM APIs accessible through the global <code><a href="/en-US/docs/Web/API/Window">window</a></code> object</li> + <li>the same <a href="/en-US/Add-ons/WebExtensions/Content_scripts#WebExtension_APIs">WebExtension APIs as in Content Scripts</a></li> + <li>the devtools APIs: + <ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow">devtools.inspectedWindow</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.network">devtools.network</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.panels">devtools.panels</a></code></li> + </ul> + </li> +</ul> + +<p>Note that the devtools page does not get access to any other WebExtension APIs, and the background page doesn't get access to the devtools APIs. Instead, the devtools page and the background page must communicate using the <code>runtime</code> messaging APIs.</p> + +<h2 id="Criar_painéis">Criar painéis</h2> + +<p>The devtools window hosts a number of separate tools - the JavaScript Debugger, Network Monitor, and so on. A row of tabs across the top lets the user switch between the different tools. The window hosting each tool's user interface is called a "panel".</p> + +<p>Using the <code>devtools.panels.create()</code> API, you can create your own panel in the devtools window:</p> + +<pre class="brush: js">browser.devtools.panels.create( + "My Panel", // title + "icons/star.png", // icon + "devtools/panel/panel.html" // content +).then((newPanel) => { + newPanel.onShown.addListener(initialisePanel); + newPanel.onHidden.addListener(unInitialisePanel); +});</pre> + +<p>This takes three mandatory arguments: the panel's title, icon, and content. It returns a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> which resolves to a <code>devtools.panels.ExtensionPanel</code> object representing the new panel.</p> + +<h2 id="Interagir_com_a_janela_de_destino">Interagir com a janela de destino</h2> + +<p>The developer tools are always attached to a particular browser tab. This is referred to as the "target" for the developer tools, or the "inspected window". You can interact with the inspected window using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow">devtools.inspectedWindow</a></code> API.</p> + +<h3 id="Executar_código_na_janela_de_destino">Executar código na janela de destino</h3> + +<p>The <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow/eval">devtools.inspectedWindow.eval()</a></code> provides one way to run code in the inspected window.</p> + +<p>This is somewhat like using {{WebExtAPIRef("tabs.executeScript()")}} to inject a content script, but with one important difference:</p> + +<ul> + <li>unlike content scripts, scripts loaded using <code>devtools.inspectedWindow.eval()</code><strong> do not</strong> get <a href="/en-US/Add-ons/WebExtensions/Content_scripts#DOM_access">a "clean view of the DOM"</a>: that is, they can see changes to the page made by page scripts.</li> +</ul> + +<div class="note"> +<p>Note that a clean view of the DOM is a security feature, intended to help prevent hostile pages from tricking extensions by redefining the behavior of native DOM functions. This means you need to be very careful using eval(), and should use a normal content script if you can.</p> +</div> + +<p>Scripts loaded using <code>devtools.inspectedWindow.eval()</code> also don't see any JavaScript variables defined by content scripts.</p> + +<h3 id="Trabalhar_com_scripts_de_conteúdo">Trabalhar com <em>scripts</em> de conteúdo</h3> + +<p>A devtools document doesn't have direct access to {{WebExtAPIRef("tabs.executeScript()")}}, so if you need to inject a content script, the devtools document must send a message to the background script asking it to inject the script. The <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow/tabId">devtools.inspectedWindow.tabId</a></code> provides the ID of the target tab: the devtools document can pass this to the background script, and the background script can in turn pass it into {{WebExtAPIRef("tabs.executeScript()")}}:</p> + +<pre class="brush: js">// devtools-panel.js + +const scriptToAttach = "document.body.innerHTML = 'Hi from the devtools';"; + +window.addEventListener("click", () => { + browser.runtime.sendMessage({ + tabId: browser.devtools.inspectedWindow.tabId, + script: scriptToAttach + }); +});</pre> + +<pre class="brush: js">// background.js + +function handleMessage(request, sender, sendResponse) { + browser.tabs.executeScript(request.tabId, { + code: request.script + }); +} + +browser.runtime.onMessage.addListener(handleMessage);</pre> + +<p>If you need to exchange messages between the content scripts running in the target window and a devtools document, it's a good idea to use the {{WebExtAPIRef("runtime.connect()")}} and {{WebExtAPIRef("runtime.onConnect")}} to set up a connection between the background page and the devtools document. The background page can then maintain a mapping between tab IDs and {{WebExtAPIRef("runtime.Port")}} objects, and use this to route messages between the two scopes.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14923/devtools-content-scripts.png" style="display: block; height: 416px; margin-left: auto; margin-right: auto; width: 600px;"></p> + +<h2 id="Limitações_das_APIs_de_devtools">Limitações das APIs de devtools</h2> + +<p>These APIs are based on the Chrome devtools APIs, but many features are still missing, compared with Chrome. This section lists the features that are still not implemented, as of Firefox 54. Note that the devtools APIs are under active development and we expect to add support for most of them in future releases.</p> + +<h3 id="devtools.inspectedWindow">devtools.inspectedWindow</h3> + +<p>The following are not supported:</p> + +<ul> + <li><code>inspectedWindow.getResources()</code></li> + <li><code>inspectedWindow.onResourceAdded</code></li> + <li><code>inspectedWindow.onResourceContentCommitted</code></li> +</ul> + +<p>None of the options to <code>inspectedWindow.eval()</code> are supported.</p> + +<p>Scripts injected using <code>inspectedWindow.eval()</code> can't use any of the Console's command-line helper functions, like $0.</p> + +<h3 id="devtools.network">devtools.network</h3> + +<p>The following are not supported:</p> + +<ul> + <li><code>network.getHAR()</code></li> + <li><code>network.onRequestFinished</code></li> +</ul> + +<h3 id="devtools.panels">devtools.panels</h3> + +<p>O seguinte não é suportado:</p> + +<ul> + <li><code>panels.elements</code></li> + <li><code>panels.sources</code></li> + <li><code>panels.setOpenResourceHandler()</code></li> + <li><code>panels.openResource()</code></li> + <li><code>panels.ExtensionPanel.createStatusBarButton()</code></li> + <li><code>panels.Button</code></li> + <li><code>panels.ElementsPanel</code></li> + <li><code>panels.SourcesPanel</code></li> +</ul> + +<h2 id="Exemplos">Exemplos</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repo on GitHub, contains several examples of extensions that use devtools panels:</p> + +<ul> + <li> + <p><a href="https://github.com/mdn/webextensions-examples/blob/master/devtools-panels/">devtools-panels</a> utiliza painéis de <em>devtools</em>:</p> + </li> +</ul> |