diff options
Diffstat (limited to 'files/pt-pt/mozilla/add-ons')
61 files changed, 7710 insertions, 0 deletions
diff --git a/files/pt-pt/mozilla/add-ons/amo/index.html b/files/pt-pt/mozilla/add-ons/amo/index.html new file mode 100644 index 0000000000..3857ed65ca --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/amo/index.html @@ -0,0 +1,9 @@ +--- +title: AMO +slug: Mozilla/Add-ons/AMO +tags: + - NeedsTranslation + - TopicStub +translation_of: Mozilla/Add-ons/AMO +--- +<p>Content to be added.</p> diff --git a/files/pt-pt/mozilla/add-ons/amo/policy/em_destaque/index.html b/files/pt-pt/mozilla/add-ons/amo/policy/em_destaque/index.html new file mode 100644 index 0000000000..71eafffe67 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/amo/policy/em_destaque/index.html @@ -0,0 +1,85 @@ +--- +title: AMO - Políticas de Extensões em Destaque +slug: Mozilla/Add-ons/AMO/Policy/Em_destaque +translation_of: Mozilla/Add-ons/AMO/Policy/Featured +--- +<p>{{AddonSidebar}}</p> + +<p>Featured add-ons are top-quality extensions and themes highlighted on <a href="https://addons.mozilla.org/en-US/firefox/extensions/?sort=featured">AMO</a>, Firefox's Add-ons Manager, and across other Mozilla websites. These add-ons showcase the power of Firefox customization and are useful to a wide audience.</p> + +<p>Featured extensions are chosen by the Featured Extensions Advisory Board, a small group of extension developers and fans from the Mozilla community who have volunteered to review and vote on nominations.</p> + +<p>Todos os meses, são escolhidas novas <a href="https://addons.mozilla.org/pt-PT/firefox/search/?featured=true&type=extension">extensões em destaque</a>.</p> + +<h3 id="Critérios_para_Extensões_em_Destaque">Critérios para Extensões em Destaque</h3> + +<p>Before nominating an extension to be featured, please ensure it meets the following criteria:</p> + +<ol> + <li>The extension must have a complete and informative listing on AMO. This means: + <ul> + <li>a 64-pixel custom icon</li> + <li>a clear and concise name (no lengthy keywords)</li> + <li>a clear and concise summary of the extension's functionality</li> + <li>detailed description and privacy policy, if applicable</li> + <li>updated screenshots of the extension's functionality</li> + </ul> + </li> + <li>The extension must have excellent user reviews and any problems or support requests must be promptly addressed by the developer.</li> + <li>The extension must have a minimum of 500 users.</li> + <li>The extension must be built with <a href="https://developer.mozilla.org/Add-ons/WebExtensions">WebExtensions</a> API.</li> + <li>The extension must be compatible with the latest release of Firefox.</li> + <li><strong>Most importantly</strong>, the extension must have wide consumer appeal to Firefox's users and be outstanding in nearly every way: user experience, performance, security, and usefulness or entertainment value.</li> +</ol> + +<h3 id="Painel_de_Descoberta">Painel de Descoberta</h3> + +<p>The Get Add-ons section (also referred to as the Discovery Pane) in about:addons serves a distinct editorial function: it is a tightly curated list of extensions and themes selected by Mozilla staff to address an array of the most common user needs (e.g. ad blockers, screenshot tools, etc.). The Discovery Pane is primarily intended to introduce extensions to Firefox users who have limited experience with browser customization. As such, we only select extensions that meet the highest standards of functionality, user experience, and Firefox compatibility.</p> + +<p>Only content that is part of AMO’s <a class="external text" href="https://addons.mozilla.org/en-US/firefox/search/?featured=true&type=extension" rel="nofollow">Featured Extensions collection</a> will be considered for the Discovery Pane; please note that featured content must meet certain <a href="https://wiki.mozilla.org/AMO/Featured_Board_Process#Add-on_Requirements" title="AMO/Featured Board Process">criteria</a>.</p> + +<p>Discovery Pane content is updated monthly, though some highly popular extensions may remain on the page for an indefinite period of time.</p> + +<p>If you’d like to nominate a great extensions for consideration in the Discovery Pane, please send us a link to the add-on on AMO to <strong>amo-featured@mozilla.org</strong> and we’ll add your nomination to the editorial review queue. There’s no need to mention you’re nominating add-ons specifically for the Discovery Pane, but feel free to note that if you like.</p> + +<h3 id="Nomear_um_Extra">Nomear um Extra</h3> + +<p>If you wish to nominate an extension to be featured and it meets the criteria above, send an email to <a href="mailto:amo-featured@mozilla.org">amo-featured@mozilla.org</a> with:</p> + +<ul> + <li>the extension name, URL, and whether you are its developer</li> + <li>a short explanation of why the extension has wide appeal and should be featured</li> + <li>optionally, links to any external reviews or articles mentioning the extension</li> +</ul> + +<p>Extension nominations are reviewed by the Advisory Board once a month. Common reasons for rejection include lacking wide appeal to consumers, a suboptimal user experience, quality or security issues, incompatibility, and similarity to another featured extension. Rejected extension cannot be re-nominated within 3 months.</p> + +<h3 id="Rodar_Extensões_em_Destaque">Rodar Extensões em Destaque</h3> + +<p>Mozilla and the Featured Extensions Advisory Board regularly evaluate and rotate out featured extensions. Some of the most common reasons for extensions being removed from the featured list are:</p> + +<ul> + <li>Lack of growth — Extensions that are featured typically experience a substantial gain in both downloads and active users. If an extension is not demonstrating growth in any substantial way, that's a good indicator the extension may not be very useful to our users.</li> + <li>Negative reviews — Featured extensions should have a great experience and very few bugs, so extensions with many negative reviews may be reconsidered.</li> + <li>Incompatibility with upcoming Firefox versions — Featured extensions are expected to be compatible with stable and beta versions of Firefox. Extensions not yet compatible with a Beta version of Firefox four weeks before its expected release will lose their featured status.</li> +</ul> + +<h3 id="Aderir_ao_Conselho_Consultivo_de_Extensões_em_Destaque">Aderir ao Conselho Consultivo de Extensões em Destaque</h3> + +<p>Every six months a new Advisory Board is chosen based on applications from the add-ons community. Members must:</p> + +<ul> + <li>be active members of the add-ons community, whether as a developer, evangelist, or fan</li> + <li>commit to trying all the nominations submitted, giving their feedback, and casting their votes every month</li> + <li>abstain from voting on extensions that they have any business or personal affiliations with, as well as direct competitors of any such extensions</li> +</ul> + +<p>Members of the Mozilla Add-ons team may veto any extension's selection because of security, privacy, compatibility, or any other reason, but in general it is up to the Board to select extensions to feature.</p> + +<p>This featured policy only applies to the addons.mozilla.org global list of featured extensions. Extensions featured in other locations are often pulled from this list, but Mozilla may feature any extension in other locations without the Board's consent. Additionally, locale-specific features override the global defaults, so if a locale has opted to select its own features, some or all of the global features may not appear in that locale.</p> + +<p>Follow the <a href="http://blog.mozilla.com/addons">Add-ons Blog</a> or <a href="http://www.twitter.com/mozamo">@mozamo</a> on Twitter to learn when the next application period opens.</p> + +<p><em>Última atualização: 12 de abril de 2018</em></p> + +<p><span class="comment seoSummary">How up-and-coming add-ons become featured and what's involved in the process. </span></p> diff --git a/files/pt-pt/mozilla/add-ons/amo/policy/index.html b/files/pt-pt/mozilla/add-ons/amo/policy/index.html new file mode 100644 index 0000000000..2dd894f5bd --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/amo/policy/index.html @@ -0,0 +1,19 @@ +--- +title: Políticas AMO +slug: Mozilla/Add-ons/AMO/Policy +tags: + - NeedsTranslation + - TopicStub +translation_of: Mozilla/Add-ons/AMO/Policy +--- +<p>Mozilla está empenhada em garantir uma grande experiência com os extras para os nossos utilizadores e desenvolvedores. Por favor, reveja as políticas abaixo antes de submeter o seu extra.</p> + +<dl> + <dd></dd><dt><a href="/Mozilla/Add-ons/AMO/Policy/Agreement">Developer Agreement</a></dt> +<dd>Effective January 5, 2016</dd> <dt><a href="/Mozilla/Add-ons/AMO/Policy/Reviews">Review Process</a></dt> +<dd>Add-ons extend the core capabilities of Firefox, allowing users to modify and personalize their Web experience. A healthy add-on ecosystem, built on trust, is vital for developers to be successful and users to feel safe making Firefox their own. For these reasons, Mozilla requires all add-ons to comply with the following set of policies on acceptable practices. The below is not intended to serve as legal advice, nor is it intended to serve as a comprehensive list of terms to include in your add-on’s privacy policy.</dd> <dt><a href="/Mozilla/Add-ons/AMO/Policy/Featured">Featured Add-ons</a></dt> +<dd>How up-and-coming add-ons become featured and what's involved in the process. </dd> <strong><a href="/en-US/Add-ons#Contact_us">Contacting us</a></strong> + + <p> How to get in touch with us regarding these policies or your add-on.</p> + +</dl> diff --git a/files/pt-pt/mozilla/add-ons/amo/policy/revisões/index.html b/files/pt-pt/mozilla/add-ons/amo/policy/revisões/index.html new file mode 100644 index 0000000000..96e6d880f5 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/amo/policy/revisões/index.html @@ -0,0 +1,160 @@ +--- +title: Políticas de Extras +slug: Mozilla/Add-ons/AMO/Policy/Revisões +tags: + - Extras + - Política de Revisão +translation_of: Mozilla/Add-ons/AMO/Policy/Reviews +--- +<p>{{AddonSidebar}}</p> + +<p>Os extras estendem os recursos principais do Firefox, permitindo que os utilizadores modifiquem e personalizem a sua experiência na Web. Um ecossistema de extras saudável, baseado na confiança, é vital para que os programadores sejam bem-sucedidos e os utilizadores se sintam seguros, tornando o Firefox deles próprio. Por estes motivos, a Mozilla requer que todos os extras estejam em conformidade com o seguinte conjunto de políticas sobre as práticas aceitáveis. O abaixo, não se destina para servir como aconselhamento jurídico, nem pretende servir como uma lista abrangente de termos para incluir na política de privacidade do seu extra.</p> + +<p>Todos os extras estão sujeitos a estas políticas, independentemente de como eles são distribuídos. Os extras que não estejam em conformidade com estas políticas podem estar sujeitos à rejeição ou desativação pela Mozilla.</p> + +<h2 id="Sem_Surpresas">Sem Surpresas</h2> + +<p>As surpresas podem ser apropriadas em muitas situações, mas não são bem-vindas quando a segurança, a privacidade e o controlo do utilizador estão em jogo. É extremamente importante ser o mais transparente possível quando submeter um extra. Os utilizadores deverão ser capazes de discernir facilmente qual é a funcionalidade do seu extra e não receber experiências inesperadas do utilizador depois de o instalal.</p> + +<h3 id="Funcionalidades_Inesperadas">Funcionalidades Inesperadas</h3> + +<p>“Funcionalidades" inesperadas são aquelas que não estão relacionadas com a função principal do extra e provavelmente não são do nome do extra ou da descrição esperada por um utilizador que está a instalar esse extra.</p> + +<p>Um extra deveria incluir qualquer funcionalidade inesperada que se enquadre numa das seguintes categorias:</p> + +<ul> + <li>Potencialmente compromete a privacidade ou a segurança do utilizador (tal como enviar dados para terceiros)</li> + <li>Altera as definições predefinidas, tal como o novo separador, a página inicial ou o motor de pesquisa</li> + <li>Faz alterações inesperadas no navegador ou no conteúdo da Web</li> + <li>Inclui recursos ou funcionalidades não relacionadas com as funções principais do extra</li> +</ul> + +<p>Então, a(s) funcionalidade(s) "inesperada(s)" devem seguir todos os seguintes requisitos:</p> + +<ul> + <li>A descrição do extra deve indicar claramente quais as alterações que o extra efetua.</li> + <li>Todas as alterações devem ser "opcionais", o que significa que o utilziador deve executar uma ação não predefinida para aprovar a alteração. As alterações que solicitam aos utilizadores por meio do sistema de permissões não requerem uma opção adicional.</li> + <li>A interface de opções deve declarar claramente o nome do extra que está a solicitar a alteração.</li> +</ul> + +<h2 id="Conteúdo">Conteúdo</h2> + +<p>Os extras que utilizarem as marcas registadas da Mozilla devem obedecer à <a href="https://www.mozilla.org/en-US/foundation/trademarks/policy/">Política de Marcas Registadas da Mozilla</a>. Se o extra utiliza “Firefox” no seu nome, o padrão de nomeação que o extra deve seguir é “<nome do Extra> por Firefox”.</p> + +<p>Além disso, os extras listados em <a href="https://addons.mozilla.org/pt-PT/firefox/">Extras para o Firefox</a> (AMO) devem seguir as seguintes políticas:</p> + +<ul> + <li>All add-ons submitted for listing on AMO are subject to Mozilla’s <a href="https://www.mozilla.org/en-US/about/legal/acceptable-use/">Conditions of Use</a>.</li> + <li>Add-ons must disclose when payment is required to enable any functionality.</li> + <li>Any add-ons, or add-on content, hosted on Mozilla site(s) must conform to the laws of the United States.</li> + <li>The add-on listing should have an easy-to-read description about everything it does, and any information it collects. Please consult our best practices guide for <a href="https://developer.mozilla.org/en-US/Add-ons/Listing">creating an appealing listing</a>.</li> + <li>Add-ons that are intended for internal or private use, or for distribution testing may not be listed on AMO. Such add-ons may be <a href="https://developer.mozilla.org/en-US/Add-ons/Distribution#Self-distributed_(unlisted)_versions">uploaded for self-distribution</a> instead.</li> + <li>If the add-on is a fork of another add-on, the name must clearly distinguish it from the original and provide a significant difference in functionality and/or code.</li> +</ul> + +<h2 id="Linhas_Diretrizes_de_Submissão">Linhas Diretrizes de Submissão</h2> + +<p>Os extras devem funcionar apenas conforme o descrito e devem fornecer uma experiência de utilizador atraente. Com base na descrição do extra, um utilizador deve ser capaz de entender e utilizar os recursos do extra sem exigir conhecimento especializado. Dicas sobre como criar uma boa experiência do utilziador para o seu extra podem ser encontradas <a href="/pt-PT/Add-ons/WebExtensions/As_melhores_praticas_de_experiencia_do_utilizador">aqui</a>.</p> + +<p>During review, the add-on undergoes basic testing in addition to code review. To facilitate the functional testing, the add-on author must provide testing information and, if applicable, testing credentials required to use the add-on if an account is needed for any part of the add-on’s functionality.</p> + +<p>Issues brought up during review must be addressed using best efforts. If corrections have been requested, the new version should not contain unrelated changes, as this complicates the review process and can lead to further rejections.</p> + +<h3 id="Submissão_de_Código_Fonte">Submissão de Código Fonte</h3> + +<p>Add-ons may contain transpiled, obfuscated, minified or otherwise machine-generated code, but Mozilla needs to review a copy of the human-readable source code. The author must provide this information to Mozilla during submission as well as instructions on how to reproduce the build.</p> + +<p>The provided source code will be reviewed by an administrator and will not be redistributed in any way. The code will only be used for the purpose of reviewing the add-on. Failure to provide this information will result in rejection.</p> + +<p>Please read our <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/Source_Code_Submission">Source Code Submission guidelines</a> to avoid unexpected rejections.</p> + +<h2 id="Práticas_de_Desenvolvimento">Práticas de Desenvolvimento</h2> + +<p>In general, developers are free to maintain their add-ons in the manner they choose. However, in order to maintain appropriate data security and effectively review code, we do have certain technical requirements that all add-ons must meet. In particular, potentially dangerous APIs may only be used in ways that are demonstrably safe, and code within add-ons that cannot be verified as behaving safely and correctly may need to be refactored.</p> + +<p>While any code, method or practice in a submitted add-on is subject to review and rejection, the following requirements are of particular importance:</p> + +<ul> + <li>Add-ons must only request those permissions that are necessary for function</li> + <li>Add-ons must be self-contained and not load remote code for execution</li> + <li>Add-ons must use encrypted channels for sending sensitive user data</li> + <li>Add-ons should avoid including duplicate or unnecessary files</li> + <li>Add-on code must be written in a way that is reviewable and understandable. Reviewers may ask you to refactor parts of the code if it is not reviewable.</li> + <li>Add-ons must not negatively impact the performance or stability of Firefox.</li> + <li>Only release versions of third-party libraries and/or frameworks may be included with an add-on. Modifications to these libraries/frameworks are not permitted.</li> +</ul> + +<h2 id="Gestão_Recolha_e_Divulgação_de_Dados">Gestão, Recolha e Divulgação de Dados</h2> + +<p>You must disclose how the add-on collects, uses, stores and shares user data in the privacy policy field on AMO. Mozilla expects that the add-on limits data collection whenever possible, in keeping with Mozilla’s <a href="https://www.mozilla.org/en-US/about/policy/lean-data/">Lean Data Practices</a> and Mozilla’s <a href="https://www.mozilla.org/en-US/privacy/principles/">Data Privacy Principles</a>, and uses the data only for the purpose for which it was originally collected.</p> + +<p>User data includes all information the add-on collects, regardless of the manner. It can be personal data actively provided by the user (such as a name or email address), technical data (such as operating system, build ID, version numbers, crash reports, activation, updates), and interaction or activity data (add-on activity data, visited URLs, console logs), including interactions with Firefox.</p> + +<p>The add-on’s privacy policy must be the full policy text; it cannot be a link to an externally hosted privacy policy. In addition, the privacy policy must:</p> + +<ul> + <li>be specific and exclusive to the add-on,</li> + <li>clearly describe the purpose of the data collection,</li> + <li>set forth the exact data to be collected,</li> + <li>address the add-on’s particular privacy properties.</li> +</ul> + +<p>A summary of this information must be included in the add-on’s listing description. Finally, you and your add-on must also comply with all applicable data privacy laws as well as any other laws that may apply to your specific add-on.</p> + +<h3 id="Interações_do_Utilizador_e_Dados_Técnicos">Interações do Utilizador e Dados Técnicos</h3> + +<ul> + <li>Users must be provided a clear way to control this data collection. The control mechanism must be shown during the installation process of the add-on.</li> + <li>Add-ons must only collect information about add-on performance and/or use.</li> + <li>Collecting ancillary information (e.g. any data not explicitly required for the add-on’s basic functionality) is prohibited.</li> +</ul> + +<h3 id="Cookies">Cookies</h3> + +<ul> + <li>If your add-on installs cookies, this must also be disclosed in the add-on’s privacy policy.</li> + <li>The add-on privacy policy must clearly express the placing and purposes of the cookie(s). It is highly recommended that you disclose the types of cookies being used.</li> + <li>Users must be provided an opportunity to refuse the storage of or access to cookies, and must be informed of the consequences of doing so (e.g., without a functional cookie, the add-on may not work).</li> + <li>Installing cookies that are not explicitly required for the add-on’s functionality is prohibited.</li> +</ul> + +<h3 id="Dados_Pessoais">Dados Pessoais</h3> + +<ul> + <li>If you are collecting any personal information, the users must provide affirmative consent (i.e., explicit opt-in from the user). It must be clear to the user that they give consent to the collection of personal data.</li> + <li>Collecting ancillary personal information (e.g., any data not explicitly required for the add-on’s basic functionality) is prohibited.</li> + <li>Any transmission of this type of data must use secure, encrypted connections.</li> +</ul> + +<h3 id="Protocolos_de_Privacidade_Adicionais">Protocolos de Privacidade Adicionais</h3> + +<ul> + <li>Leaking local or user-sensitive information to websites or other processes (e.g., using native messaging) is prohibited.</li> + <li>If the add-on uses native messaging, the privacy policy must clearly disclose which information is being exchanged with the native application. Data exchanged with the native application must be in accordance with our No Surprises policy.</li> + <li>HTTPS must be used for security and privacy-sensitive operations such as transmitting passwords or tokens.</li> + <li>Browsing data from private browsing sessions must not be stored.</li> + <li>Identity information must not be leaked to web content in private browsing sessions.</li> +</ul> + +<h2 id="Vulnerabilidades_de_Segurança">Vulnerabilidades de Segurança</h2> + +<p>Because add-ons run in an environment with elevated privileges relative to ordinary web pages, they present a very serious set of security considerations. They have the potential to open security holes not only in the add-ons themselves, but also in the browser, in web pages, and, in particularly distressing cases, the entire system the browser is running on.</p> + +<p>As a result, we take our security policies very seriously and apply them to all add-ons, whether hosted on AMO or not. We expect all add-ons to be secure and well-maintained in handling both their own data and their user’s data. They must also securely manage all of their interactions with the web, the browser and the operating system.</p> + +<h2 id="Monetização">Monetização</h2> + +<ul> + <li>Os mecanismos de monetização devem cumprir com as políticas na secção <em>Divulgação, Recolha e Gestão de Dados</em>. Em particular, um extra deve ser acompanhado de um mecanismo de controle de utilizador claro (e opção para dados pessoais) apresentado durante o processo de instalação ou atualização do extra. A recolha de informação auxiliar para monetização é proibida.</li> + <li>Um extra que injetar publicidade no conteúdo da página da Web deve identificar claramente o conteúdo injetado como originário do extra.</li> + <li>A inclusão de mineiros de criptomoedas ou funcionalidades similares num extra é proibida.</li> + <li>A modificação do conteúdo da Web ou a facilitação de redirecionamentos para incluir etiquetas de promoção de afiliados não é permitida. Por outro lado, a utilização da promoção de afiliação nos elementos da interface do utilizador claramente identificada como pertencentes ao extra é aceitável.</li> +</ul> + +<h2 id="Conformidade_e_Lista_de_Bloqueio">Conformidade e Lista de Bloqueio</h2> + +<p>Para os extras que não correspondem com estas políticas, a Mozilla pode rejeitar ou bloquear as versões afetadas ou extras completos, dependendo da extensão da sua não conformidade.</p> + +<p>Geralmente, a Mozilla tentará entrar em contacto com o(s) programador(es) do extra e fornecer um prazo razoável para que os problemas sejam corrigidos antes que um bloqueio seja implementado. Se um extra for considerado malicioso ou se os seus programadores tiverem se mostrado inalcançáveis ou não responderem, ou no caso de violações recorrentes, a inclusão na listagem de bloqueio ser imediata.</p> + +<p>A Mozilla reserva o direito de bloquear ou eliminar a conta do programador em addons.mozilla.org, evitando assim a utilização adicional do serviço.</p> diff --git a/files/pt-pt/mozilla/add-ons/crição_de_extensões_firefox_com_sistema_mozilla/index.html b/files/pt-pt/mozilla/add-ons/crição_de_extensões_firefox_com_sistema_mozilla/index.html new file mode 100644 index 0000000000..35a9c7fbe1 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/crição_de_extensões_firefox_com_sistema_mozilla/index.html @@ -0,0 +1,518 @@ +--- +title: >- + Criação de extensões personalizadas do Firefox com o sistema de criação da + Mozilla +slug: Mozilla/Add-ons/Crição_de_extensões_Firefox_com_Sistema_Mozilla +translation_of: >- + Archive/Add-ons/Creating_Custom_Firefox_Extensions_with_the_Mozilla_Build_System +--- +<p>{{AddonSidebar}}</p> + +<p>Existe uma <a href="/pt-PT/Add-ons" title="en/Extensions">abundância de material</a> na criação de extensões para Firefox. Todos estes documentos atualmente assumem, contudo, que está a desenvolver a sua extensão utilizando apena <a href="/en/JavaScript" title="en/JavaScript">JavaScript </a>e <a href="/en/XUL" title="en/XUL">XUL</a>. Para extenões complexas, poderá ser necessário criar componentes em C++ que proporcionam uma funcionalidade adicional. Os motivos pelos quais poderá querer incluir componentes C++ na sua extensão incluem:</p> + +<div class="m2"> +<div class="mrg"> +<div class="client" id="baseBody" style=""> +<div id="textContainer" style="DISPLAY: block;"> +<div id="FtxtWnd" style=""> +<div class="targetTxt"> </div> +</div> +</div> +</div> +</div> +</div> + +<ul> + <li>Need for high-performance beyond what can be delivered by JavaScript code.</li> + <li>Use of third-party libraries written in C or C++.</li> + <li>Use of Mozilla interfaces that are not exposed via <a href="/en/XPCOM" title="en/XPCOM">XPCOM</a> (e.g. <a href="/en/NSPR" title="en/NSPR">NSPR</a>).</li> +</ul> + +<div class="note"><strong>Note:</strong> With the modern JIT Javascript Engine in Gecko and <a href="/en/js-ctypes/js-ctypes_reference" title="js-ctypes reference">js-ctypes</a> more extension code can be written only in JavaScript than ever before. Please consider all of your options carefully before deciding to use native code (C++) in your extension. In addition, binary components need to be recompiled for every major Firefox release, which can be frustrating.</div> + +<p>This article describes how to set up the development environment for a large, complex Firefox extension with any or all of the above-mentioned requirements. I should also stress that you do <em>not</em> have to build Mozilla or use the Mozilla build system if you want to create C++ components for Mozilla. If you are just looking to create an <a href="/en/XPCOM" title="en/XPCOM">XPCOM</a> component or two, this is probably overkill, and you might want to take a look at <a class="external" href="http://www.iosart.com/firefox/xpcom/">this guide</a> instead. On the other hand, if you are an experienced developer or team, and you know that you are going to build a large, complex extension, you would do well to consider the approach described in this article.</p> + +<p>One final note: I’ve only tried these techniques inside Firefox, but they’ll probably work more or less unchanged on other Gecko-based platforms like Thunderbird or Seamonkey. If someone can confirm this and/or provide guidelines for what’s different, I’ll update the article to incorporate this information.</p> + +<h3 id="Bambi_Cruza-se_com_Mozilla">Bambi Cruza-se com Mozilla</h3> + +<p>None of this is for the faint of heart. In particular, the initial step involves building Mozilla, which is a huge - nay, gargantuan! - project. Many intelligent developers have been driven to the brink of insanity trying to build it for the first time. If you're not an experienced C++ developer, I wouldn’t even bother. Stick to JavaScript.</p> + +<h4 id="Nas_Plataformas_do_Windows">Nas Plataformas do Windows</h4> + +<p>The first time I built Mozilla I used <a href="/En/Developer_Guide/Build_Instructions/Windows_Prerequisites" title="En/Developer_Guide/Build_Instructions/Windows_Prerequisites">this guide</a>. I can’t even remember why anymore, but I got stuck in a number of places, and the whole affair ended up taking far longer than I originally expected. Much furniture was smashed, much hair torn out by the roots. Here’s a <a class="external" href="http://whereswalden.com/mozilla/msvcfree/">comprehensive looking guide</a> that’s gotten good reviews. Follow every step methodically and you’ll probably be alright. Focus on the fact that once you get the build working, it’ll probably work effortlessly from then on. Maybe.</p> + +<h4 id="Em_Outras_Plataformas">Em Outras Plataformas</h4> + +<p>On other platforms, namely Linux and MacOS, the process is much easier. All the tools for building are available built-in, and therefore all you have to do is run some commands in the terminal. You can find full instructions for almost any OS <a href="/En/Developer_Guide/Build_Instructions" title="En/Developer_Guide/Build_Instructions">here</a>.</p> + +<h3 id="Estruturar_o_Seu_Projeto">Estruturar o Seu Projeto</h3> + +<p>Mozilla includes a number of complex extensions that are integrated into its build process. It has thus been necessary to solve all of the issues involved in creating and registering XPCOM components, building JAR files and manifests, installing the lot into the Firefox <code>extensions/</code> directory and so forth. So it behooves us to piggyback on this infrastructure to build our extension.</p> + +<p>First of all, think of a catchy name for your extension and create a directory with that name under the <code>/mozilla/extensions/</code> directory. Use only lowercase letters. You should see a bunch of other directories (<code>inspector/</code>, <code>reporter/</code> and so forth) at the same level in the build tree.</p> + +<p>Note that before actually building anything, the Mozilla build system invokes a configuration process that generates the actual makefiles used for the build from makefile templates called <code>Makefile.in</code>. The actual makefiles tend to be very similar or identical to the templates, but the extra flexibility gained from having the makefiles generated dynamically is one of the things that makes the build system so powerful.</p> + +<h4 id="Anatomia_de_uma_Extensão_C_Simples">Anatomia de uma Extensão C++ Simples</h4> + +<p>We assume that you are using C++ to write XPCOM components that can be used either from other C++ components or from JavaScript. The process of creating a component is actually relatively straightforward when the Mozilla build system is used.</p> + +<p>In the simplest case, a component will consist of a single main directory with two subdirectories, <code>public/</code> and <code>src/</code>. The main directory and each subdirectory must contain a <code>Makefile.in</code> (from now on I’ll just refer to this file as a makefile although we know that it is actually used to generate the real makefile). This makefile says two things. First of all, it lists the subdirectories that make up the extension, so the build system knows where to look for additional makefiles. Secondly, it instructs the build system to create a new extension, rather than copying the components directly into Firefox’s binary directory. The main advantage of using an extension is that it is easy to package everything up and install it on another machine.</p> + +<p>So here’s your basic, plain-vanilla top-level makefile (<code>Makefile.in</code> in the main extension directory):</p> + +<pre>DEPTH = ../.. +topsrcdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = @srcdir@ + +include $(DEPTH)/config/autoconf.mk + +MODULE = myextension + +DIRS = public src + +XPI_NAME = myextension +INSTALL_EXTENSION_ID = myextension@mycompany.com +XPI_PKGNAME = myextension + +DIST_FILES = install.rdf + +include $(topsrcdir)/config/rules.mk +</pre> + +<p>A detailed description of the make process, describing the key features of this makefile, can be found <a href="/en/How_Mozilla's_build_system_works" title="en/How_Mozilla's_build_system_works">here</a>. <strong>MODULE</strong> and <strong>XPI_NAME</strong> are both set to the name of your extension; they should be repeated in all project makefiles so that all of the files land in the same place in the XPI staging area (see below). <strong>INSTALL_EXTENSION_ID</strong> is the unique ID of your extension. This can be a GUID, but the format shown above is prettier and, let’s face it, a lot easier to remember. You don’t have to provide an <strong>XPI_PKGNAME</strong>, but if you do an XPI file, suitable for distribution, is automatically created in the root of the XPI staging area (<code>/mozilla/$(MOZ_OBJDIR)/dist/xpi-stage/</code>).</p> + +<p>Every extension must include an <code>install.rdf</code> file that tells Firefox how to install it. This file should be located in the main extension directory and look something like this:</p> + +<pre class="brush: xml"><?xml version="1.0"?> + +<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:em="http://www.mozilla.org/2004/em-rdf#"> + <Description about="urn:mozilla:install-manifest"> + <em:id>myextension@mycompany.com</em:id> + <em:version>0.1</em:version> + + <em:targetApplication> + <!-- Firefox --> + <Description> + <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> + <em:minVersion>1.0+</em:minVersion> + <em:maxVersion>1.0+</em:maxVersion> + </Description> + </em:targetApplication> + + <!-- front-end metadata --> + <em:name>My First Extension</em:name> + <em:description>Just an example.</em:description> + <em:creator>allpeers.com</em:creator> + <em:homepageURL>http://www.allpeers.com/blog/</em:homepageURL> + </Description> +</RDF> +</pre> + +<p>There's a <a href="/en/Install_Manifests" title="en/Install_Manifests">detailed description</a> of the format of the <code>install.rdf</code> file. Use the <strong>DIST_FILES</strong> variable in the makefile to tell <code>make</code> to copy the file into the extension directory and (optional) XPI file.</p> + +<h4 id="Interfaces_Públicas">Interfaces Públicas</h4> + +<p>The <code>public/</code> directory contains any interfaces that need to be accessed by other modules. These can be <a class="external" href="http://www.mozilla.org/scriptable/xpidl/idl-authors-guide/index.html">IDL</a> files describing <a href="/en/XPCOM" title="en/XPCOM">XPCOM</a> interfaces, which are used to generate normal C++ header files for inclusion in your source files. They can also be normal C++ header files that are to be used directly by other modules. The easiest way to accomplish the latter is to use inline implementations for all methods so you don’t have any additional linking dependencies. Otherwise you will have to link statically to your module if you use these public headers in other modules. Personally I would discourage this practice (among other things, static linking means the same code gets loaded more than once into memory, and the code won’t be available from JavaScript or other non-C++ languages) and encourage the use of XPCOM wherever possible.</p> + +<p>The makefile in the <code>public/</code> directory should follow this model:</p> + +<pre>DEPTH = ../../.. +topsrcdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = @srcdir@ + +include $(DEPTH)/config/autoconf.mk + +MODULE = myextension +XPIDL_MODULE = myextension + +XPI_NAME = myextension + +EXPORTS = \ + myHeader.h \ + $(NULL) + +XPIDLSRCS = \ + myIFirstComponent.idl \ + myISecondComponent.idl \ + $(NULL) + +include $(topsrcdir)/config/rules.mk +</pre> + +<p><strong>XPIDL_MODULE</strong> is the name of the generated XPT file that contains type information about your <a class="external" href="http://www.mozilla.org/scriptable/xpidl/idl-authors-guide/index.html">IDL</a> interfaces. If you have multiple modules, make absolutely sure that you use a different value for <strong>XPIDL_MODULE</strong> for each one. Otherwise the first module’s XPT file will be overwritten by the second and you’ll get <strong>NS_ERROR_XPC_BAD_IID</strong> errors when you try to access its IDL interfaces from your code. The files under <strong>EXPORTS</strong> are copied directly to the <code>/mozilla/$(MOZ_OBJDIR)/dist/include/</code> directory and are thus accessible from other modules (the value of <strong>MOZ_OBJDIR</strong> is defined in <code>/mozilla/.mozconfig</code>). XPIDLSRCS are run through the IDL processor, and the generated C++ headers are copied into the same include directory. In addition, an XPT (type library) file is generated and placed in the <code>components/</code> subdirectory of your extension.</p> + +<h4 id="Ficheiros_Fonte">Ficheiros Fonte</h4> + +<p>Now it’s time to create the makefile and source files in the <code>src/</code> subdirectory. If you're implementing interfaces that you've described using IDL, the easiest way to do this is to leave the <code>src/</code> directory empty and run <code>make</code> on the <code>public/</code> directory only; this will be explained shortly.</p> + +<p>Then open the generated header file for your interface from <code>/mozilla/$(MOZ_OBJDIR)/dist/include/</code>. It contains stubs for the component .H and .CPP files that you can copy and paste into your implementation files. All you have to do is fill in the implementation stubs in the C++ file and you’re good to go.</p> + +<p>Here’s an example of the makefile you need to place into your <code>src</code> directory:</p> + +<pre class="eval">DEPTH = ../../.. +topsrcdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = @srcdir@ + +include $(DEPTH)/config/autoconf.mk + +IS_COMPONENT = 1 +<a href="/en/MODULE" title="en/MODULE">MODULE</a> = myextension +<a href="/en/LIBRARY_NAME" title="en/LIBRARY_NAME">LIBRARY_NAME</a> = myExtension +<a href="/en/USE_STATIC_LIBS" title="en/USE_STATIC_LIBS">USE_STATIC_LIBS</a> = 1 + +XPI_NAME = myextension + +<a href="/en/CPPSRCS" title="en/CPPSRCS">CPPSRCS</a> = \ + myFirstComponent.cpp \ + mySecondComponent.cpp \ + myExtension.cpp \ + $(NULL) + +include $(topsrcdir)/config/rules.mk + +<a href="/en/EXTRA_DSO_LDOPTS" title="en/EXTRA_DSO_LDOPTS">EXTRA_DSO_LDOPTS</a> += \ + $(MOZ_COMPONENT_LIBS) \ + $(NSPR_LIBS) \ + $(NULL) +</pre> + +<p>In this example, the first two files contain the implementation of the extension’s two components. The final file, <code>myExtension.cpp</code>, contains the code necessary to register these components, as described in the next section.</p> + +<h4 id="Registar_os_Seus_Componentes">Registar os Seus Componentes</h4> + +<p><a href="/pt-PT/docs/Mozilla/Tech/XPCOM/Guide/Alterações_XPCOM_Gecko_2.0" title="XPCOM changes in Gecko 2.0">Este artigo </a>explica como registar os componentes XPCOM no Gecko 2.0 e superior.</p> + +<h4 id="Criação_de_Extensão">Criação de Extensão</h4> + +<p>As mentioned above, you’ll probably want to build your extension immediately after creating your IDL files in order to generate the C++ stubs for your component implementations. I’m assuming that you’ve already built Firefox successfully. If not, return immediately to the beginning of this article and don’t come back til you have a functioning <code>firefox.exe</code>. Do not pass go. Do not collect $200.</p> + +<p>Still here? Okay, now we have to modify your <code>.mozconfig</code> (in the <code>/mozilla/</code> root directory) so that your extension is built along with Mozilla. Add the following line at the end of the file:</p> + +<pre class="brush: shell">ac_add_options --enable-extensions=default,myextension +</pre> + +<p>Now launch <code>make</code> from the Mozilla root:</p> + +<pre class="brush: shell">make -f client.mk build +</pre> + +<p>Even if you have an up-to-date Firefox build, you’ll have to wait a while for <code>make</code> to recurse over the entire Mozilla source tree looking for new stuff (on my machine, which is pretty fast, this takes a good 10-15 minutes). Eventually it will reach your extension and generate a bunch of stuff under <code>/mozilla/$(MOZ_OBJDIR)/</code>:</p> + +<ul> + <li>Exported header files and generated header files (from IDL) in <code>dist/include/</code></li> + <li>Static libraries for your modules in <code>dist/lib/</code> (in case other modules want to link statically to your stuff instead of using XPCOM).</li> + <li>XPI file in <code>dist/xpi-stage/myextension.xpi</code>.</li> + <li>Generated makefiles for your projects in <code>extensions/myextension/</code> (remember, we’re under <code>/mozilla/$(MOZ_OBJDIR)/</code>.</li> + <li>Everything else in <code><a class="link-mailto" href="mailto:dist/bin/extensions/myextension@mycompany.com" rel="freelink">dist/bin/extensions/myextension@mycompany.com</a>/</code>.</li> +</ul> + +<p>A lot of this stuff won’t get created on this first pass since <code>make</code> will gag when it doesn’t find the source files for your components. Don’t worry about this; all you need are the generated header files that contain the C++ implementation stubs. Go back and flesh out the C++ implementation of your components so that the build can complete next time. Remember that you should never, ever modify any of these generated files. Always modify the files used to generate them and rerun <code>make</code>. If you’re changing the generated files directly, you’re probably doing something wrong.</p> + +<p>The process of walking the entire Mozilla tree takes a long time. If you already have a Mozilla build, you can avoid this by creating a makefile for your extension directly. Go to the root of your $(MOZ_OBJDIR) and (from a bash-compatible shell) enter:</p> + +<pre class="eval">../build/autoconf/make-makefile extensions/myextension +</pre> + +<p>If your $(MOZ_OBJDIR) is located outside your $(TOPSRCDIR), you'll need to do:</p> + +<pre class="eval">$(TOPSRCDIR)/build/autoconf/make-makefile -t $(TOPSRCDIR) extensions/myextension +</pre> + +<p>in order for the script to know where your source is (it'll use the extension path you gave it relative to the current dir to figure out where you want your makefiles to go).</p> + +<p>This will generate the proper makefile for your extension. Whether you build the whole Mozilla tree or take this shortcut, you can build from now on by going to <code>/mozilla/$(MOZ_OBJDIR)/extensions/myextension/</code> and typing "make" on the command line. It should build your component without bothering with the rest of Mozilla. If everything works out, you’ll see your XPI file in the XPI staging area. You’ll also see the "exploded" version of the XPI (i.e. the unzipped directory structure) underneath <code>/mozilla/$(MOZ_OBJDIR)/dist/bin/extensions</code>. (If something goes wrong, figure out what, fix it and then come back here and add it to this article.)</p> + +<p>To make sure that the build really finished, launch Firefox and check that your extension is listed when you select Tools/Extensions. If you are using Firefox as your regular browser (and if you’re not, why not!?), you might be annoyed by the fact that you have to close regular Firefox before running your custom-built version. If so, try setting the <strong>MOZ_NO_REMOTE</strong> environment variable to "1" before running the development version of Firefox. You’ll also need to use a different profile for your development version:</p> + +<pre class="brush: shell">firefox -P <em>development</em> +</pre> + +<p>Where <em>development</em> is replaced with the name of the extra profile you’ve created. This will let you run both versions of Firefox simultaneously, saving you oodles of time over the course of the build/test cycle.</p> + +<h4 id="Nenhum_Local_Como_o_Chrome">Nenhum Local Como o Chrome</h4> + +<p>Yippee-ki-yay! Now you have an extension that does, well, absolutely nothing. It’s time to do something with those groovy components that you’ve implemented and registered. The simplest way to do this is to write some <a href="/en/JavaScript" title="en/JavaScript">JavaScript</a> and <a href="/en/XUL" title="en/XUL">XUL</a> code. At this point, it would be very helpful to have a bit of experience <a href="/en/Extensions" title="en/Extensions">writing "regular" extensions</a> (i.e. without using custom C++ components). If you’ve never done this, I strongly recommend that you think of a cool idea for something simple that you’ve always wanted to tweak in Firefox and write it. Just displaying a new menu item that opens a "Hello, World!" dialog box would be already be a great exercise to get warmed up with.</p> + +<p>Assuming you know how to write XUL/JavaScript extensions, you’re aware that the most important stuff goes in the <code>chrome/</code> directory of your extension. Well, the fact that you’re also using C++ components doesn’t change that one whit. So now you need to create the normal <code>content/</code>, <code>locale/</code> and <code>skin/</code> directories in which to place your chrome files. Personally I like placing these directly under the root directory of my module, but I don’t suppose it makes any difference if you prefer putting them under a <code>chrome/</code> subdirectory or whatever. Let freedom reign!</p> + +<p>Once you’ve written the necessary chrome files (for instance, an overlay that adds a menu item to instantiate and use one of your components), you need to package them up as part of your extension. This is accomplished through the use of a <a href="/en/JAR_Manifests" title="en/JAR_Manifests">JAR Manifest</a>. For our simple extension example, this file might look something like this:</p> + +<pre>myextension.jar: +% content myextension %content/ +% locale myextension en-US %locale/en-US/ +% skin myextension classic/1.0 %skin/classic/ +% overlay chrome://browser/content/browser.xul chrome://myextension/content/MyExtensionOverlay.xul + content/MyExtensionOverlay.js (content/MyExtensionOverlay.js) + content/MyExtensionOverlay.xul (content/MyExtensionOverlay.xul) + locale/en-US/MyExtension.dtd (locale/en-US/MyExtension.dtd) + locale/en-US/MyExtension.properties (locale/en-US/MyExtension.properties) + skin/classic/MyExtension.css (skin/classic/MyExtension.css) +</pre> + +<p>Place this code in a file called <code>jar.mn</code> in the root directory of your extension, making sure that the paths in parentheses point to actual files (when interpreted relative to the root directory). You also have to make one small change to the makefile in the same directory, adding the following line:</p> + +<pre class="eval">USE_EXTENSION_MANIFEST = 1 +</pre> + +<p>This tells <code>make</code> to create a single manifest file called <code>chrome.manifest</code> instead of creating separate manifests with goofy names for each package.</p> + +<p>Now launch <code>make</code> again, and you should see a <code>chrome</code> subdirectory appear in your extension (<code>/mozilla/$(MOZ_OBJDIR)<a class="link-mailto" href="mailto:/dist/bin/extensions/myextension@mycompany.com" rel="freelink">/dist/bin/extensions/myextension@mycompany.com</a>/</code>). Note that the <code>chrome</code> directory contains a JAR (i.e. ZIP) file with all the chrome files listed in <code>jar.mn</code> as well as a complete directory structure mirroring that of the JAR file. The directory structure, however, is empty. Why? I don’t know. Don’t worry about this, the files in the JAR are the ones that are actually used.</p> + +<h4 id="Mantedo-a_Complexa">Mantedo-a Complexa</h4> + +<p>If you’re developing a really complex extension with lots of <a href="/en/XPCOM" title="en/XPCOM">XPCOM</a> components, you’ll probably want to divide your code up into smaller modules.</p> + +<h5 id="Kinda_Sorta_Complex_Extensions">Kinda, Sorta Complex Extensions</h5> + +<p>For a moderately complex extension, it’s probably enough just to subdivide the code into a single level of modules. Let’s assume that you have a <code>base/</code> module that defines a bunch of basic XPCOM components and an <code>advanced/</code> module that defines some chrome as well as other components that use the basic components. Your complete directory structure will look something like this:</p> + +<ul> + <li>myextension + <ul> + <li>base + <ul> + <li>public</li> + <li>src</li> + </ul> + </li> + <li>advanced + <ul> + <li>content</li> + <li>locale + <ul> + <li>en-US</li> + <li>...other locales...</li> + </ul> + </li> + <li>public</li> + <li>skin + <ul> + <li>classic</li> + <li>...other skins...</li> + </ul> + </li> + <li>src</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Other than that, nothing really changes. The makefiles in the <code>base/</code> and <code>advanced/</code> directories should look more or less like your original root makefile, remembering to change the <strong>DEPTH</strong> variable to account for the fact that they’ve moved a level further away from the Mozilla root. You also need to remove the <strong>DIST_FILES</strong> variable since that’s going to be in the top-level makefile. Every makefile that generates anything should define the <strong>XPI_NAME</strong> variable to make sure generated files go into your extension and not into the global <code>components/</code> directory. In fact, just define this in every makefile to be safe. You can use the same <strong>MODULE</strong> in both <code>base/</code> and <code>advanced/</code> so that all the generated include files go into the same directory, but make sure that you don’t use the same <strong>XPIDL_MODULE</strong> in the two <code>public/</code> directories or one of the component type libraries (i.e. XPT files) will overwrite the other one and all hell will break loose.</p> + +<p>Each module must also have a different value for the <strong>LIBRARY_NAME</strong> variable. This is the name of the generated dynamic library, so if we call the libraries "myBase" and "myAdvanced", we’ll end up with <code>myBase.dll</code> and <code>myAdvanced.dll</code> (on Windows, at least). And each of these modules is going to have a separate C++ file for registering components. So there will be two files that look like <code>myExtension.cpp</code> in the original example, say <code>Base.cpp</code> and <code>Advanced.cpp</code>. Finally, each module will obviously have its own <code>jar.mn</code>, though they can reference the same JAR filename and package name if you want all the chrome files to be organized in a single JAR file and package. The only file that really stays put is <code>install.rdf</code>, which still exists once and only once in the extension root directory.</p> + +<p>As for the top-level makefile, it will now look like this:</p> + +<pre>DEPTH = ../.. +topsrcdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = @srcdir@ + +include $(DEPTH)/config/autoconf.mk + +MODULE = myextension + +DIRS = base advanced + +XPI_NAME = myextension +INSTALL_EXTENSION_ID = myextension@mycompany.com +XPI_PKGNAME = myextension + +DIST_FILES = install.rdf + +include $(topsrcdir)/config/rules.mk +</pre> + +<h5 id="Extensões_Complexas_Sérias">Extensões Complexas Sérias</h5> + +<p>At some point, even a single module may grow to the point where you want to divide it further into submodules. The difference between having separate modules and having a single module with separate submodules is that the submodules all share the same file for registering components (the famous <code>myExtension.cpp</code> file), and when compiled they create a single dynamic library. The decision to split a module into submodules is all about code organization; it doesn’t really affect the final product at all.</p> + +<p>To split a module into submodules, first create a subdirectory for each submodule. Then create an additional directory called <code>build/</code>. Each submodule will be configured to create a static library, and the <code>build/</code> directory will pull these libraries together to create a single dynamic component library. Confused? Here’s an example, showing just the <code>advanced/</code> subbranch of the <code>myextension/</code> directory:</p> + +<ul> + <li>advanced + <ul> + <li>build</li> + <li>intricate + <ul> + <li>public</li> + <li>src</li> + </ul> + </li> + <li>multifarious + <ul> + <li>public</li> + <li>src</li> + </ul> + </li> + <li>content</li> + <li>locale + <ul> + <li>en-US</li> + <li>...other locales...</li> + </ul> + </li> + <li>skin + <ul> + <li>classic</li> + <li>...other skins...</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>As you can see, we’ve split <code>advanced/</code> into two submodules: <code>intricate/</code> and <code>multifarious/</code>, and we’ve added an additional <code>build/</code> subdirectory. We’ve left the chrome directories directly under <code>advanced/</code>, since they aren’t tied to any specific submodule. This means that <code>jar.mn</code> will stay in the same place.</p> + +<p>The <code>intricate/</code> and <code>multifarious/</code> makefiles will look a lot like the original <code>advanced/</code> makefile, but we’ll need to tweak them a bit. As always, we have to adjust the <strong>DEPTH</strong> variable since the makefiles are deeper in the directory structure. And we should change the <strong>LIBRARY_NAME</strong> to indicate that we’re generating a static library for each submodule. By convention the "_s" suffix is used for this purpose. So let’s call them "myIntricate_s" and "myMultifarious_s". Finally, we define the variable <strong>FORCE_STATIC_LIB</strong>, resulting in a makefile that starts something like this:</p> + +<pre>DEPTH = ../../../../.. +topsrcdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = @srcdir@ + +include $(DEPTH)/config/autoconf.mk + +MODULE = myextension +LIBRARY_NAME = myIntricate_s +FORCE_STATIC_LIB = 1 +USE_STATIC_LIBS = 1 + +XPI_NAME = myextension + +...more stuff here... +</pre> + +<p>The <code>build</code> makefile pulls together the static libraries generated by the submodules and creates a single (dynamic) component library:</p> + +<pre>DEPTH = ../../../.. +topsrcdir = @top_srcdir@ +srcdir = @srcdir@ +VPATH = @srcdir@ + +include $(DEPTH)/config/autoconf.mk + +IS_COMPONENT = 1 +MODULE = myextension +LIBRARY_NAME = myAdvanced +USE_STATIC_LIBS = 1 + +XPI_NAME = myextension + +DEFINES += XPCOM_GLUE + +SHARED_LIBRARY_LIBS = \ + $(DIST)/lib/$(LIB_PREFIX)myIntricate_s.$(LIB_SUFFIX) \ + $(DIST)/lib/$(LIB_PREFIX)myMultifarious_s.$(LIB_SUFFIX) \ + $(DIST)/lib/$(LIB_PREFIX)xpcomglue_s.$(LIB_SUFFIX) \ + $(DIST)/lib/$(LIB_PREFIX)xul.$(LIB_SUFFIX) \ + $(DIST)/lib/$(LIB_PREFIX)nss3.$(LIB_SUFFIX) \ + $(NULL) + +CPPSRCS = \ + Advanced.cpp \ + $(NULL) + +include $(topsrcdir)/config/rules.mk + +LOCAL_INCLUDES += \ + -I$(srcdir)/../intricate/src \ + -I$(srcdir)/../multifarious/src \ + $(NULL) +</pre> + +<p>The makefile in the <code>advanced/</code> directory should list the <code>intricate/</code>, <code>multifarious/</code> and <code>build/</code> directories in its <strong>DIRS</strong> variable. Make sure that <code>build/</code> comes last since it can’t create the component library until the other makefiles have completed.</p> + +<h3 id="Outros_Tópicos">Outros Tópicos</h3> + +<h4 id="Adicionar_Ficheiros_de_Dados_às_Suas_Extensões">Adicionar Ficheiros de Dados às Suas Extensões</h4> + +<p>In some cases, you may wish to include additional files in your extension that don’t belong in the <code>chrome/</code> subdirectory. Examples might be database files or XML schemas. This can be achieved by adding a custom step to your makefile that copies the files from the source tree into the extension’s target directory.</p> + +<h5 id="Copiar_Ficheiros_de_Dados_para_a_Diretoria_de_Destino">Copiar Ficheiros de Dados para a Diretoria de Destino</h5> + +<p>Let’s say that you have some data files containing statistical information that you want to include in your extension and make available to your components. You’ve placed these files, which have the extension .TXT, into a <code>stats/</code> subdirectory under your extension directory in the source tree. The following makefile rule can be used to copy these files into the final target directory of the extension:</p> + +<pre>export:: + if test ! -d $(FINAL_TARGET)/stats; then \ + $(NSINSTALL) -D $(FINAL_TARGET)/stats; \ + fi + $(INSTALL) $(srcdir)/*.txt $(FINAL_TARGET)/stats +</pre> + +<h5 id="Aceder_aos_Ficheiros_de_Dados_a_partir_dos_Componentes">Aceder aos Ficheiros de Dados a partir dos Componentes</h5> + +<p>The trick to accessing your data files is to figure out where the home directory of your extension is. Rumor has it that at some future date, this will possible through the <code><a href="/en/XPCOM_Interface_Reference/nsIExtensionManager" title="en/XPCOM_Interface_Reference/nsIExtensionManager">nsIExtensionManager</a></code> interface or something similar. In the meantime, there is a simple and reliable hack that can be used to achieve this. In the implementation of any JavaScript XPCOM component, there is a special <strong>__LOCATION__</strong> (two leading and two trailing underscores) symbol that points to the component’s implementation file. So you can write a simple component which deduces the root directory of your extensions by extrapolating from its location.</p> + +<p><a class="external" href="http://www.builderau.com.au/program/soa/Creating_XPCOM_components_with_JavaScript/0,39024614,39206503,00.htm">This article</a> explains how to create an XPCOM component in JavaScript. You’ll need an IDL file for an interface that looks something like this:</p> + +<pre>interface myILocation : nsISupports +{ + readonly attribute nsIFile locationFile; +}; +</pre> + +<p>Place the IDL file in the <code>public/</code> directory of your project or subproject. In the <code>src/</code> directory, place the JavaScript file that implements the component. The component implementation will include the methods for retrieving the path or file for the extension’s home directory:</p> + +<pre class="brush: js">myLocation.prototype = +{ + QueryInterface: function(iid) + { + if (iid.equals(nsISupports)) + return this; + if (iid.equals(myILocation)) + return this; + + Components.returnCode = Components.results.NS_ERROR_NO_INTERFACE; + return null; + }, + + get locationFile() + { + return __LOCATION__.parent.parent; + } +} +</pre> + +<p>This assumes that the component resides in a subdirectory of the extension directory (by convention, this directory is called <code>components/</code>). The <code>parent</code> property of <strong>__LOCATION__</strong> returns the <code>components/</code>, and the <code>parent</code> of this is the extension directory.</p> + +<p>The last step is to modify the makefile of the source directory where you placed your JavaScript file so that it is copied into the appropriate location in the extension:</p> + +<pre>export:: + $(INSTALL) $(srcdir)/*.js $(FINAL_TARGET)/components +</pre> + +<p>Now you can instantiate an instance of this component and use the <code>locationFile</code> property to get an <code><a href="/en/XPCOM_Interface_Reference/nsIFile" title="en/XPCOM_Interface_Reference/nsIFile">nsIFile</a></code> interface that points to your extension’s home directory.</p> + +<h4 id="Using_Third-Party_Libraries">Using Third-Party Libraries</h4> + +<p>For more sophisticated extensions, you may want to integrate third-party libraries that provide specialized functionality for database connectivity, image processing, networking and the like. If you want your extension to run on all Firefox platforms, you will need to have the source code for the library in question, so I assume that this is available.</p> + +<p>The most convenient approach from the perspective of the development cycle is to create a Mozilla-style makefile for the library. This works well for libraries that have a straightforward make process without extensive configuration. A good example of this is the SQLite library included in the Mozilla build tree at <code>db/sqlite</code>. By adapting the makefile in this way, the library is created as part of the standard Mozilla build process, which eliminates additional build steps. The downside is that you will need to update the modified makefile any time a new version of the library is released.</p> + +<p>For libraries that have complex configuration processes, use a non-standard compiler or have other special characteristics, it may be unfeasible to create a Mozilla-compliant makefile. In this case, I would recommend placing the entire library distribution inside the project or subproject that uses it. So if library <code>acmelib</code> is used inside the <code>multifarious/</code> subproject in the above example, it would be placed as a subdirectory underneath that subproject (at the same level as <code>public/</code> and <code>src/</code>).</p> + +<p>Of course, this means that you will have to build <code>acmelib</code> manually on all platforms before launching the Mozilla build. But at least you can then refer to include files and import libraries from your component using relative paths.</p> + +<h4 id="Building_for_Multiple_Platforms">Building for Multiple Platforms</h4> + +<p>TODO</p> + +<div class="originaldocinfo"> +<h2 id="Original_Document_Information">Original Document Information</h2> + +<ul> + <li>Author: Matthew Gertner - July 26, 2005.</li> + <li>Permission granted to migrate in Jan 2006, including permission to relicense under the CC:By-SA.</li> + <li>Original Source: <a class="external" href="http://www.allpeers.com/blog/creating-complex-firefox-extensions/" rel="freelink">http://www.allpeers.com/blog/creatin...ox-extensions/</a></li> +</ul> +</div> + +<p> </p> diff --git a/files/pt-pt/mozilla/add-ons/distribuicao/index.html b/files/pt-pt/mozilla/add-ons/distribuicao/index.html new file mode 100644 index 0000000000..eede6b7581 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/distribuicao/index.html @@ -0,0 +1,78 @@ +--- +title: Assinar e distribuir os seus extras +slug: Mozilla/Add-ons/Distribuicao +tags: + - Extensões + - Extensões da Web + - Extras + - assinatura + - distribuição + - publicação + - revisões +translation_of: Mozilla/Add-ons/Distribution +--- +<div>{{AddonSidebar}}</div> + +<p>Os extras precisam de ser assinados antes de serem instalados nas versões beta e de lançamento do Firefox. Este processo de assinatura ocorre via addons.mozilla.org (AMO), independentemente de optar por distribuir o seu extra via AMO ou por si mesmo.</p> + +<p>Nós aqui analisamos os requisitos de assinatura e as revisões relacionadas, antes de discutir como escolher entre o distribuir no AMO ou distribuir um extra por si mesmo. Nós também analisamos os canais disponíveis no AMO e respondemos a questões sobre propriedade e disputas de código.</p> + +<h2 class="brush: js" id="Assinar_os_seus_extras">Assinar os seus extras</h2> + +<p>Starting with Firefox 43, add-on extensions and multi-item add-ons that include extensions need to be signed by Mozilla before they can install in release and beta versions of Firefox. Themes, and other types of add-ons such as spelling dictionaries, don't need to be signed.</p> + +<p>Unsigned extensions can be installed in <a href="/en-US/Firefox/Developer_Edition">Developer Edition</a>, Nightly, and <a href="/en-US/Firefox/Enterprise_deployment">ESR</a> versions of Firefox, after toggling the <em>xpinstall.signatures.required</em> preference in <code>about:config</code>.</p> + +<p>Mozilla signs add-ons through the <a href="https://addons.mozilla.org/developers/addon/submit">AMO</a> website and provides three methods for submitting your add-on for signing:</p> + +<ul> + <li>upload your add-on through the <a href="/en-US/Add-ons/Distribution/Submitting_an_add-on">Developer Hub on AMO</a>.</li> + <li>use the <a href="http://addons-server.readthedocs.io/en/latest/topics/api/signing.html">addons.mozilla.org signing API</a>.</li> + <li>use <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_sign">web-ext sign.</a></li> +</ul> + +<p>All the signing options are subject to the <a href="/en-US/Add-ons/AMO/Policy/Agreement">Firefox Add-on Distribution Agreement</a>.</p> + +<p>Using the signing API or web-ext returns you signed add-ons, with no distribution listing created on AMO. If you take the option to upload your add-on through the AMO Developer Hub, you're given a choice between listing on AMO or self-distribution. If you choose self-distribution, at the end of the process you download signed copies of your add-on.</p> + +<p>Regardless of the method used all add-ons must pass an automated validation before they are signed. They may also be subject to a manual code review. The review criteria applied to add-ons are found in the <a href="/en-US/docs/Mozilla/Add-ons/AMO/Policy/Reviews">Add-on Policies</a>.</p> + +<h2 id="Distributir_o_seu_extra">Distributir o seu extra</h2> + +<p>You aren't required to list or distribute your add-on through AMO. You'll, therefore, need to decide if you want to distribute and list your add-on through AMO or distribute it yourself. Here are some things you should consider:</p> + +<ul> + <li>AMO is a very popular distribution platform, with millions of monthly visitors and installations. It's integrated into the Firefox Add-ons Manager, allowing for easy installation of add-ons published on AMO.</li> + <li>When an add-on is listed on AMO, updates to installed copies are handled automatically by Firefox each time a new version is listed on AMO.<br> + To enable Firefox to automatically update self-distributed add-ons, the URL where Firefox can find updates needs to be included in the add-on manifest's <a href="/en-US/Add-ons/Updates">update_link</a> key. Self-distributed add-ons that don't have an update URL check AMO for updates and are updated to a listed version, if one is available.</li> +</ul> + +<p>For more information on how to submit an add-on for distribution on AMO or self-distribution, see <a href="/en-US/docs/Mozilla/Add-ons/Distribution/Submitting_an_add-on">Submitting an add-on.</a></p> + +<h2 id="Mais_informação_sobre_AMO">Mais informação sobre AMO</h2> + +<h3 id="Propriedade">Propriedade</h3> + +<p>Os extras no AMO podem ter vários utilizadores com permissão para atualizar e gerir a listagem. Os autores de um extra podem transferir a propriedade e adicionar programadores à listagem de um extra por meio do <em>Hub </em>do Programdor. Não é necessária nenhuma interação com os representantes da Mozilla para uma transferência de propriedade.</p> + +<p> </p> + +<h4 id="Para_transferir_propriedade">Para transferir propriedade</h4> + +<ul> + <li>Make sure the new owner has an account on <a href="https://addons.mozilla.org/">addons.mozilla.org</a>. New accounts can be created using the "Register or Log in" button, after which the owner must confirm their email address.</li> + <li>Sign into your account on the <a href="https://addons.mozilla.org/developers/">Add-on Developer Hub</a>, and click "Edit Listing" for the extension you want to transfer.</li> + <li>On the left-hand side of the screen, you will see a blue box labeled "Edit Information". Click "Manage Authors & License" — from the resulting page you can add and remove authors.</li> + <li>One you have added the new author's email address, set that person as the extension owner and make sure the "Listed" box has a checkmark. Now you can remove yourself by clicking the "x" next to your email address.</li> + <li>When you're done, click "Save Changes". The new owner will be able to manage updates, listing information, etc., when logged in.</li> +</ul> + +<p> </p> + +<h3 id="Disputas_de_códogo">Disputas de códogo</h3> + +<p>Many add-ons allow their source code to be viewed. This does not mean that the source code is open source or available for use in another add-on. The original author of an add-on retains copyright of their work unless otherwise noted in the add-on's license.</p> + +<p>If we're notified of a copyright or license infringement, we will take steps to address the situation per the DMCA, which may include taking down the add-on listing. Details about this process and how to report trademark or licensing issues can be <a href="https://www.mozilla.org/en-US/about/legal/report-abuse/">found here</a>.</p> + +<p>If you are unsure of the current copyright status of an add-on's source code, you must contact the author and get explicit permission before using the source code.</p> diff --git a/files/pt-pt/mozilla/add-ons/index.html b/files/pt-pt/mozilla/add-ons/index.html new file mode 100644 index 0000000000..2b69084b27 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/index.html @@ -0,0 +1,111 @@ +--- +title: Extras (Add-ons) +slug: Mozilla/Add-ons +tags: + - Extensões + - Extras + - Landing + - Mozilla + - extensão +translation_of: Mozilla/Add-ons +--- +<div>{{AddonSidebar}}</div> + +<p><span class="seoSummary">Os extras permitem que os responsáveis pelo desenvolvimento estendam e modifiquem a funcionalidade do Firefox. As mesmas são criadas utilizando as tecnologias da Web padrão - CSS, HTML e JavaScript - mais algumas APIs de JavaScript dedicadas. Entre outras coisas, um extra poderia:</span></p> + +<ul> + <li>Modificar e alterar a aparência ou conteúdo de um site em particualr</li> + <li>Modificar a interface de utilizador do Firefox</li> + <li>Adicionar novas funcionalidades ao Firefox</li> +</ul> + +<h2 id="Desenvolver_extras">Desenvolver extras</h2> + +<p>Existem, de momento, vários conjuntos de ferramentas utilizadas para desenvolver Aplicações Complementares mas as chamadas <a href="/en-US/Add-ons/WebExtensions">Extensões da Web</a> vão tornar-se o padrão pelo final de 2017. Das restantes a expectativa é de que se tornem <a href="/en-US/Add-ons/Overlay_Extensions">obsoletas</a> dentro do mesmo periodo de tempo.</p> + +<p>Neste documento vai encontrar informação sobre as opções disponíveis para desenvolver aplicações complementares para que possa decidir qual a melhor para si agora e no futuro.</p> + +<h3 id="Criar_um_Novo_Extra">Criar um Novo Extra</h3> + +<p>Se está a desenvolver uma nova aplicação complementar recomendamos que escolha entre um dos dois seguintes métodos. Até que a transição para as Extensões da Web esteja finalizada, existirão prós e contras em relação a ambos os métodos. Por favor leia atentamente as opções para decidir qual a melhor para funcionar com a sua aplicação.</p> + +<ul class="card-grid"> + <li style="position: relative; max-width: 400px;"> + <div style="margin-bottom: 70px;"> + <h4 id="Extensões_da_Web"><a href="pt-PT/Add-ons/WebExtensions">Extensões da Web</a></h4> + + <p>As Extensões da Web são o futuro das Aplicações Complementares para o Firefox. Se a puder utilizar, a API das Extensões da Web será a melhor escolha. Pode começar a desenvolver e publicar Extensões da Web imediatamente, mas as mesmas ainda estão num estado embrionário.<br> + <br> + A maioria das funcionalidades da API Extensões da Web estão também disponíveis no <a href="/en-US/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">Firefox para Android</a>.</p> + + <p>We're preparing a first full release for <a href="https://wiki.mozilla.org/RapidRelease/Calendar">Firefox 48</a>.</p> + </div> + <a class="card-grid-button" href="/en-US/Add-ons/WebExtensions">Saber mais</a></li> + <li style="position: relative; max-width: 400px;"> + <div style="margin-bottom: 70px;"> + <h4 id="SDK_de_Extras"><a href="/en-US/Add-ons/SDK">SDK de Extras</a></h4> + + <p>O SDK de Extra proporcina várias APIs para desenvolvimento de extras para o Firefox, e uma ferramenta para desenvolvimento, teste e finalização.</p> + + <p>Também pode executar as extensões de SDK de Extras no<a href="/en-US/Add-ons/SDK/Tutorials/Mobile_development"> Firefox para Android</a>.</p> + + <p>We encourage you to use only <a href="/en-US/Add-ons/SDK/High-Level_APIs">high-level APIs</a> because this will make it easier to migrate to WebExtensions down the road.</p> + </div> + <a class="card-grid-button" href="/en-US/Add-ons/SDK">Learn more</a></li> +</ul> + +<h3 id="Migrar_um_Extra_Existente">Migrar um Extra Existente</h3> + +<p>There are changes coming to Firefox in the next year that will make browsing more reliable for users, and creating add-ons easier for developers. Your add-on may require updating to maintain its compatibility, but once this is done and the transition is complete, your add-on will be more interoperable, secure, and future-proof than ever.</p> + +<p>We've created <a href="https://wiki.mozilla.org/Add-ons/developer/communication">resources, migration paths, office hours, and more</a>, to ensure you have the support you need to get through the transition.</p> + +<p>To get started, use the <a href="https://compatibility-lookup.services.mozilla.com/">add-on compatibility checker</a> to see if your add-on will be affected.</p> + +<h2 id="Publicação_de_extras">Publicação de extras</h2> + +<p><a href="https://addons.mozilla.org">Addons.mozilla.org</a>, commonly known as "AMO," is Mozilla's official site for developers to list add-ons, and for users to discover them. By uploading your add-on to AMO, you can participate in our community of users and creators, and find an audience for your add-on.</p> + +<p>You are not required to list your add-on on AMO, but starting with Firefox 40, your code must be signed by Mozilla or users won't be able to install it.</p> + +<p>For an overview of the process of publishing your add-on, see <a href="https://developer.mozilla.org/en-US/Add-ons/Distribution">Signing and distributing your add-on</a>.</p> + +<h2 id="Outros_tipos_de_extras">Outros tipos de extras</h2> + +<p>Generally, when people speak of add-ons they're referring to extensions, but there are a few other add-on types that allow users to customize Firefox. Those add-ons include:</p> + +<ul> + <li><a href="https://developer.mozilla.org/Add-ons/Themes/Background">Lightweight themes</a> are a simple way to provide limited customization for Firefox.</li> + <li><a href="/en-US/Add-ons/Firefox_for_Android">Mobile add-ons</a> are add-ons for Firefox for Android. Note, though, that we intend to deprecate some of the technology underlying these APIs. In the future, WebExtensions will be fully supported on Firefox for Android.</li> + <li><a href="/en-US/docs/Creating_OpenSearch_plugins_for_Firefox">Search engine plugins</a> add new search engines to the browser's search bar.</li> + <li><a href="/pt-PT/docs/Mozilla/Criação_de_um_complemento_de_dicionário_de_verificação_ortográfica">Dicionários do utilizador</a> são complementos que o deixam verificar a ortografia em diferentes idiomas.</li> + <li><a href="https://support.mozilla.org/pt-PT/kb/use-firefox-interface-other-languages-language-pack">Pacotes de idioma </a>são complementos que o deixam ter mais idiomas disponíveis para a interface do utilizador do Firefox.</li> +</ul> + +<hr> +<h2 id="Contacte-nos">Contacte-nos</h2> + +<p>Pode utilizar as hiperligações abaixo para obetr ajuda, manter-se atualizado com as notícias relacionadas com os complementos, e dar-nos a sua opinião/comentário.</p> + +<h3 id="Fórum_de_extras">Fórum de extras</h3> + +<p>Utilize o <a href="https://discourse.mozilla-community.org/c/add-ons">fórum de conversação sobre os complementos</a> para discutir todos aspetos do desenvolvimento de complementos e obter ajuda.</p> + +<h3 id="Listas_de_endereçosdiscussão">Listas de endereços/discussão</h3> + +<p>Use the <strong>dev-addons</strong> list to discuss development of the add-ons ecosystem, including the development of the WebExtensions system and of AMO:</p> + +<ul> + <li><a href="https://mail.mozilla.org/listinfo/dev-addons">dev-addons list info</a></li> + <li><a href="https://mail.mozilla.org/pipermail/dev-addons/">dev-addons archives</a></li> +</ul> + +<h3 id="IRC">IRC</h3> + +<p>If you're a fan of IRC, you can get in touch at:</p> + +<ul> + <li><a href="irc://irc.mozilla.org/addons">#addons</a> (discussion of the add-ons ecosystem)</li> + <li><a href="irc://irc.mozilla.org/extdev">#extdev</a> (general discussion of add-on development)</li> + <li><a href="irc://irc.mozilla.org/webextensions">#webextensions</a> (discussion of WebExtensions in particular)</li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/linhas_diretrizes_para_extras/index.html b/files/pt-pt/mozilla/add-ons/linhas_diretrizes_para_extras/index.html new file mode 100644 index 0000000000..4293fe9c74 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/linhas_diretrizes_para_extras/index.html @@ -0,0 +1,8 @@ +--- +title: Linhas Diretrizes para Extras +slug: Mozilla/Add-ons/Linhas_diretrizes_para_extras +translation_of: 'https://extensionworkshop.com/documentation/publish/add-on-policies/' +--- +<div class="warning"> +<p>Este documento já não é válido. Por favor, consulte o documento de <a href="/pt-PT/docs/Mozilla/Add-ons/AMO/Policy/Revisões">Políticas de Revisão</a> para o conjunto atual das políticas de extras.</p> +</div> diff --git a/files/pt-pt/mozilla/add-ons/sdk/index.html b/files/pt-pt/mozilla/add-ons/sdk/index.html new file mode 100644 index 0000000000..1c160220ae --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/sdk/index.html @@ -0,0 +1,97 @@ +--- +title: Add-on SDK +slug: Mozilla/Add-ons/SDK +tags: + - Add-on SDK + - Jetpack +translation_of: Archive/Add-ons/Add-on_SDK +--- +<div class="warning"> +<p>Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.</p> + +<p>Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use <a href="/en-US/Add-ons/WebExtensions">WebExtensions</a> instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.</p> + +<p><strong>Starting from <a href="https://wiki.mozilla.org/RapidRelease/Calendar">Firefox 53</a>, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.</strong></p> + +<p><strong>Starting from <a href="https://wiki.mozilla.org/RapidRelease/Calendar">Firefox 57</a>, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android. </strong></p> + +<p>Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to use WebExtensions APIs if they can. See the <a href="https://blog.mozilla.org/addons/2017/02/16/the-road-to-firefox-57-compatibility-milestones/">"Compatibility Milestones" document</a> for more information.</p> + +<p>A wiki page containing <a href="https://wiki.mozilla.org/Add-ons/developer/communication">resources, migration paths, office hours, and more</a>, is available to help developers transition to the new technologies.</p> +</div> +<p>Pode criar extras do Firefox utilizando <strong><u>Add-on SDK</u></strong>. Pode utilizar várias tecnologias da Web padrão: CSS, HTML e JavaScript, para criar os extras. O SDK inclui as APIs de JavaScript APIs, que pode utilziar para criar extras e ferramentas para a criação, execução, testes, e empacotamento dos extras.</p> + +<hr> +<h3 id="Tutoriais"><a href="/en-US/Add-ons/SDK/Tutorials">Tutoriais</a></h3> + +<div class="column-container"> +<div class="column-half"> +<dl> + <dt><a href="/en-US/Add-ons/SDK/Tutorials#getting-started">Getting started</a></dt> + <dd>How to <a href="/en-US/Add-ons/SDK/Tutorials/Installation">install the SDK</a> and <a href="/en-US/Add-ons/SDK/Tutorials/Getting_Started_(jpm)">use the jpm tool</a> to develop, test, and package add-ons.</dd> + <dt><a href="/en-US/Add-ons/SDK/Tutorials#interact-with-the-browser">Interact with the browser</a></dt> + <dd><a href="/en-US/Add-ons/SDK/Tutorials/Open_a_Web_Page">Open web pages</a>, <a href="/en-US/Add-ons/SDK/Tutorials/Listen_For_Page_Load">listen for pages loading</a> and <a href="/en-US/Add-ons/SDK/Tutorials/List_Open_Tabs">list open pages</a>.</dd> + <dt><a href="/en-US/Add-ons/SDK/Tutorials#development-techniques">Development techniques</a></dt> + <dd>Learn about common development techniques, such as <a href="/en-US/Add-ons/SDK/Tutorials/Unit_testing">unit testing</a>, <a href="/en-US/Add-ons/SDK/Tutorials/Logging">logging</a>, <a href="/en-US/Add-ons/SDK/Tutorials/Creating_Reusable_Modules">creating reusable modules</a>, <a href="/en-US/Add-ons/SDK/Tutorials/l10n">localization</a>, and <a href="/en-US/Add-ons/SDK/Tutorials/Mobile_development">mobile development</a>.</dd> +</dl> +</div> + +<div class="column-half"> +<dl> + <dt><a href="/en-US/Add-ons/SDK/Tutorials#create-user-interfaces">Create user interface components</a></dt> + <dd>Create user interface components such as <a href="/en-US/Add-ons/SDK/Tutorials/Adding_a_Button_to_the_Toolbar">toolbar buttons</a>, <a href="/en-US/Add-ons/SDK/Tutorials/Add_a_Context_Menu_Item">context menus</a>, <a href="/en-US/Add-ons/SDK/Tutorials/Add_a_Menu_Item_to_Firefox">menu items</a>, and <a href="/en-US/Add-ons/SDK/Tutorials/Display_a_Popup">dialogs</a>.</dd> + <dt><a href="/en-US/Add-ons/SDK/Tutorials#modify-web-pages">Modify web pages</a></dt> + <dd>Modify pages <a href="/en-US/Add-ons/SDK/Tutorials/Modifying_Web_Pages_Based_on_URL">matching a URL pattern</a> or dynamically <a href="/en-US/Add-ons/SDK/Tutorials/Modifying_the_Page_Hosted_by_a_Tab">modify a particular tab</a>.</dd> + <dt><a href="/en-US/Add-ons/SDK/Tutorials/Annotator">Putting it together</a></dt> + <dd>Walkthrough of the Annotator example add-on.</dd> +</dl> +</div> +</div> + +<hr> +<h3 id="Guias">Guias</h3> + +<div class="column-container"> +<div class="column-half"> +<dl> + <dt><a href="/en-US/Add-ons/SDK/Guides#contributors-guide">Contributor's guide</a></dt> + <dd>Learn <a href="/en-US/Add-ons/SDK/Guides/Getting_Started">how to start contributing</a> to the SDK and about the most important idioms used in the SDK code such as <a href="/en-US/Add-ons/SDK/Guides/Modules">modules</a>, <a href="/en-US/Add-ons/SDK/Guides/Classes_and_Inheritance">classes and inheritance</a>, <a href="/en-US/Add-ons/SDK/Guides/Private_Properties">private properties</a>, and <a href="/en-US/Add-ons/SDK/Guides/Content_Processes">content processes</a>.</dd> + <dt><a href="/en-US/Add-ons/SDK/Guides#sdk-infrastructure">SDK infrastructure</a></dt> + <dd>Aspects of the SDK's underlying technology: <a href="/en-US/Add-ons/SDK/Guides/Module_structure_of_the_SDK">modules</a>, the <a href="/en-US/Add-ons/SDK/Guides/Program_ID">Program ID</a> and the rules defining <a href="/en-US/Add-ons/SDK/Guides/Firefox_Compatibility">Firefox compatibility</a>.</dd> + <dt><a href="/en-US/Add-ons/SDK/Guides/Content_Scripts">Content scripts</a></dt> + <dd>A detailed guide to working with content scripts.</dd> +</dl> +</div> + +<div class="column-half"> +<dl> + <dt><a href="/en-US/Add-ons/SDK/Guides#sdk-idioms">SDK idioms</a></dt> + <dd>The SDK's <a href="/en-US/Add-ons/SDK/Guides/Working_with_Events">event framework</a> and the <a href="/en-US/Add-ons/SDK/Guides/Two_Types_of_Scripts">distinction between add-on scripts and content scripts</a>.</dd> + <dt><a href="/en-US/Add-ons/SDK/Guides/XUL_Migration_Guide">XUL migration</a></dt> + <dd>A guide to <a href="/en-US/Add-ons/SDK/Guides/XUL_Migration_Guide">porting XUL add-ons to the SDK</a>. This guide includes a <a href="/en-US/Add-ons/SDK/Guides/XUL_vs_SDK">comparison of the two toolsets</a> and a <a href="/en-US/Add-ons/SDK/Guides/Porting_the_Library_Detector">working example</a> of porting a XUL add-on.</dd> + <dt><a href="/en-US/Add-ons/SDK/Guides/Multiprocess_Firefox_and_the_SDK">Multiprocess Firefox and the SDK</a></dt> + <dd>How to check whether your add-on is compatible with multiprocess Firefox or not and fix it accordingly.</dd> +</dl> +</div> +</div> + +<hr> +<h3 id="Referência">Referência</h3> + +<div class="column-container"> +<div class="column-half"> +<dl> + <dt><a href="/en-US/Add-ons/SDK/High-Level_APIs">High-Level APIs</a></dt> + <dd>Reference documentation for the high-level SDK APIs.</dd> + <dt><a href="/en-US/Add-ons/SDK/Tools">Tools reference</a></dt> + <dd>Reference documentation for the <a href="/en-US/Add-ons/SDK/Tools/jpm">jpm tool</a> used to develop, test and package add-ons, the <a href="/en-US/Add-ons/SDK/Tools/console">console</a> global used for logging, and the <a href="/en-US/Add-ons/SDK/Tools/package_json">package.json</a> file.</dd> +</dl> +</div> + +<div class="column-half"> +<dl> + <dt><a href="/en-US/Add-ons/SDK/Low-Level_APIs">Low-Level APIs</a></dt> + <dd>Reference documentation for the low-level SDK APIs.</dd> +</dl> +</div> +</div> diff --git a/files/pt-pt/mozilla/add-ons/themes/conceitos_tema/index.html b/files/pt-pt/mozilla/add-ons/themes/conceitos_tema/index.html new file mode 100644 index 0000000000..bb59c4386f --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/themes/conceitos_tema/index.html @@ -0,0 +1,230 @@ +--- +title: Conceitos de Tema +slug: Mozilla/Add-ons/Themes/Conceitos_tema +tags: + - Tema + - extra +translation_of: Mozilla/Add-ons/Themes/Theme_concepts +--- +<div>{{AddonSidebar()}}</div> + +<p>Os temas desenvolvidos utilizando a <a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions">WebExtensions API</a> no Firefox permitem-lhe alterar a aparência do navegador ao adicionar imagens na área do cabeçalho do navegador Firefox; esta é a área por trás da barra de menus, barras de ferramentas, barra de endereço, barra de pesquisa e seuparador de faixa.</p> + +<p>Estas opções de temas podem ser implementadas como temas estáticos (embora as próprias imagens do tema possam ser animadas) ou como temas dinâmicos criados numa extensão do navegador.</p> + +<div class="note"> +<p>If you have a <a href="/en-US/docs/Mozilla/Add-ons/Themes/Lightweight_themes">lightweight theme</a> it will be converted to this new theme format automatically before lightweight themes are deprecated. You do not need to port your theme. However, please feel free to update your themes to use any of the new features described here.</p> +</div> + +<h2 id="Temas_estásticos">Temas estásticos</h2> + +<p>Static themes are specified using the same resources as a browser extension: a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> file to define the theme components with those components stored in the same folder as the manifest.json file or a sub folder. These resources are then packed in a zip for publication on <a href="https://addons.mozilla.org">addons.mozilla.org</a> (AMO).</p> + +<div class="note"> +<p>A theme and browser extension functionality cannot be defined in one package, such as including a theme to complement an extension. You can, however, programmatically include a theme in an extension using the Theme API. See <a href="#Dynamic_themes">Dynamic themes</a>.</p> +</div> + +<h3 id="Definir_um_tema">Definir um tema</h3> + +<p>To create a theme (in this example a simple, single image theme):</p> + +<ul> + <li>Create a folder in a suitable location on your computer.</li> + <li>Add the theme image file to the folder: + <pre><mytheme> + <your_header_image>.<type></pre> + </li> + <li>Create a file called manifest.json in the folder and edit its content as follows: + <pre class="brush: json">{ + "manifest_version": 2, + "version": "1.0", + "name": "<your_theme_name>", + "theme": { + "images": { + "headerURL": "<your_header_image>.<type>" + }, + "colors": { + "accentcolor": "#FFFFFF", + "textcolor": "#000" + } + } +} +</pre> + Where: + + <ul> + <li><code>"accentcolor":</code> is the heading area background color for your theme.</li> + <li><code>"</code><code>textcolor</code><code>":</code> the color of the text in the heading area.</li> + </ul> + </li> + <li>Package your theme and submit it to AMO, <a href="/en-US/Add-ons/WebExtensions/Publishing_your_WebExtension">following these instructions</a>.</li> +</ul> + +<h3 id="Static_theme_approaches">Static theme approaches</h3> + +<p>There are two approaches you can take to theming the header area of Firefox: using a single image or using multiple images. You could combine the two, but it’s easier to treat them separately.</p> + +<h4 id="Single_image_themes">Single image themes</h4> + +<p>This is the basic or minimal theming option, where you define:</p> + +<ul> + <li>a single image, which is anchored to the top right of the header area.</li> + <li>A color for the text in the header.</li> +</ul> + +<p>The area your header image needs to fill is a maximum of 200 pixels high. The maximum image width is determined by the resolution of the monitor Firefox is displaying on and how much of the monitor Firefox is using. Practically, this means you would need to allow for a width of up to 5120 pixels wide (for the next generation of 5k monitors). However, rather than creating a very wide image, a better approach is to use a narrower image with a transparent left edge so that it fades to the background color. For example, we could use this image<br> + <img alt="An image of a weta (the common name for a group of about 70 insect species in the families Anostostomatidae and Rhaphidophoridae, endemic to New Zealand) with the left edge fading to total transparency." src="https://mdn.mozillademos.org/files/15215/weta.png" style="height: 200px; width: 406px;"><br> + combined with a complementary background color, to create this effect in the header<br> + <img alt="A single image theme using the weta.png image" src="https://mdn.mozillademos.org/files/15217/basic_theme.png" style="height: 113px; width: 679px;"></p> + +<p>See details about this theme in the <a href="https://github.com/mdn/webextensions-examples/tree/master/themes">themes</a> example <a href="https://github.com/mdn/webextensions-examples/tree/master/themes/weta_fade">weta_fade</a>.</p> + +<p>Obviously, you can still provide a single wide image if you prefer.</p> + +<h4 id="Multiple_image_themes">Multiple image themes</h4> + +<p>As an alternative to creating a single image theme, you have the option to use multiple images. These images can be individually anchored to locations within the header, with the option to apply tiling to each image.</p> + +<p>Depending on the effect you want to create you may need to suppress the mandatory <code>"</code><code>headerURL</code><code>":</code> image with an empty or transparent image. You would use an empty or transparent image if, for example, you wanted to tile a centrally justified image, such as<br> + <img alt="An image of a weta (the common name for a group of about 70 insect species in the families Anostostomatidae and Rhaphidophoridae, endemic to New Zealand) with the left and right edges fading to total transparency." src="https://mdn.mozillademos.org/files/15219/weta_for_tiling.png" style="height: 200px; width: 270px;"><br> + to create this effect<br> + <img alt="A single image theme using the additional images option to align an image to the center of the heading and tile it. " src="https://mdn.mozillademos.org/files/15221/tiled_theme.png" style="height: 113px; width: 679px;"><br> + Here you specify the weta image like this:</p> + +<pre class="brush: json" dir="ltr">"images": { + "headerURL": "empty.png", + "additional_backgrounds": [ "weta_for_tiling.png"] +},</pre> + +<p dir="ltr">and the images tiling with:</p> + +<pre class="brush: json" dir="ltr">"properties": { + "additional_backgrounds_alignment": [ "top" ], + "additional_backgrounds_tiling": [ "repeat" ] +},</pre> + +<p>Full details of how to setup this theme can be found in the <a href="https://github.com/mdn/webextensions-examples/tree/master/themes">themes</a> example <a href="https://github.com/mdn/webextensions-examples/tree/master/themes/weta_tiled">weta_tiled</a>. Full detais of the alignment and tiling options can be found in the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme">"theme" key description</a>.</p> + +<p>Alternatively, you can use multiple images, say combining the original weta image with this one anchored to the left of the header<br> + <img alt="An image of a weta (the common name for a group of about 70 insect species in the families Anostostomatidae and Rhaphidophoridae, endemic to New Zealand) with the right edge fading to total transparency." src="https://mdn.mozillademos.org/files/15223/weta-left.png" style="height: 200px; width: 406px;"><br> + to create this effect<br> + <img alt="A theme using the additional images option to place two mirrored image to the left and right of the browser header." src="https://mdn.mozillademos.org/files/15225/multi_image_theme.png" style="height: 113px; width: 679px;"></p> + +<p>Where the images are specified with:</p> + +<pre class="brush: json" dir="ltr">"images": { + "headerURL": "empty.png", + "additional_backgrounds": [ "weta.png", "weta-left.png"] +},</pre> + +<p dir="ltr">and their alignment by:</p> + +<pre class="brush: json" dir="ltr">"properties": { + "additional_backgrounds_alignment": [ "right top" , "left top" ] +},</pre> + +<p>Full details of how to setup this theme can be found in the <a href="https://github.com/mdn/webextensions-examples/tree/master/themes">themes</a> example <a href="https://github.com/mdn/webextensions-examples/tree/master/themes/weta_mirror">weta_mirror</a>. Full detais of the alignment options can be found in the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme">"theme" key description</a>.</p> + +<h3 id="Static_animated_themes">Static animated themes</h3> + +<p>It is possible to create an animated theme using an APNG format image, as in the <a href="https://github.com/mdn/webextensions-examples/tree/master/themes">themes</a> example <a href="https://github.com/mdn/webextensions-examples/tree/master/themes/animated">animated</a>. However, remember that rapid animations, such as the one in the example might be too distracting for a practical theme.</p> + +<p dir="ltr">You can also animate themes programmatically, which we discuss in <a href="#Dynamic_themes">Dynamic themes</a>.</p> + +<h2 id="Temas_dinâmicos">Temas dinâmicos</h2> + +<p>As an alternative to defining a static theme, you can use the {{WebExtAPIRef("theme")}} API to control the theme used in Firefox from within a browser extension. There are a couple of use cases for this option:</p> + +<ul> + <li>To bundle a theme with a browser extension, as an added extra.</li> + <li>Create a dynamic theme that changes under programmatic control.</li> +</ul> + +<p>And, obviously, you can combine the two and bundle a programmatically controlled theme with your extension.</p> + +<p>Using the {{WebExtAPIRef("theme")}} API is straightforward. First, request "theme"<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions"> permission</a> in the extension's<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json"> manifest.json</a> file. Next, you build a JSON object containing the same information you would use in a static theme’s manifest.json, Finally, pass the JSON object in a {{WebExtAPIRef("theme.update()")}} call.</p> + +<p>For example, the following code, from the <a href="https://github.com/mdn/webextensions-examples/tree/master/dynamic-theme">dynamic theme example</a> defines the content for the day and night elements of the dynamic theme:</p> + +<pre class="brush: js" dir="ltr">const themes = { + 'day': { + images: { + headerURL: 'sun.jpg', + }, + colors: { + accentcolor: '#CF723F', + textcolor: '#111', + } + }, + 'night': { + images: { + headerURL: 'moon.jpg', + }, + colors: { + accentcolor: '#000', + textcolor: '#fff', + } + } +};</pre> + +<p>The theme.Theme object is then passed to {{WebExtAPIRef("theme.update()")}} to change the header theme, as in this code snippet from the same example:</p> + +<pre class="brush: js" dir="ltr">function setTheme(theme) { + if (currentTheme === theme) { + // No point in changing the theme if it has already been set. + return; + } + currentTheme = theme; + browser.theme.update(themes[theme]); +}</pre> + +<p dir="ltr">Learn more about dynamic themes and see an additional example in the following video:</p> + +<p dir="ltr">{{EmbedYouTube("ycckyrUN0AY")}}</p> + +<p dir="ltr"> </p> + +<p dir="ltr">If you have not built a browser extension before, check out <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension">Your first extension</a> for a step-by-step guide.</p> + +<h2 id="Compatibilidade_entre_navegadores">Compatibilidade entre navegadores</h2> + +<p>There is currently limited compatibility between themes in the major browsers. Opera takes an entirely different approach, and Microsoft Edge themes are not yet open to developers.</p> + +<p>There is some compatibility between Firefox static themes and Chrome themes, providing the ability to port a single header image theme from Firefox to Chrome. This would be done by amending the manifest.json keys as follows:</p> + +<ul> + <li><code>"headerURL":</code> to <code>"theme_frame":</code></li> + <li><code>"accentcolor":</code> to <code>"frame":</code></li> + <li><code>"textcolor":</code> to <code>"tab_text":</code></li> +</ul> + +<p>Noting that "frame": and "tab_text": support RGB color definition only.</p> + +<p>So, in the single image theme example (weta_fade) could be supported in Chrome using the following manifest.json file:</p> + +<pre class="brush: json" dir="ltr">{ + "manifest_version": 2, + "version": "1.0", + "name": "<your_theme_name>", + "theme": { + "images": { + "theme_frame": "weta.png" + }, + "colors": { + "frame": [ 173 , 176 , 159 ], + "tab_text": [ 0 , 0 , 0 ] + } + } +}</pre> + +<p>However, there will be a couple of differences:</p> + +<ul> + <li>Chrome tiles the <code>“theme_frame”:</code> image from the left of the header area.</li> + <li><code>"tab_text":</code> only affects the text on the highlighted/active tab.</li> +</ul> + +<p dir="ltr"><img alt="The basic theme example using the Chrome compatible manifest.json keys, showing the differences in how those keys are implemented." src="https://mdn.mozillademos.org/files/15227/basic_in_chrome.png" style="height: 113px; width: 679px;"></p> + +<p>For more information, see the notes on <a href="/en-US/Add-ons/WebExtensions/manifest.json/theme#Chrome_compatibility">Chrome compatibility</a>.</p> diff --git a/files/pt-pt/mozilla/add-ons/themes/index.html b/files/pt-pt/mozilla/add-ons/themes/index.html new file mode 100644 index 0000000000..26dfb24673 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/themes/index.html @@ -0,0 +1,49 @@ +--- +title: Temas +slug: Mozilla/Add-ons/Themes +tags: + - Apresentação e Disposição + - Extras + - Temas +translation_of: Mozilla/Add-ons/Themes +--- +<p>{{AddonSidebar}}</p> + +<p>Temas permite-lhe alterar a apresentação e disposição da interface do utilizador e personalizar a seu gosto. Saiba como criar e partilhar os temas!</p> + +<div class="column-container"> +<div class="column-half"> +<h2 class="Documentation" id="Documentation" name="Documentation">Temas de Navegador</h2> + +<dl> + <dt><a href="/en-US/docs/Mozilla/Add-ons/Themes/Theme_concepts">Browser theme concepts</a></dt> + <dd>Get an introduction to creating themes for the latest versions of Firefox</dd> +</dl> + +<h2 class="Documentation" id="Documentation" name="Documentation">Temas Simples</h2> + +<dl> + <dt><a href="/en-US/docs/Themes/Lightweight_themes" title="Themes/Lightweight themes">Lightweight themes</a></dt> + <dd>Building lightweight themes for Firefox</dd> + <dt><a href="/en-US/Add-ons/Themes/Lightweight_Themes/FAQ">Lightweight themes FAQ</a></dt> + <dd>Get answers to commonly asked questions</dd> +</dl> +</div> + +<div class="column-half"> +<h2 id="Ferramentas_e_Recursos">Ferramentas e Recursos</h2> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme">Browser theme manifest.json keys</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/theme">Browser extensions theme API</a></li> + <li><a href="http://vanillaorchidstutorials.blogspot.com/2015/11/mozilla-themes-focal-point-sizing.html">Lightweight themes tutorial</a></li> + <li><a href="https://discourse.mozilla.org/c/add-ons/themes">Discourse forum</a></li> + <li><a href="https://blog.mozilla.org/addons/category/personas/">Theme related blog posts</a></li> + <li><a href="/en-US/Mozilla/Add-ons/Themes/Obsolete">Archived resources</a></li> +</ul> +</div> +</div> + +<p> </p> + +<p> </p> diff --git a/files/pt-pt/mozilla/add-ons/themes/obsolete/creating_a_skin_for_firefox/index.html b/files/pt-pt/mozilla/add-ons/themes/obsolete/creating_a_skin_for_firefox/index.html new file mode 100644 index 0000000000..9d187b7315 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/themes/obsolete/creating_a_skin_for_firefox/index.html @@ -0,0 +1,33 @@ +--- +title: Creating a Skin for Firefox +slug: Mozilla/Add-ons/Themes/Obsolete/Creating_a_Skin_for_Firefox +tags: + - Add-ons + - NeedsTranslation + - Themes + - TopicStub +translation_of: Archive/Themes/Creating_a_Skin_for_Firefox +--- +<h2 id="Introduction" name="Introduction">Introduction</h2> + +<p>In order to create a skin for Firefox, there are three things you need to know: how to edit images, how to extract zip files, and how to modify CSS. Firefox uses standard GIF, PNG, and JPEG images for the buttons and CSS to style everything else in the interface.</p> + +<h3 id="What_is_a_skin" name="What_is_a_skin">What is a skin?</h3> + +<p>A skin does not totally change the interface; instead, it just defines how the interface looks. You can't change what happens when the user right clicks on an image, but you can change the look of the right click menu (Make it blue with pink polka dots, for example). If you want to change the functionality of Firefox, you'll have to look into modifying the chrome, which is beyond the scope of this document.</p> + +<h2 id="Contents" name="Contents">Contents</h2> + +<ul> + <li><a href="/en-US/docs/Creating_a_Skin_for_Firefox_Getting_Started">Getting Started</a></li> +</ul> + +<div class="originaldocinfo"> +<h2 id="Original_Document_Information" name="Original_Document_Information">Informações Sobre o Documento Original</h2> +<ul> +<li>Autor(es): Neil Marshall and Tucker Lee</li> +<li>Outros Contribuidores: Brent Marshall, CDN (http://themes.mozdev.org), JP Martin, Boris Zbarsky, Asa Dotzler, WeSaySo, David James, Dan Mauch, Anders Conbere, Tim Regula (http://www.igraphics.nn.cx)</li> +<li>Informações sobre Copyright: Copyright 2002-2003 Neil Marshall, permission given to MDC to migrate into the wiki April 2005 via email.</li> +<li>Original Location: <a class="external" href="http://www.eightlines.com/neil/mozskin" rel="noopener">http://www.eightlines.com/neil/mozskin</a></li> +</ul> +</div> diff --git a/files/pt-pt/mozilla/add-ons/themes/obsolete/index.html b/files/pt-pt/mozilla/add-ons/themes/obsolete/index.html new file mode 100644 index 0000000000..d420b6ebf0 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/themes/obsolete/index.html @@ -0,0 +1,10 @@ +--- +title: Obsolete +slug: Mozilla/Add-ons/Themes/Obsolete +tags: + - NeedsTranslation + - TopicStub +translation_of: Mozilla/Add-ons/Themes/Obsolete +--- +<p>This page collects theme docs that we don't expect will ever be updated, but which we're keeping for the time being as potential source material for updated docs.</p> +<p>{{ ListSubPages ("/en-US/Add-ons/Themes/Obsolete", 5) }}</p> diff --git a/files/pt-pt/mozilla/add-ons/thunderbird/index.html b/files/pt-pt/mozilla/add-ons/thunderbird/index.html new file mode 100644 index 0000000000..b15b535a59 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/thunderbird/index.html @@ -0,0 +1,135 @@ +--- +title: Thunderbird extensions +slug: Mozilla/Add-ons/Thunderbird +tags: + - Add-ons + - Extensions + - NeedsTranslation + - TopicStub + - thunderbird +translation_of: Mozilla/Thunderbird/Thunderbird_extensions +--- +<div class="callout-box"><strong><a href="/en/Extensions/Thunderbird/Building_a_Thunderbird_extension" title="en/Building_a_Thunderbird_extension">Building a Thunderbird extension</a></strong><br> +Step-by-step explanation on how to build an extension for Thunderbird.</div> + +<div> +<p>{{AddonSidebar}}</p> +The following documentation provides help for creating extensions for Mozilla's <a class="internal" href="/en/Thunderbird" title="En/Thunderbird">Thunderbird</a> email client. Although there are many similarities with <a href="/en/Extensions" title="en/Extensions">Firefox extensions</a> there are also some differences that may confound the starting developer.</div> + +<div><br> +<strong>Please help!</strong> You can <a class="internal" href="/en/Extensions/Thunderbird/HowTos" title="en/Extensions/Thunderbird/HowTos">add a how-to</a> (a question or an answer or a code snippet), <a class="internal" href="/en/Extensions/Thunderbird/Useful_newsgroups_discussions" title="En/Extensions/Thunderbird/Useful newsgroups discussions">summarize and link to a relevant newsgroup discussion</a>, or create a tutorial. Need help? Contact <a class="internal" href="/User:jenzed" title="User:jenzed">jenzed</a>.</div> + +<table class="topicpage-table"> + <tbody> + <tr> + <td> + <h2 id="Documentation" name="Documentation"><a href="/Special:Tags?tag=Extensions&language=en" title="Special:Tags?tag=Extensions&language=en">Documentation</a></h2> + + <h3 id="Getting_started_with_Thunderbird">Getting started with Thunderbird</h3> + + <p>A brave, young developer wants to develop an add-on for Thunderbird. Here's a few links to help them through this journey.</p> + + <ul> + <li>Start by reading the tutorial and learn how to<a class="internal" href="/en/Extensions/Thunderbird/Building_a_Thunderbird_extension" title="En/Building a Thunderbird extension"> build a Thunderbird extension</a> (Outdated, still talks about overlays and the add-on builder is no longer available but the tutorial has not been updated.)</li> + <li>Read about the <a href="/en/Thunderbird/Main_Windows" title="Main Windows">main windows</a> so that you know what one means when they say « thread pane », « preview pane », and « folder pane ».</li> + + <li>Want to do some real stuff? See <a class="external" href="http://blog.xulforum.org/index.php?post/2011/03/14/Basic-MimeMessage-demo" title="http://blog.xulforum.org/index.php?post/2011/03/14/Basic-MimeMessage-demo">how to inspect a message</a> (demo add-on included!)</li> + <li>Play with our other <a href="/en/Extensions/Thunderbird/Demo_Addon" title="Demo Addon">demo add-on</a> that exercises some more advanced Thunderbird-specific features</li> + <li>Want to do even more stuff? Don't reinvent the wheel: steal functions from the <a class="link-https" href="https://github.com/protz/thunderbird-stdlib" title="https://github.com/protz/thunderbird-stdlib">thunderbird-stdlib</a> project (doc <a class="external" href="http://protz.github.com/thunderbird-stdlib/doc/symbols/_global_.html" title="http://protz.github.com/thunderbird-stdlib/doc/symbols/_global_.html">here</a>). Functions for dealing with messages (delete them, archive them, change their tags, etc.) are included.</li> + <li>Haven't found what you're looking for? Read the <a class="internal" href="/en/Extensions/Thunderbird/HowTos" rel="internal" title="en/Extensions/Thunderbird/HowTos">Thunderbird how-tos</a>; they contain a lot of recipes for things extensions want to do.</li> + <li>Still haven't managed to do what you wanted? See the list of all <a class="external" href="http://wiki.mozilla.org/Thunderbird/CommunicationChannels" title="http://wiki.mozilla.org/Thunderbird/CommunicationChannels">Thunderbird communication channels </a>so that you know where to ask when you get stuck :-).</li> + <li>Feeling really brave? Read the source using a <a class="external" href="http://doxygen.db48x.net/comm-central/html/" title="http://doxygen.db48x.net/comm-central/html/">fancy interface</a>; you can often find tests that demonstrate how to do what you're trying to achieve.</li> + </ul> + + <h3 id="The_Gloda_database">The Gloda database</h3> + + <p>Thunderbird has a subsystem called Gloda. Gloda stands for « Global Database », and creates Thunderbird-wide relations between objects. Gloda provides concepts such as Conversations, Messages, Identities, Contacts. All these concepts are related together: a Conversation contains Messages which are linked to Identities (<strong>from</strong> field, <strong>to</strong> field) which are themselves part of a Contact: indeed, a contact has multiple identities.</p> + + <p>Typical use cases for Gloda: find all messages whose subject matches [search term], find all messages from [person], find all messages in the same thread as [a given message], find all messages involving [person], etc. etc.</p> + + <p>Gloda is extremely powerful and is used heavily by add-ons such as <a class="link-https" href="https://addons.mozilla.org/en-US/thunderbird/addon/gmail-conversation-view/" title="https://addons.mozilla.org/en-US/thunderbird/addon/gmail-conversation-view/">Thunderbird Conversations</a>. Learn more about Gloda:</p> + + <ul> + <li>an overview of <a href="/en/Thunderbird/gloda" title="Gloda">Gloda</a></li> + <li>learn how to create <a href="/en/Thunderbird/Creating_a_Gloda_message_query" title="Creating a gloda message query">your first message query</a> and read the <a href="/en/Thunderbird/Gloda_examples" title="Gloda examples">gloda examples</a></li> + <li>learn about the Gloda internals: <a href="/en/Thunderbird/Gloda_debugging" title="Gloda debugging">Gloda debugging</a>, <a href="/en/Thunderbird/Gloda_indexing" title="Gloda indexing">Gloda indexing</a></li> + </ul> + + <h3 id="More_Thunderbird-specific_links">More Thunderbird-specific links</h3> + + <p>Some of these links may be wildly out of date, but they still provide valuable information on the codebase.</p> + + <ul> + <li><a class="internal" href="/en/Extensions/Thunderbird/An_overview_of_the_Thunderbird_interface" title="En/Extensions/Thunderbird/An overview of the Thunderbird interface">An overview of Thunderbird components</a></li> + <li><a class="internal" href="/en/Extensions/Thunderbird/Thunderbird_developer_reference_docs" title="en/Extensions/Thunderbird/Thunderbird developer reference docs">Developer reference docs</a>: + <ul> + <li><a class="internal" href="/en/Folders" title="En/Folders">Folder classes</a></li> + <li><a class="internal" href="/en/DB_Views_(message_lists)" title="En/DB Views (message lists)">DB views (message list)</a></li> + <li><a class="internal" href="/en/Message_Summary_Database" title="En/Message Summary Database">Message summary database</a></li> + <li><a class="internal" href="/en/MailNews_Protocols" title="En/MailNews Protocols">MailNews protocols</a></li> + <li><a class="internal" href="/En/MailNews_Filters" rel="internal" title="En/MailNews Filters">MailNews filters</a></li> + <li><a class="internal" href="/en/Extensions/Thunderbird/Error_reporting_tools" title="en/Extension Library/Extensions/Thunderbird/Error reporting tools">Error reporting tools</a></li> + <li><a href="/en/Toolkit_API/STEEL" title="en/Toolkit API/STEEL">STEEL library</a> (obsolete as of Thunderbird 52, use <a class="link-https" href="https://github.com/protz/thunderbird-stdlib" title="https://github.com/protz/thunderbird-stdlib">https://github.com/protz/thunderbird-stdlib</a>)</li> + <li><a class="external" href="http://quetzalcoatal.blogspot.com/2010/01/developing-new-account-types-part-0.html" title="http://quetzalcoatal.blogspot.com/2010/01/developing-new-account-types-part-0.html">Developing new account types</a> <strong>NEW!</strong></li> + </ul> + </li> + <li><a class="internal" href="/en/Extensions/Thunderbird/Useful_newsgroups_discussions" title="En/Extensions/Thunderbird/Useful newsgroups discussions">Useful newsgroup discussions</a> (watch out, anything that's too old should be regarded suspiciously; there's been significant API rewrite over the past years, and most of these techniques are considerably easier now) </li> + <li><a href="/en/Thunderbird/Thunderbird_API_documentation" title="en/Thunderbird/Thunderbird API documentation">Thunderbird API docs</a> (mostly a collection of out-of-date pages, relevance is rather dubious) </li> + <li><a href="/en/Mozilla/Thunderbird/Releases" title="Thunderbird developer release notes">Thunderbird developer release notes</a> - changes in the recent Thunderbird updates affecting add-on developers. <a href="/Thunderbird_5_for_developers" title="Thunderbird 5 for developers">Thunderbird 5 for developers</a> has important information on MsgHdrToMimeMessage which is a central piece of code.</li> + </ul> + + <h3 id="General_links">General links</h3> + + <ul> + <li><a href="/en/Extensions/Thunderbird/Finding_the_code_for_a_feature" title="en/Extensions/Thunderbird/Finding the code for a feature">Finding the code for a feature</a></li> + <li><a class="external" href="http://kb.mozillazine.org/Category:Thunderbird" title="http://kb.mozillazine.org/Category:Thunderbird">Mozillazine articles on Thunderbird</a></li> + <li><a href="/Special:Tags?tag=Thunderbird" title="https://developer.mozilla.org/Special:Tags?tag=Thunderbird">All pages tagged with Thunderbird</a></li> + <li><a href="/Special:Tags?tag=MailNews" title="https://developer.mozilla.org/Special:Tags?tag=MailNews">All pages tagged with MailNews</a></li> + </ul> + </td> + <td> + <h2 id="Community" name="Community">Community</h2> + + <ul> + <li>See the list of all <a class="external" href="http://wiki.mozilla.org/Thunderbird/CommunicationChannels" title="http://wiki.mozilla.org/Thunderbird/CommunicationChannels">Thunderbird communication channels </a>first</li> + <li>Among these are:</li> + </ul> + + <p>{{ DiscussionList("dev-extensions", "mozilla.dev.extensions") }}</p> + + <ul> + <li><a class="link-irc" href="irc://moznet/#extdev">#extdev IRC channel</a> / <a class="link-irc" href="irc://moznet/#maildev">#maildev IRC channel</a></li> + <li><a class="external" href="http://forums.mozillazine.org/viewforum.php?f=19">MozillaZine forum</a></li> + <li><a class="external" href="http://mozdev.org/mailman/listinfo/project_owners">mozdev project owners</a></li> + <li><a href="/en/Extensions/Community" title="en/Extensions/Community">Other community links...</a></li> + </ul> + + <h2 id="Tools" name="Tools">Tools</h2> + + <ul> + <li><a class="link-https" href="https://addons.mozilla.org/en-US/firefox/addon/6622" rel="external nofollow" title="https://addons.mozilla.org/en-US/firefox/addon/6622">DOM Inspector</a> edit the live DOM (Firefox and Thunderbird)</li> + <li><a class="link-https" href="https://addons.mozilla.org/thunderbird/addon/workspace-for-thunderbird/" title="https://addons.mozilla.org/thunderbird/addon/workspace-for-thunderbird/">Workspace for Thunderbird</a>, allows running code snippets in Thunderbird and inspecting variable structure and content</li> + <li><a class="external" href="http://www.hacksrus.com/~ginda/venkman/" rel="external nofollow" title="http://www.hacksrus.com/~ginda/venkman/">Venkman</a>, a JavaScript debugger (<a class="external" href="http://addons.mozilla.org/en-US/firefox/addon/216" rel="external nofollow" title="http://addons.mozilla.org/en-US/firefox/addon/216">Firefox</a>, <a class="external" href="http://addons.mozilla.org/en-US/thunderbird/addon/216" rel="external nofollow" title="http://addons.mozilla.org/en-US/thunderbird/addon/216">Thunderbird</a>)</li> + <li><a class="link-https" href="https://addons.mozilla.org/en-US/firefox/addon/7434/" rel="external nofollow" title="https://addons.mozilla.org/en-US/firefox/addon/7434/">Extension Developer's Extension</a> a suite of development tools</li> + <li><a class="external" href="http://www.gijsk.com/" rel="external nofollow" title="http://www.gijsk.com/">Chrome List</a> view files in chrome:// (<a class="external" href="http://addons.mozilla.org/en-US/firefox/addon/4453" rel="external nofollow" title="http://addons.mozilla.org/en-US/firefox/addon/4453">Firefox</a>, <a class="external" href="http://addons.mozilla.org/en-US/thunderbird/addon/4453" rel="external nofollow" title="http://addons.mozilla.org/en-US/thunderbird/addon/4453">Thunderbird</a>)</li> + <li><a href="/en/Mozmill" title="en/Mozmill">Mozmill</a> test tool and framework</li> + <li><a class="external" href="http://xpcomviewer.mozdev.org/" rel="external nofollow" title="http://xpcomviewer.mozdev.org">XPCOMViewer</a> an XPCOM inspector (Firefox and Thunderbird)</li> + </ul> + + <p>... <a class="internal" href="/en/Setting_up_extension_development_environment#Development_extensions" title="en/Setting up extension development environment#Development extensions">more tools</a> ...</p> + + <p><span class="alllinks"><a href="/Special:Tags?tag=Extensions:Tools&language=en" title="Special:Tags?tag=Extensions:Tools&language=en">View All...</a></span></p> + + <h2 id="Related_Topics" name="Related_Topics">Related Topics</h2> + + <dl> + <dd><a href="/en/XUL" title="en/XUL">XUL</a>, <a href="/en/JavaScript" title="en/JavaScript">JavaScript</a>, <a href="/en/XPCOM" title="en/XPCOM">XPCOM</a>, <a href="/en/Themes" title="en/Themes">Themes</a>, <a href="/En/Developer_Guide" title="en/Developing_Mozilla">Developing Mozilla</a></dd> + </dl> + </td> + </tr> + </tbody> +</table> + +<p><span class="comment">Categories</span></p> + +<p>{{ languages( { "ja": "ja/Extensions/Thunderbird" } ) }}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/a_sua_primeira_extensao/index.html b/files/pt-pt/mozilla/add-ons/webextensions/a_sua_primeira_extensao/index.html new file mode 100644 index 0000000000..21b34f2e2c --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/a_sua_primeira_extensao/index.html @@ -0,0 +1,153 @@ +--- +title: A sua primeira extensão +slug: Mozilla/Add-ons/WebExtensions/A_sua_primeira_extensao +tags: + - Extensões da Web + - Guía +translation_of: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>Neste artigo, nós iremos abordar a criação de uma extensão para o Firefox, do início até ao fim. A extensão adiciona apenas um contorno vermelho a qualquer página carregada de 'mozilla.org' ou qualquer um dos seus subdomínios.</p> + +<p>O código fonte para este exemplo está no GitHub: <em><a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">borderify</a></em>.</p> + +<p>Primeiro, precisa de ter o Firefox - versão 45 ou superior.</p> + +<h2 id="Escrever_a_extensão">Escrever a extensão</h2> + +<p>Crie uma nova diretoria e vá para a mesma:</p> + +<pre class="brush: bash">mkdir borderify +cd borderify</pre> + +<h3 id="manifest.json">manifest.json</h3> + +<p>Now create a new file called "manifest.json" directly under the "borderify" directory. Give it the following contents:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Borderify", + "version": "1.0", + + "description": "Adds a red border to all webpages matching mozilla.org.", + + "icons": { + "48": "icons/border-48.png" + }, + + "content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } + ] + +}</pre> + +<ul> + <li>The first three keys: <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code>, <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/name">name</a></code>, and <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/version">version</a></code>, are mandatory and contain basic metadata for the extension.</li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/description">description</a></code> is optional, but recommended: it's displayed in the Add-ons Manager.</li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> is optional, but recommended: it allows you to specify an icon for the extension, that will be shown in the Add-ons Manager.</li> +</ul> + +<p>The most interesting key here is <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code>, which tells Firefox to load a script into Web pages whose URL matches a specific pattern. In this case, we're asking Firefox to load a script called "borderify.js" into all HTTP or HTTPS pages served from "mozilla.org" or any of its subdomains.</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/Content_scripts">Learn more about content scripts.</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Match_patterns">Learn more about match patterns</a>.</li> +</ul> + +<div class="warning"> +<p><a href="/en-US/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID#When_do_you_need_an_Add-on_ID">In some situations you need to specify an ID for your extension</a>. If you do need to specify an add-on ID, include the <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> key in <code>manifest.json</code> and set its <code>gecko.id</code> property:</p> + +<pre class="brush: json">"applications": { + "gecko": { + "id": "borderify@example.com" + } +}</pre> +</div> + +<h3 id="iconsborder-48.png">icons/border-48.png</h3> + +<p>The extension should have an icon. This will be shown next to the extension's listing in the Add-ons Manager. Our manifest.json promised that we would have an icon at "icons/border-48.png".</p> + +<p>Create the "icons" directory directly under the "borderify" directory. Save an icon there named "border-48.png". You could use <a href="https://github.com/mdn/webextensions-examples/blob/master/borderify/icons/border-48.png">the one from our example</a>, which is taken from the Google Material Design iconset, and is used under the terms of the <a href="https://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike</a> license.</p> + +<p>If you choose to supply your own icon, It should be 48x48 pixels. You could also supply a 96x96 pixel icon, for high-resolution displays, and if you do this it will be specified as the <code>96</code> property of the <code>icons</code> object in manifest.json:</p> + +<pre class="brush: json">"icons": { + "48": "icons/border-48.png", + "96": "icons/border-96.png" +}</pre> + +<p>Alternatively, you could supply an SVG file here, and it will be scaled correctly. (Though: if you're using SVG and your icon includes text, you may want to use your SVG editor's "convert to path" tool to flatten the text, so that it scales with a consistent size/position.)</p> + +<ul> + <li><a href="/pt-PT/Add-ons/WebExtensions/manifest.json/icones">Saiba mais sobre a especificação de ícones (icons).</a></li> +</ul> + +<h3 id="borderify.js">borderify.js</h3> + +<p>Finally, create a file called "borderify.js" directly under the "borderify" directory. Give it this content:</p> + +<pre class="brush: js">document.body.style.border = "5px solid red";</pre> + +<p>This script will be loaded into the pages that match the pattern given in the <code>content_scripts</code> manifest.json key. The script has direct access to the document, just like scripts loaded by the page itself.</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/Content_scripts">Learn more about content scripts.</a></li> +</ul> + +<h2 id="Testá-la">Testá-la</h2> + +<p>Primeiro, reverifique que tem os ficheiros corretos nos locais certos:</p> + +<pre>borderify/ + icons/ + border-48.png + borderify.js + manifest.json</pre> + +<h3 id="Instalar">Instalar</h3> + +<p>Open "about:debugging" in Firefox, click "Load Temporary Add-on" and select any file in your extension's directory:</p> + +<p>{{EmbedYouTube("cer9EUKegG4")}}</p> + +<p>The extension will now be installed, and will stay until you restart Firefox.</p> + +<p>Alternatively, you can run the extension from the command line using the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> tool.</p> + +<h3 id="Testar">Testar</h3> + +<p>Now try visiting a page under "mozilla.org", and you should see the red border round the page:</p> + +<p>{{EmbedYouTube("rxBQl2Z9IBQ")}}</p> + +<div class="note"> +<p>Don't try it on addons.mozilla.org, though! Content scripts are currently blocked on that domain.</p> +</div> + +<p>Try experimenting a bit. Edit the content script to change the color of the border, or do something else to the page content. Save the content script, then reload the extensions's files by clicking the "Reload" button in about:debugging. You can see the changes right away:</p> + +<p>{{EmbedYouTube("NuajE60jfGY")}}</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">Learn more about loading extensions</a></li> +</ul> + +<h2 id="Empacotar_e_publicação">Empacotar e publicação</h2> + +<p>Para que as outras pessoas utilizem a sua extensão, precisa de empacotá-la e enviá-la para a assinar na Mozilla. Para saber mais sobre isto, consulte <a href="/pt-PT/Add-ons/WebExtensions/Publicar_a_sua_extensao">"Publicar a sua extensão"</a>.</p> + +<h2 id="E_a_seguir">E a seguir?</h2> + +<p>Agora tem uma idéia do processo de desenvolvimento de uma <strong>Extensão da Web</strong> para o Firefox, tente:</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">reading more about the anatomy of an extension</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Your_second_WebExtension">writing a more complex extension</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/API">reading about the JavaScript APIs available for extensions.</a></li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/a_sua_segunda_extensao/index.html b/files/pt-pt/mozilla/add-ons/webextensions/a_sua_segunda_extensao/index.html new file mode 100644 index 0000000000..503f2b4ae9 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/a_sua_segunda_extensao/index.html @@ -0,0 +1,460 @@ +--- +title: A sua segunda extensão +slug: Mozilla/Add-ons/WebExtensions/A_sua_segunda_extensao +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension +--- +<div>{{AddonSidebar}} +<p>Se já leu o artigo da <a href="/pt-PT/Add-ons/WebExtensions/A_sua_primeira_extensao">A sua primeira extens</a>ão, já tem uma ideia de como escrever uma extensão. Neste artigo, nós iremos escrever uma extensão um pouco mais complexa que demonstra algumas mais das APIs. <br> + <br> + A extensão adiciona um novo botão à barra de ferramentas do Firefox. Quando o utilizador clica no botão, nós exibimos uma janela que lhes permite escolher um animal. Uma vez que eles escolhem um animal, nós iremos substituir o conteúdo da página atual com uma fotografia do animal escolhido. <br> + <br> + Para implementar isto, nós iremos:.</p> + +<p>To implement this, we will:</p> + +<ul> + <li><strong>define a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_action">browser action</a>, which is a button attached to the Firefox toolbar</strong>.<br> + For the button we'll supply: + <ul> + <li>an icon, called "beasts-32.png"</li> + <li>a popup to open when the button is pressed. The popup will include HTML, CSS, and JavaScript.</li> + </ul> + </li> + <li><strong>define an icon for the extension</strong>, called "beasts-48.png". This will be shown in the Add-ons Manager.</li> + <li><strong>write a content script, "beastify.js" that will be injected into web pages</strong>.<br> + This is the code that will actually modify the pages.</li> + <li><strong>package some images of the animals, to replace images in the web page</strong>.<br> + We'll make the images "web accessible resources" so the web page can refer to them.</li> +</ul> + +<p>You could visualise the overall structure of the extension like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13671/Untitled-1.png" style="display: block; height: 1200px; margin-left: auto; margin-right: auto; width: 860px;"></p> + +<p>It's a simple extension, but shows many of the basic concepts of the WebExtensions API:</p> + +<ul> + <li>adding a button to the toolbar</li> + <li>defining a popup panel using HTML, CSS, and JavaScript</li> + <li>injecting content scripts into web pages</li> + <li>communicating between content scripts and the rest of the extension</li> + <li>packaging resources with your extension that can be used by web pages</li> +</ul> + +<p>You can find <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">complete source code for the extension on GitHub</a>.</p> + +<p>To write this extension, you'll need Firefox 45 or newer.</p> + +<h2 id="Escrever_a_extensão">Escrever a extensão</h2> + +<p>Create a new directory and navigate to it:</p> + +<pre class="brush: bash">mkdir beastify +cd beastify</pre> + +<h3 id="manifest.json">manifest.json</h3> + +<p>Now create a new file called "manifest.json", and give it the following contents:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Beastify", + "version": "1.0", + + "description": "Adds a browser action icon to the toolbar. Click the button to choose a beast. The active tab's body content is then replaced with a picture of the chosen beast. See https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Examples#beastify", + "homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/beastify", + "icons": { + "48": "icons/beasts-48.png" + }, + + "permissions": [ + "activeTab" + ], + + "browser_action": { + "default_icon": "icons/beasts-32.png", + "default_title": "Beastify", + "default_popup": "popup/choose_beast.html" + }, + + "web_accessible_resources": [ + "beasts/frog.jpg", + "beasts/turtle.jpg", + "beasts/snake.jpg" + ] + +} +</pre> + +<ul> + <li>The first three keys: <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name">name</a></code>, and <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version">version</a></code>, are mandatory and contain basic metadata for the extension.</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/description">description</a></code> and <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url">homepage_url</a></code> are optional, but recommended: they provide useful information about the extension.</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> is optional, but recommended: it allows you to specify an icon for the extension, that will be shown in the Add-ons Manager.</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> lists permissions the extension needs. We're just asking for the <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission"><code>activeTab</code> permission</a> here.</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> specifies the toolbar button. We're supplying three pieces of information here: + <ul> + <li><code>default_icon</code> is mandatory, and points to the icon for the button</li> + <li><code>default_title</code> is optional, and will be shown in a tooltip</li> + <li><code>default_popup</code> is used if you want a popup to be shown when the user clicks the button. We do, so we've included this key and made it point to an HTML file included with the extension.</li> + </ul> + </li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code> lists files that we want to make accessible to web pages. Since the extension replaces the content in the page with images we've packaged with the extension, we need to make these images accessible to the page.</li> +</ul> + +<p>Note that all paths given are relative to manifest.json itself.</p> + +<h3 id="O_ícone">O ícone</h3> + +<p>The extension should have an icon. This will be shown next to the extension's listing in the Add-ons Manager (you can open this by visiting the URL "about:addons"). Our manifest.json promised that we would have an icon for the toolbar at "icons/beasts-48.png".</p> + +<p>Create the "icons" directory and save an icon there named "beasts-48.png". You could use <a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-48.png">the one from our example</a>, which is taken from the <a href="https://www.iconfinder.com/iconsets/free-retina-icon-set">Aha-Soft’s Free Retina iconset</a>, and used under the terms of its <a href="http://www.aha-soft.com/free-icons/free-retina-icon-set/">license</a>.</p> + +<p>If you choose to supply your own icon, It should be 48x48 pixels. You could also supply a 96x96 pixel icon, for high-resolution displays, and if you do this it will be specified as the <code>96</code> property of the <code>icons</code> object in manifest.json:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"icons":</span> <span class="punctuation token">{</span> + <span class="key token">"48":</span> <span class="string token">"icons/beasts-48.png"</span><span class="punctuation token">,</span> + <span class="key token">"96":</span> <span class="string token">"icons/beasts-96.png"</span> +<span class="punctuation token">}</span></code></pre> + +<h3 id="O_botão_de_barra_de_ferramentas">O botão de barra de ferramentas</h3> + +<p>The toolbar button also needs an icon, and our manifest.json promised that we would have an icon for the toolbar at "icons/beasts-32.png".</p> + +<p>Save an icon named "beasts-32.png" in the "icons" directory. You could use <a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-32.png">the one from our example</a>, which is taken from the <a href="http://www.iconbeast.com/free">IconBeast Lite icon set</a> and used under the terms of its <a href="http://www.iconbeast.com/faq/">license</a>.</p> + +<p>If you don't supply a popup, then a click event is dispatched to your extension when the user clicks the button. If you do supply a popup, the click event is not dispatched, but instead, the popup is opened. We want a popup, so let's create that next.</p> + +<h3 id="A_janela_(popup)">A janela (popup)</h3> + +<p>The function of the popup is to enable the user to choose one of three beasts.</p> + +<p>Create a new directory called "popup" under the extension root. This is where we'll keep the code for the popup. The popup will consist of three files:</p> + +<ul> + <li><strong><code>choose_beast.html</code></strong> defines the content of the panel</li> + <li><strong><code>choose_beast.css</code></strong> styles the content</li> + <li><strong><code>choose_beast.js</code></strong> handles the user's choice by running a content script in the active tab</li> +</ul> + +<pre class="brush: bash">mkdir popup +cd popup +touch choose_beast.html choose_beast.css choose_beast.js +</pre> + +<h4 id="choose_beast.html">choose_beast.html</h4> + +<p>The HTML file looks like this:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + <link rel="stylesheet" href="choose_beast.css"/> + </head> + +<body> + <div id="popup-content"> + <div class="button beast">Frog</div> + <div class="button beast">Turtle</div> + <div class="button beast">Snake</div> + <div class="button reset">Reset</div> + </div> + <div id="error-content" class="hidden"> + <p>Can't beastify this web page.</p><p>Try a different page.</p> + </div> + <script src="choose_beast.js"></script> +</body> + +</html> +</pre> + +<p>We have a <code><a href="/en-US/docs/Web/HTML/Element/div"><div></a></code> element with an ID of <code>"popup-content"</code> that contains an element for each animal choice. We have another <code><div></code> with an ID of <code>"error-content"</code> and a class <code>"hidden"</code>. We'll use that in case there's a problem initializing the popup.</p> + +<p>Note that we include the CSS and JS files from this file, just like a web page.</p> + +<h4 id="choose_beast.css">choose_beast.css</h4> + +<p>The CSS fixes the size of the popup, ensures that the three choices fill the space, and gives them some basic styling. It also hides elements with <code>class="hidden"</code>: this means that our <code>"error-content"</code> <code><div></code> will be hidden by default.</p> + +<pre class="brush: css">html, body { + width: 100px; +} + +.hidden { + display: none; +} + +.button { + margin: 3% auto; + padding: 4px; + text-align: center; + font-size: 1.5em; + cursor: pointer; +} + +.beast:hover { + background-color: #CFF2F2; +} + +.beast { + background-color: #E5F2F2; +} + +.reset { + background-color: #FBFBC9; +} + +.reset:hover { + background-color: #EAEA9D; +} + +</pre> + +<h4 id="choose_beast.js">choose_beast.js</h4> + +<p>Here's the JavaScript for the popup:</p> + +<pre class="brush: js">/** + * CSS to hide everything on the page, + * except for elements that have the "beastify-image" class. + */ +const hidePage = `body > :not(.beastify-image) { + display: none; + }`; + +/** + * Listen for clicks on the buttons, and send the appropriate message to + * the content script in the page. + */ +function listenForClicks() { + document.addEventListener("click", (e) => { + + /** + * Given the name of a beast, get the URL to the corresponding image. + */ + function beastNameToURL(beastName) { + switch (beastName) { + case "Frog": + return browser.extension.getURL("beasts/frog.jpg"); + case "Snake": + return browser.extension.getURL("beasts/snake.jpg"); + case "Turtle": + return browser.extension.getURL("beasts/turtle.jpg"); + } + } + + /** + * Insert the page-hiding CSS into the active tab, + * then get the beast URL and + * send a "beastify" message to the content script in the active tab. + */ + function beastify(tabs) { + browser.tabs.insertCSS({code: hidePage}).then(() => { + let url = beastNameToURL(e.target.textContent); + browser.tabs.sendMessage(tabs[0].id, { + command: "beastify", + beastURL: url + }); + }); + } + + /** + * Remove the page-hiding CSS from the active tab, + * send a "reset" message to the content script in the active tab. + */ + function reset(tabs) { + browser.tabs.removeCSS({code: hidePage}).then(() => { + browser.tabs.sendMessage(tabs[0].id, { + command: "reset", + }); + }); + } + + /** + * Just log the error to the console. + */ + function reportError(error) { + console.error(`Could not beastify: ${error}`); + } + + /** + * Get the active tab, + * then call "beastify()" or "reset()" as appropriate. + */ + if (e.target.classList.contains("beast")) { + browser.tabs.query({active: true, currentWindow: true}) + .then(beastify) + .catch(reportError); + } + else if (e.target.classList.contains("reset")) { + browser.tabs.query({active: true, currentWindow: true}) + .then(reset) + .catch(reportError); + } + }); +} + +/** + * There was an error executing the script. + * Display the popup's error message, and hide the normal UI. + */ +function reportExecuteScriptError(error) { + document.querySelector("#popup-content").classList.add("hidden"); + document.querySelector("#error-content").classList.remove("hidden"); + console.error(`Failed to execute beastify content script: ${error.message}`); +} + +/** + * When the popup loads, inject a content script into the active tab, + * and add a click handler. + * If we couldn't inject the script, handle the error. + */ +browser.tabs.executeScript({file: "/content_scripts/beastify.js"}) +.then(listenForClicks) +.catch(reportExecuteScriptError); + +</pre> + +<p>The place to start here is line 96. The popup script executes a content script in the active tab as soon as the popup is loaded, using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">browser.tabs.executeScript()</a></code> API. If executing the content script is successful, then the content script will stay loaded in the page until the tab is closed or the user navigates to a different page.</p> + +<p>A common reason the <code>browser.tabs.executeScript()</code> call might fail is that you can't execute content scripts in all pages. For example, you can't execute them in privileged browser pages like about:debugging, and you can't execute them on pages in the <a href="https://addons.mozilla.org/">addons.mozilla.org</a> domain. If it does fail, <code>reportExecuteScriptError()</code> will hide the <code>"popup-content"</code> <code><div></code>, show the <code>"error-content"</code> <code><div></code>, and log an error to the <a href="/en-US/Add-ons/WebExtensions/Debugging">console</a>.</p> + +<p>If executing the content script is successful, we call <code>listenForClicks()</code>. This listens for clicks on the popup.</p> + +<ul> + <li>If the click was on a button with <code>class="beast"</code>, then we call <code>beastify()</code>.</li> + <li>If the click was on a button with <code>class="reset"</code>, then we call <code>reset()</code>.</li> +</ul> + +<p>The <code>beastify()</code> function does three things:</p> + +<ul> + <li>map the button clicked to a URL pointing to an image of a particular beast</li> + <li>hide the page's whole content by injecting some CSS, using the <code><a href="/en-US/Add-ons/WebExtensions/API/tabs/insertCSS">browser.tabs.insertCSS()</a></code> API</li> + <li>send a "beastify" message to the content script using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">browser.tabs.sendMessage()</a></code> API, asking it to beastify the page, and passing it the URL to the beast image.</li> +</ul> + +<p>The <code>reset()</code> function essentially undoes a beastify:</p> + +<ul> + <li>remove the CSS we added, using the <code><a href="/en-US/Add-ons/WebExtensions/API/tabs/removeCSS">browser.tabs.removeCSS()</a></code> API</li> + <li>send a "reset" message to the content script asking it to reset the page.</li> +</ul> + +<h3 id="O_script_de_conteúdo">O <em>script</em> de conteúdo</h3> + +<p>Create a new directory, under the extension root, called "content_scripts" and create a new file in it called "beastify.js", with the following contents:</p> + +<pre class="brush: js">(function() { + /** + * Check and set a global guard variable. + * If this content script is injected into the same page again, + * it will do nothing next time. + */ + if (window.hasRun) { + return; + } + window.hasRun = true; + + /** + * Given a URL to a beast image, remove all existing beasts, then + * create and style an IMG node pointing to + * that image, then insert the node into the document. + */ + function insertBeast(beastURL) { + removeExistingBeasts(); + let beastImage = document.createElement("img"); + beastImage.setAttribute("src", beastURL); + beastImage.style.height = "100vh"; + beastImage.className = "beastify-image"; + document.body.appendChild(beastImage); + } + + /** + * Remove every beast from the page. + */ + function removeExistingBeasts() { + let existingBeasts = document.querySelectorAll(".beastify-image"); + for (let beast of existingBeasts) { + beast.remove(); + } + } + + /** + * Listen for messages from the background script. + * Call "beastify()" or "reset()". + */ + browser.runtime.onMessage.addListener((message) => { + if (message.command === "beastify") { + insertBeast(message.beastURL); + } else if (message.command === "reset") { + removeExistingBeasts(); + } + }); + +})(); +</pre> + +<p>The first thing the content script does is to check for a global variable <code>window.hasRun</code>: if it's set the script returns early, otherwise it sets <code>window.hasRun</code> and continues. The reason we do this is that every time the user opens the popup, the popup executes a content script in the active tab, so we could have multiple instances of the script running in a single tab. If this happens, we need to make sure that only the first instance is actually going to do anything.</p> + +<p>After that, the place to start is line 40, where the content script listens for messages from the popup, using the <code><a href="/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code> API. We saw above that the popup script can send two different sorts of messages: "beastify" and "reset".</p> + +<ul> + <li>if the message is "beastify", we expect it to contain a URL pointing to a beast image. We remove any beasts that might have been added by previous "beastify" calls, then construct and append an <code><a href="/en-US/docs/Web/HTML/Element/img"><img></a></code> element whose <code>src</code> attribute is set to the beast URL.</li> + <li>if the message is "reset", we just remove any beasts that might have been added.</li> +</ul> + +<h3 id="As_feras">As feras</h3> + +<p>Finally, we need to include the images of the beasts.</p> + +<p>Create a new directory called "beasts", and add the three images in that directory, with the appropriate names. You can get the images from <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify/beasts">the GitHub repository</a>, or from here:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11459/frog.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"><img alt="" src="https://mdn.mozillademos.org/files/11461/snake.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"><img alt="" src="https://mdn.mozillademos.org/files/11463/turtle.jpg" style="display: inline-block; height: 200px; margin: 20px; width: 200px;"></p> + +<h2 id="Testar_a_extensão">Testar a extensão</h2> + +<p>First, double check that you have the right files in the right places:</p> + +<pre>beastify/ + + beasts/ + frog.jpg + snake.jpg + turtle.jpg + + content_scripts/ + beastify.js + + icons/ + beasts-32.png + beasts-48.png + + popup/ + choose_beast.css + choose_beast.html + choose_beast.js + + manifest.json</pre> + +<p>Starting in Firefox 45, you can install extensions temporarily from disk.</p> + +<p>Open "about:debugging" in Firefox, click "Load Temporary Add-on", and select your manifest.json file. You should then see the extension's icon appear in the Firefox toolbar:</p> + +<p>{{EmbedYouTube("sAM78GU4P34")}}</p> + +<p>Open a web page, then click the icon, select a beast, and see the web page change:</p> + +<p>{{EmbedYouTube("YMQXyAQSiE8")}}</p> + +<h2 id="Programae_a_partir_da_linha_de_comando">Programae a partir da linha de comando</h2> + +<p>Pode automatizar o passo da instalação temporária utilizando a ferramenta <a href="/pt-PT/Add-ons/WebExtensions/Primeiros_passos_com_web-ext">web-ext</a>. Experimente isto:</p> + +<pre class="brush: bash">cd beastify +web-ext run</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/anatomia_de_uma_extensao/index.html b/files/pt-pt/mozilla/add-ons/webextensions/anatomia_de_uma_extensao/index.html new file mode 100644 index 0000000000..ecad403ae1 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/anatomia_de_uma_extensao/index.html @@ -0,0 +1,135 @@ +--- +title: Anatomia de uma extensão +slug: Mozilla/Add-ons/WebExtensions/Anatomia_de_uma_extensao +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>Uma extensão consiste numa coleção de ficheiros, empacotados para distribuição e instalação. Neste artigo, nós passaremos rapidamente pelos ficheiros que podem estar presentes numa extensão.</p> + +<h2 id="manifest.json">manifest.json</h2> + +<p>This is the only file that must be present in every extension. It contains basic metadata such as its name, version and the permissions it requires. It also provides pointers to other files in the extension.</p> + +<p>This manifest can also contain pointers to several other types of files:</p> + +<ul> + <li><a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">Background pages</a>: Implement long-running logic.</li> + <li>Icons for the extension and any buttons it might define.</li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Sidebars_popups_options_pages">Sidebars, popups, and options pages</a>: HTML documents that provide content for various user interface components.</li> + <li><a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">Content scripts</a>: JavaScript included with your extension, that you will inject into web pages.</li> +</ul> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13669/webextension-anatomy.png" style="display: block; height: 581px; margin-left: auto; margin-right: auto; width: 600px;"></p> + +<p>See the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> reference page for all the details.</p> + +<p>Other than those referenced from the manifest, an extension can include additional <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Extension_pages">Extension pages</a> with supporting files.</p> + +<h2 id="Scripts_de_fundo_(segundo_plano)"><em>Scripts</em> de fundo (segundo plano)</h2> + +<p>Extensions often need to maintain long-term state or perform long-term operations independently of the lifetime of any particular web page or browser window. That is what background scripts are for.</p> + +<p>Background scripts are loaded as soon as the extension is loaded and stay loaded until the extension is disabled or uninstalled. You can use any of the <a href="/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> in the script, as long as you have requested the necessary <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a>.</p> + +<h3 id="Especificar_os_scripts_de_fundo">Especificar os <em>scripts</em> de fundo</h3> + +<p>You can include a background script using the <code>background</code> key in "manifest.json":</p> + +<pre class="brush: json">// manifest.json + +"background": { + "scripts": ["background-script.js"] +}</pre> + +<p>You can specify multiple background scripts: if you do, they run in the same context, just like multiple scripts that are loaded into a single web page.</p> + +<h3 id="Ambiente_de_script_de_fundo">Ambiente de <em>script</em> de fundo</h3> + +<h4 id="APIS_de_DOM">APIS de DOM</h4> + +<p>Background scripts run in the context of special pages called background pages. This gives them a <code><a href="/en-US/docs/Web/API/Window">window</a></code> global, along with all the standard DOM APIs provided by that object.</p> + +<p>You do not have to supply your background page. If you include a background script, an empty background page will be created for you.</p> + +<p>However, you can choose to supply your background page as a separate HTML file:</p> + +<pre class="brush: json">// manifest.json + +"background": { + "page": "background-page.html" +}</pre> + +<h4 id="APIs_da_Extensão_da_Web">APIs da Extensão da Web</h4> + +<p>Background scripts can use any of the <a href="/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> in the script, as long as their extension has the necessary <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a>.</p> + +<h4 id="Acesso_cruzado_da_origem">Acesso cruzado da origem</h4> + +<p>Background scripts can make XHR requests to any hosts for which they have <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">host permissions</a>.</p> + +<h4 id="Conteúdo_da_Web">Conteúdo da Web</h4> + +<p>Background scripts do not get direct access to web pages. However, they can load <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts</a> into web pages and can <a href="/en-US/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">communicate with these content scripts using a message-passing API</a>.</p> + +<h4 id="Política_de_segurança_do_conteúdo">Política de segurança do conteúdo</h4> + +<p>Background scripts are restricted from certain potentially dangerous operations, like the use of <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>, through a Content Security Policy. See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> for more details on this.</p> + +<h2 id="Barras_laterais_janelas_(popups)_opções_de_páginas">Barras laterais, janelas (popups), opções de páginas</h2> + +<p>A sua extensão pode inclur vários componentes da interface do utilizador cujo conteúdo é definido utilizando um documento HTML:</p> + +<ul> + <li>uma <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Barras_laterais">barra lateral</a> é um painel que é exibido no lado esquerdo da janela do navegador, junto à página da <em>web</em></li> + <li>uma <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Popups">janela (popup</a>) é uma janela que pode exibir quando o utilizador clica num <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/A%C3%A7%C3%A3o_navegador">botão da barra de ferramentas</a> ou <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Acoes_pagina">botão da barra de endereço</a></li> + <li>uma <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Options_pages">página de opções </a>é uma página que é mostrada quando o utilizador acede ao seu extra de preferências no gestor de extras nativo do navegador</li> +</ul> + +<p>For each of these components, you create an HTML file and point to it using a specific property in <a href="/pt-PT/Add-ons/WebExtensions/manifest.json">manifest.json</a>. The HTML file can include CSS and JavaScript files, just like a normal web page.</p> + +<p>All of these are a type of <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Paginas_de_extens%C3%A3o">Extension pages</a>, and unlike a normal web page, your JavaScript can use all the same privileged WebExtension APIs as your background script. They can even directly access variables in the background page using {{WebExtAPIRef("runtime.getBackgroundPage()")}}.</p> + +<h2 id="Páginas_de_extensão">Páginas de extensão</h2> + +<p>You can also include HTML documents in your extension which are not attached to some predefined user interface component. Unlike the documents you might provide for sidebars, popups, or options pages, these don't have an entry in manifest.json. However, they do also get access to all the same privileged WebExtension APIs as your background script.</p> + +<p>You'd typically load a page like this using {{WebExtAPIRef("windows.create()")}} or {{WebExtAPIRef("tabs.create()")}}.</p> + +<p>See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages">Extension pages</a> to learn more.</p> + +<h2 id="Scripts_de_conteúdo"><em>Scripts</em> de conteúdo</h2> + +<p>Use content scripts to access and manipulate web pages. Content scripts are loaded into web pages and run in the context of that particular page.</p> + +<p>Content scripts are extension-provided scripts which run in the context of a web page; this differs from scripts which are loaded by the page itself, including those which are provided in {{HTMLElement("script")}} elements within the page.</p> + +<p>Content scripts can see and manipulate the page's DOM, just like normal scripts loaded by the page.</p> + +<p>Unlike normal page scripts, they can:</p> + +<ul> + <li>Make cross-domain XHR requests.</li> + <li>Use a small subset of the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API">WebExtension APIs</a>.</li> + <li>Exchange messages with their background scripts and can in this way indirectly access all the WebExtension APIs.</li> +</ul> + +<p>Content scripts cannot directly access normal page scripts but can exchange messages with them using the standard <code><a href="/en-US/docs/Web/API/Window/postMessage">window.postMessage()</a></code> API.</p> + +<p>Usually, when we talk about content scripts, we are referring to JavaScript, but you can inject CSS into web pages using the same mechanism.</p> + +<p>See the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts</a> article to learn more.</p> + +<h2 id="Recursos_de_acessibilidade_da_Web">Recursos de acessibilidade da Web</h2> + +<p>Web accessible resources are resources such as images, HTML, CSS, and JavaScript that you include in the extension and want to make accessible to content scripts and page scripts. Resources which are made web-accessible can be referenced by page scripts and content scripts using a special URI scheme.</p> + +<p>For example, if a content script wants to insert some images into web pages, you could include them in the extension and make them web accessible. Then the content script could create and append <code><a href="/en-US/docs/Web/HTML/Element/img">img</a></code> tags which reference the images via the <code>src</code> attribute.</p> + +<p>To learn more, see the documentation for the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a> manifest.json key.</p> + +<p> </p> + +<p> </p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/armazenamento/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/armazenamento/index.html new file mode 100644 index 0000000000..d267faf520 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/armazenamento/index.html @@ -0,0 +1,105 @@ +--- +title: Armazenamento +slug: Mozilla/Add-ons/WebExtensions/API/Armazenamento +tags: + - API + - Armazenamento + - Extensões + - Extensões da Web + - Extras + - Interface + - Não Padrão + - Referencia +translation_of: Mozilla/Add-ons/WebExtensions/API/storage +--- +<div>{{AddonSidebar}}</div> + +<p>Permite que as extensões armazenem e recuperem dados, e escutem as alterações aos itens armazenados.</p> + +<p>O sistema de armazenamento é baseado na <a href="/pt-PT/docs/Web/API/API_de_Armazenamento_da_Web">API de Armazenamento da Web</a>, com algumas diferenças. Entre outras diferençãs, estas incluem:</p> + +<ul> + <li>It's asynchronous.</li> + <li>Values are scoped to the extension, not to a specific domain (i.e. the same set of key/value pairs are available to all scripts in the background context and content scripts).</li> + <li>The values stored can be any JSON-ifiable value, not just <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>. Among other things, this includes: <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> and <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>, but only when their contents can can be represented as JSON, which does not include DOM nodes. You don't need to convert your values to JSON <code>Strings</code> prior to storing them, but they are represented as JSON internally, thus the requirement that they be JSON-ifiable.</li> + <li>Multiple key/value pairs can be set or retrieved in the same API call.</li> +</ul> + +<p>To use this API you need to include the "storage" <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a> in your <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> file.</p> + +<p>Each extension has its own storage area, which can be split into different types of storage.</p> + +<p>Although this API is similar to {{domxref("Window.localStorage")}} it is recommended that you don't use <code>Window.localStorage</code> in the extension code to store extension-related data. Firefox will clear data stored by extensions using the localStorage API in various scenarios where users clear their browsing history and data for privacy reasons, while data saved using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/local">storage.local</a></code> API will be correctly persisted in these scenarios.</p> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea")}}</dt> + <dd>An object representing a storage area.</dd> + <dt>{{WebExtAPIRef("storage.StorageChange")}}</dt> + <dd>An object representing a change to a storage area.</dd> +</dl> + +<h2 id="Propriedades">Propriedades</h2> + +<p><code>storage</code> has three properties, which represent the different types of available storage area.</p> + +<dl> + <dt>{{WebExtAPIRef("storage.sync")}}</dt> + <dd>Represents the <code>sync</code> storage area. Items in <code>sync</code> storage are synced by the browser, and are available across all instances of that browser that the user is logged into, across different devices.</dd> + <dt>{{WebExtAPIRef("storage.local")}}</dt> + <dd>Represents the <code>local</code> storage area. Items in <code>local</code> storage are local to the machine the extension was installed on.</dd> + <dt>{{WebExtAPIRef("storage.managed")}}</dt> + <dd>Represents the <code>managed</code> storage area. Items in <code>managed</code> storage are set by the domain administrator and are read-only for the extension. Trying to modify this namespace results in an error.</dd> +</dl> + +<h2 id="Eventos">Eventos</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.onChanged")}}</dt> + <dd>Fired when one or more items change in a storage area.</dd> +</dl> + +<h2 id="Compatibilidade_do_navegador">Compatibilidade do navegador</h2> + +<p>{{Compat("webextensions.api.storage")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Reconehcimentos</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/storage"><code>chrome.storage</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/browseraction/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/browseraction/index.html new file mode 100644 index 0000000000..2b520684db --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/browseraction/index.html @@ -0,0 +1,127 @@ +--- +title: Ação do navegador +slug: Mozilla/Add-ons/WebExtensions/API/browserAction +tags: + - API + - Ação do navegador + - Extensões + - Extensões da Web + - Extras + - Interface + - Não Padrão + - Referencia +translation_of: Mozilla/Add-ons/WebExtensions/API/browserAction +--- +<div>{{AddonSidebar}}</div> + +<p>Adiciona um botão à barra de ferramentas do navegador.</p> + +<p>Uma <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Ação_navegador">ação do navegador </a>é um botão na barra de ferramentas do navegador.</p> + +<p>You can associate a popup with the button. The popup is specified using HTML, CSS and JavaScript, just like a normal web page. JavaScript running in the popup gets access to all the same WebExtension APIs as your background scripts, but its global context is the popup, not the current page displayed in the browser. To affect web pages you need to communicate with them via <a href="/en-US/Add-ons/WebExtensions/Modify_a_web_page#Messaging">messages</a>.</p> + +<p>If you specify a popup, it will be shown — and the content will be loaded — when the user clicks the icon. If you do not specify a popup, then when the user clicks the icon an event is dispatched to your extension.</p> + +<p>You can define most of a browser action's properties declaratively using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> key in the manifest.json.</p> + +<p>With the <code>browserAction</code> API, you can:</p> + +<ul> + <li>use {{WebExtAPIRef("browserAction.onClicked")}} to listen for clicks on the icon.</li> + <li>get and set the icon's properties — icon, title, popup, and so on. You can get and set these globally across all tabs, or for a specific tab by passing the tab ID as an additional argument.</li> +</ul> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt>{{WebExtAPIRef("browserAction.ColorArray")}}</dt> + <dd>An array of four integers in the range 0-255 defining an RGBA color.</dd> + <dt>{{WebExtAPIRef("browserAction.ImageDataType")}}</dt> + <dd>Pixel data for an image. Must be an <code><a href="/en-US/docs/Web/API/ImageData">ImageData</a></code> object (for example, from a {{htmlelement("canvas")}} element).</dd> +</dl> + +<h2 id="Funções">Funções</h2> + +<dl> + <dt>{{WebExtAPIRef("browserAction.setTitle()")}}</dt> + <dd>Sets the browser action's title. This will be displayed in a tooltip.</dd> + <dt>{{WebExtAPIRef("browserAction.getTitle()")}}</dt> + <dd>Gets the browser action's title.</dd> + <dt>{{WebExtAPIRef("browserAction.setIcon()")}}</dt> + <dd>Sets the browser action's icon.</dd> + <dt>{{WebExtAPIRef("browserAction.setPopup()")}}</dt> + <dd>Sets the HTML document to be opened as a popup when the user clicks on the browser action's icon.</dd> + <dt>{{WebExtAPIRef("browserAction.getPopup()")}}</dt> + <dd>Gets the HTML document set as the browser action's popup.</dd> + <dt>{{WebExtAPIRef("browserAction.openPopup()")}}</dt> + <dd>Open the browser action's popup.</dd> + <dt>{{WebExtAPIRef("browserAction.setBadgeText()")}}</dt> + <dd>Sets the browser action's badge text. The badge is displayed on top of the icon.</dd> + <dt>{{WebExtAPIRef("browserAction.getBadgeText()")}}</dt> + <dd>Gets the browser action's badge text.</dd> + <dt>{{WebExtAPIRef("browserAction.setBadgeBackgroundColor()")}}</dt> + <dd>Sets the badge's background color.</dd> + <dt>{{WebExtAPIRef("browserAction.getBadgeBackgroundColor()")}}</dt> + <dd>Gets the badge's background color.</dd> + <dt>{{WebExtAPIRef("browserAction.enable()")}}</dt> + <dd>Enables the browser action for a tab. By default, browser actions are enabled for all tabs.</dd> + <dt>{{WebExtAPIRef("browserAction.disable()")}}</dt> + <dd>Disables the browser action for a tab, meaning that it cannot be clicked when that tab is active.</dd> +</dl> + +<h2 id="Eventos">Eventos</h2> + +<dl> + <dt>{{WebExtAPIRef("browserAction.onClicked")}}</dt> + <dd>Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.</dd> +</dl> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p>{{Compat("webextensions.api.browserAction")}}</p> + +<div class="hidden note"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Reconhecimentos</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/browserAction"><code>chrome.browserAction</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/browser_action.json"><code>browser_action.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/browsingdata/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/browsingdata/index.html new file mode 100644 index 0000000000..14dbd68d3a --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/browsingdata/index.html @@ -0,0 +1,130 @@ +--- +title: browsingData +slug: Mozilla/Add-ons/WebExtensions/API/browsingData +tags: + - API + - Add-ons + - Extensions + - NeedsTranslation + - Non-standard + - Reference + - TopicStub + - WebExtensions + - browsingData +translation_of: Mozilla/Add-ons/WebExtensions/API/browsingData +--- +<div>{{AddonSidebar}}</div> + +<p>Enables extensions to clear the data that is accumulated while the user is browsing.</p> + +<p>In the <code>browsingData</code> API, browsing data is divided into types:</p> + +<ul> + <li>browser cache</li> + <li>cookies</li> + <li>downloads</li> + <li>history</li> + <li>local storage</li> + <li>plugin data</li> + <li>saved form data</li> + <li>saved passwords</li> +</ul> + +<p>You can use the {{WebExtAPIRef("browsingData.remove()")}} function to remove any combination of these types. There are also dedicated functions to remove each particular type of data, such as {{WebExtAPIRef("browsingData.removePasswords()", "removePasswords()")}}, {{WebExtAPIRef("browsingData.removeHistory()", "removeHistory()")}} and so on.</p> + +<p>All the <code>browsingData.remove[X]()</code> functions take a {{WebExtAPIRef("browsingData.RemovalOptions")}} object, which you can use to control two further aspects of data removal:</p> + +<ul> + <li>how far back in time to remove data</li> + <li>whether to remove data only from normal web pages, or also from hosted web apps and add-ons. Note that this option is not yet supported in Firefox.</li> +</ul> + +<p>Finally, this API gives you a {{WebExtAPIRef("browsingData.settings()")}} function that gives you the current value of the settings for the browser's built-in "Clear History" feature.</p> + +<p>To use this API you must have the "browsingData" <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a>.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("browsingData.DataTypeSet")}}</dt> + <dd>Object used to specify the type of data to remove: for example, history, downloads, passwords, and so on.</dd> + <dt>{{WebExtAPIRef("browsingData.RemovalOptions")}}</dt> + <dd>Object used to specify how far back in time to remove data, and whether to remove data added through normal web browsing, by hosted apps, or by add-ons.</dd> +</dl> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{WebExtAPIRef("browsingData.remove()")}}</dt> + <dd>Removes browsing data for the data types specified.</dd> + <dt>{{WebExtAPIRef("browsingData.removeCache()")}}</dt> + <dd>Clears the browser's cache.</dd> + <dt>{{WebExtAPIRef("browsingData.removeCookies()")}}</dt> + <dd>Removes cookies.</dd> + <dt>{{WebExtAPIRef("browsingData.removeDownloads()")}}</dt> + <dd>Removes the list of downloaded files.</dd> + <dt>{{WebExtAPIRef("browsingData.removeFormData()")}}</dt> + <dd>Clears saved form data.</dd> + <dt>{{WebExtAPIRef("browsingData.removeHistory()")}}</dt> + <dd>Clears the browser's history.</dd> + <dt>{{WebExtAPIRef("browsingData.removeLocalStorage()")}}</dt> + <dd>Clears any <a href="/en-US/docs/Web/API/Window/localStorage">local storage</a> created by websites.</dd> + <dt>{{WebExtAPIRef("browsingData.removePasswords()")}}</dt> + <dd>Clears saved passwords.</dd> + <dt>{{WebExtAPIRef("browsingData.removePluginData()")}}</dt> + <dd>Clears data associated with plugins.</dd> + <dt>{{WebExtAPIRef("browsingData.settings()")}}</dt> + <dd>Gets the current value of settings in the browser's "Clear History" feature.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + + + +<p>{{Compat("webextensions.api.browsingData", 2)}}</p> + +<div class="note hidden"> +<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p> + +<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p> +</div> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/browsingData"><code>chrome.browsingData</code></a> API.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/browsingdata/removeplugindata/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/browsingdata/removeplugindata/index.html new file mode 100644 index 0000000000..e67f9b8c70 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/browsingdata/removeplugindata/index.html @@ -0,0 +1,124 @@ +--- +title: browsingData.removePluginData() +slug: Mozilla/Add-ons/WebExtensions/API/browsingData/removePluginData +tags: + - API + - Dados de navegação + - Extensões + - Extensões da Web + - Extras + - Referencia + - metodo + - remover Dados do Plug-in +translation_of: Mozilla/Add-ons/WebExtensions/API/browsingData/removePluginData +--- +<div>{{AddonSidebar()}}</div> + +<p>Limpa dados guardados nos plug-ins do navegador.</p> + +<p>Pode utilizar o parâmetro <code>removalOptions</code>, que é um objeto {{WebExtAPIRef("browsingData.RemovalOptions")}}, para:</p> + +<ul> + <li>limpar apenas os dados do plug-in guardados depois de algum tempo</li> + <li>controlar se deve limpar apenas os dados guardados pelos plug-ins em execução nas páginas da Web normais ou limpar os dados guardados pelos plug-ins em execução nas aplicações hospedadas e também nas extensões.</li> +</ul> + +<p>Esta é uma função assíncrona que retorna um <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p> + +<h2 id="Sintaxe">Sintaxe</h2> + +<pre class="syntaxbox brush:js">var removing = browser.browsingData.removePluginData( + removalOptions // RemovalOptions object +) +</pre> + +<h3 id="Parâmetros">Parâmetros</h3> + +<dl> + <dt><code>removalOptions</code></dt> + <dd><code>object</code>. A {{WebExtAPIRef("browsingData.RemovalOptions")}} object, which may be used to clear only plugin data stored after a given time, and whether to clear only data stored by plugins running in normal web pages or to clear data stored by plugins running in hosted apps and extensions as well.</dd> +</dl> + +<h3 id="Devolver_valor">Devolver valor</h3> + +<p>A <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.</p> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.browsingData.removePluginData")}}</p> + +<h2 id="Exemplos">Exemplos</h2> + +<p>Remove data stored by plugins in the last week:</p> + +<pre class="brush: js">function onRemoved() { + console.log("removed"); +} + +function onError(error) { + console.error(error); +} + +function weekInMilliseconds() { + return 1000 * 60 * 60 * 24 * 7; +} + +var oneWeekAgo = (new Date()).getTime() - weekInMilliseconds(); + +browser.browsingData.removePluginData({since: oneWeekAgo}). +then(onRemoved, onError);</pre> + +<p>Remove all data stored by plugins:</p> + +<pre class="brush: js">function onRemoved() { + console.log("removed"); +} + +function onError(error) { + console.error(error); +} + +browser.browsingData.removePluginData({}). +then(onRemoved, onError);</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Reconhecimentos</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/browsingData"><code>chrome.browsingData</code></a> API.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/devtools.panels/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/devtools.panels/index.html new file mode 100644 index 0000000000..ebeb53d591 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/devtools.panels/index.html @@ -0,0 +1,103 @@ +--- +title: devtools.panels +slug: Mozilla/Add-ons/WebExtensions/API/devtools.panels +tags: + - API + - Extensões + - Extensões da Web + - Extras + - Referencia + - devtools.panels +translation_of: Mozilla/Add-ons/WebExtensions/API/devtools.panels +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>Embora as APIs sejam baseadas no <a href="https://developer.chrome.com/extensions/devtools">Chrome devtools APIs</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>The <code>devtools.panels</code> API lets a devtools extension define its user interface inside the devtools window.</p> + +<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>With the <code>devtools.panels</code> API you can create new panels in the devtools window.</p> + +<p>Like all the <code>devtools</code> APIs, this API is only available to code running in the document defined in the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page">devtools_page</a> manifest.json key, or in other devtools documents created by the extension (such as the panel's own document). See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">Extending the developer tools</a> for more.</p> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/ElementsPanel">devtools.panels.ElementsPanel</a></code></dt> + <dd>Represents the HTML/CSS inspector in the browser's devtools.</dd> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/ExtensionPanel">devtools.panels.ExtensionPanel</a></code></dt> + <dd>Represents a devtools panel created by the extension.</dd> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/ExtensionSidebarPane">devtools.panels.ExtensionSidebarPane</a></code></dt> + <dd>Represents a pane that an extension has added to the HTML/CSS inspector in the browser's devtools.</dd> +</dl> + +<h2 id="Propriedades">Propriedades</h2> + +<dl> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/elements">devtools.panels.elements</a></code></dt> + <dd>A reference to an <code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/ElementsPanel">ElementsPanel</a></code> object.</dd> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/themeName">devtools.panels.themeName</a></code></dt> + <dd>The name of the current devtools theme.</dd> +</dl> + +<h2 id="Funções">Funções</h2> + +<dl> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/create">devtools.panels.create()</a></code></dt> + <dd>Creates a new devtools panel.</dd> +</dl> + +<h2 id="Eventos">Eventos</h2> + +<dl> + <dt><code><a href="/en-US/Add-ons/WebExtensions/API/devtools.panels/onThemeChanged">devtools.panels.onThemeChanged</a></code></dt> + <dd>Fired when the devtools theme changes.</dd> +</dl> + +<h2 id="Compatibilidade_do_navegador">Compatibilidade do navegador</h2> + +<p>{{Compat("webextensions.api.devtools.panels", 2)}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Reconhecimentos</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/devtools_panels"><code>chrome.devtools.panels</code></a> API.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/i18n/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/i18n/index.html new file mode 100644 index 0000000000..824e2eb308 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/i18n/index.html @@ -0,0 +1,93 @@ +--- +title: i18n +slug: Mozilla/Add-ons/WebExtensions/API/i18n +tags: + - API + - Extensões + - Extensões da Web + - Extras + - Não Padrão + - Referencia + - i18n +translation_of: Mozilla/Add-ons/WebExtensions/API/i18n +--- +<div>{{AddonSidebar}}</div> + +<p>Funções para a internationalizar a sua extensão. Pode utilizar estas APIs para ter as suas <em>strings</em> traduzidas dos ficheiros de localização empacotados com a sua extensão, descubra o idioma atual do navegador e descubra o valor do seu <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#The_Accept-Language_header">cabeçalho Accept-Language</a>.</p> + +<p id="See_also">Para mais detalhes em como utilizar i18n para sua extensão, consulte:</p> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization">Internationalization</a>: a guide to using the WebExtension i18n system.</li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference">Locale-Specific Message reference</a>: extensions supply locale-specific strings in files called <code>messages.json</code>. This page describes the format of <code>messages.json</code>.</li> +</ul> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt>{{WebExtAPIRef("i18n.LanguageCode")}}</dt> + <dd>A <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.10">language tag</a> such as <code>"en-US"</code> or "<code>fr</code>".</dd> +</dl> + +<h2 id="Funções">Funções</h2> + +<dl> + <dt>{{WebExtAPIRef("i18n.getAcceptLanguages()")}}</dt> + <dd>Gets the <a href="/en-US/docs/Web/HTTP/Content_negotiation#The_Accept-Language_header">accept-languages</a> of the browser. This is different from the locale used by the browser. To get the locale, use {{WebExtAPIRef('i18n.getUILanguage')}}.</dd> + <dt>{{WebExtAPIRef("i18n.getMessage()")}}</dt> + <dd>Gets the localized string for the specified message.</dd> + <dt>{{WebExtAPIRef("i18n.getUILanguage()")}}</dt> + <dd>Gets the UI language of the browser. This is different from {{WebExtAPIRef('i18n.getAcceptLanguages')}} which returns the preferred user languages.</dd> + <dt>{{WebExtAPIRef("i18n.detectLanguage()")}}</dt> + <dd>Detects the language of the provided text using the <a href="https://github.com/CLD2Owners/cld2">Compact Language Detector</a>.</dd> +</dl> + +<dl> +</dl> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p>{{Compat("webextensions.api.i18n")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<dl> +</dl> + +<div class="note"><strong>Agradecimentos</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/i18n"><code>chrome.i18n</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/i18n.json"><code>i18n.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/index.html new file mode 100644 index 0000000000..24e8c119a7 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/index.html @@ -0,0 +1,13 @@ +--- +title: APIs de JavaScript +slug: Mozilla/Add-ons/WebExtensions/API +translation_of: Mozilla/Add-ons/WebExtensions/API +--- +<div>{{AddonSidebar}}</div> + +<div>{{SubpagesWithSummaries}}</div> + +<div class="note"><strong>Agradecimentos</strong> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/pageaction/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/pageaction/index.html new file mode 100644 index 0000000000..1453336c6c --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/pageaction/index.html @@ -0,0 +1,108 @@ +--- +title: Ação de página +slug: Mozilla/Add-ons/WebExtensions/API/pageAction +tags: + - API + - Ação de página + - Extensões + - Extensões da Web + - Extras + - Interface + - Não Padrão + - Referencia +translation_of: Mozilla/Add-ons/WebExtensions/API/pageAction +--- +<div>{{AddonSidebar}}</div> + +<p>Uma <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Acoes_pagina">ação de página</a> é ícone clicável dentro da barra de endereço do navegador.</p> + +<p> </p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/12960/page-action.png" style="display: block; height: 262px; margin-left: auto; margin-right: auto; width: 850px;"></p> + +<p>Pode ouvir cliques no ícone, ou especificar uma <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Popups">janela (<em>popup</em>)</a> que será aberta quando o ícone for clicado.</p> + +<p>If you specify a popup, you can define its contents and behavior using HTML, CSS, and JavaScript, just like a normal web page. JavaScript running in the popup gets access to all the same WebExtension APIs as your background scripts.</p> + +<p>You can define most of a page action's properties declaratively using the <a href="/en-US/Add-ons/WebExtensions/manifest.json/page_action">page_action key</a> in your <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a>, but can also redefine them programmatically using this API.</p> + +<p>Page actions are for actions that are only relevant to particular pages. If your icon should always be available, use a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_action">browser action</a> instead.</p> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt>{{WebExtAPIRef("pageAction.ImageDataType")}}</dt> + <dd>Dados de píxel para uma imagem.</dd> +</dl> + +<h2 id="Funções">Funções</h2> + +<dl> + <dt>{{WebExtAPIRef("pageAction.show()")}}</dt> + <dd>Shows the page action for a given tab.</dd> + <dt>{{WebExtAPIRef("pageAction.hide()")}}</dt> + <dd>Hides the page action for a given tab.</dd> + <dt>{{WebExtAPIRef("pageAction.setTitle()")}}</dt> + <dd>Sets the page action's title. This is displayed in a tooltip over the page action.</dd> + <dt>{{WebExtAPIRef("pageAction.getTitle()")}}</dt> + <dd>Gets the page action's title.</dd> + <dt>{{WebExtAPIRef("pageAction.setIcon()")}}</dt> + <dd>Sets the page action's icon.</dd> + <dt>{{WebExtAPIRef("pageAction.setPopup()")}}</dt> + <dd>Sets the URL for the page action's popup.</dd> + <dt>{{WebExtAPIRef("pageAction.getPopup()")}}</dt> + <dd>Gets the URL for the page action's popup.</dd> + <dt>{{WebExtAPIRef("pageAction.openPopup()")}}</dt> + <dd>Opens the page action's popup.</dd> +</dl> + +<h2 id="Eventos">Eventos</h2> + +<dl> + <dt>{{WebExtAPIRef("pageAction.onClicked")}}</dt> + <dd>Fired when a page action icon is clicked. This event will not fire if the page action has a popup.</dd> +</dl> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p>{{Compat("webextensions.api.pageAction")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Reconhecimentos</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/pageAction"><code>chrome.pageAction</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/page_action.json"><code>page_action.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/api/sidebaraction/index.html b/files/pt-pt/mozilla/add-ons/webextensions/api/sidebaraction/index.html new file mode 100644 index 0000000000..8717b019f2 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/api/sidebaraction/index.html @@ -0,0 +1,182 @@ +--- +title: sidebarAction +slug: Mozilla/Add-ons/WebExtensions/API/sidebarAction +tags: + - API + - Barra Lateral + - Extensões + - Extensões da Web + - Não Padrão + - Referencia + - sidebarAction +translation_of: Mozilla/Add-ons/WebExtensions/API/sidebarAction +--- +<div>{{AddonSidebar}}</div> + +<p>Obtém e define as propriedades da barra lateral de uma extensão.</p> + +<p>Uma <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Barras_laterais">barra lateral</a> é um painel que é exibido no lado esquerdo ou direito da janela do navegador, ao lado da página da <em>web</em>. O navegador fornece uma interface do utilizador que permite ao utilizador ver as barras laterais disponíveis no momento e selecionar uma barra lateral para exibir. Utilizando a chave de manifest.json <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code> , uma extensão pdoe definir a sua própria barra lateral. Utilizando a API <code>sidebarAction</code> descrita aqui, uma extension pode obter um conjunto de propriedades da barra lateral.</p> + +<p>A API <code>sidebarAction</code> é modelada de perto na API {{WebExtAPIRef("browserAction")}}.</p> + +<p>A API sidebarAction é baseada na API <a href="https://dev.opera.com/extensions/sidebar-action-api/">sidebarAction d</a>o Opera. Contudo, note que o seguinte ainda não é suportado: <code>setBadgeText()</code>, <code>getBadgeText()</code>, <code>setBadgeBackgroundColor()</code>, <code>getBadgeBackgroundColor()</code>, <code>onFocus</code>, <code>onBlur</code>.</p> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt>{{WebExtAPIRef("sidebarAction.ImageDataType")}}</dt> + <dd>Dados de pixel para uma imagem. Deve ser um objeto <code><a href="/en-US/docs/Web/API/ImageData">ImageData</a></code> (por exemplo, de um elemento {{htmlelement("canvas")}}).</dd> +</dl> + +<h2 id="Funções">Funções</h2> + +<dl> + <dt>{{WebExtAPIRef("sidebarAction.setPanel()")}}</dt> + <dd>Define o painel da barra lateral.</dd> + <dt>{{WebExtAPIRef("sidebarAction.getPanel()")}}</dt> + <dd>Obtém o painel da barra lateral.</dd> + <dt>{{WebExtAPIRef("sidebarAction.setTitle()")}}</dt> + <dd>Definie o título da barra lateral. Isto será exibido em qualquer IU fornecida pelo navegador para listar as barras de ferrramentas, tal como um menu.</dd> + <dt>{{WebExtAPIRef("sidebarAction.getTitle()")}}</dt> + <dd>Obtém o título da barra lateral.</dd> + <dt>{{WebExtAPIRef("sidebarAction.setIcon()")}}</dt> + <dd>Define o ícone da barra lateral.</dd> + <dt>{{WebExtAPIRef("sidebarAction.open()")}}</dt> + <dd>Abre a abarra lateral.</dd> + <dt>{{WebExtAPIRef("sidebarAction.close()")}}</dt> + <dd>fecha a barra lateral.</dd> + <dt>{{WebExtAPIRef("sidebarAction.isOpen()")}}</dt> + <dd>Verifica sebarra lateral está ou não aberta.</dd> +</dl> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p>{{Compat("webextensions.api.sidebarAction")}}</p> + +<h2 id="Exemplo_de_extras_(add-ons)">Exemplo de extras (add-ons)</h2> + +<ul> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">página de notas (annotate-page</a>)</li> +</ul> + +<div class="note"><strong>Reconhecimentos</strong> + +<p>Esta API é baseada na API <a href="https://dev.opera.com/extensions/sidebar-action-api/"><code>chrome.sidebarAction</code></a> do Opera.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> + +<div id="SL_balloon_obj" style="display: block;"> +<div class="SL_ImTranslatorLogo" id="SL_button" style="display: none;"> </div> + +<div id="SL_shadow_translation_result2" style="display: none;"> </div> + +<div id="SL_shadow_translator" style="display: none;"> +<div id="SL_planshet"> +<div id="SL_arrow_up" style=""> </div> + +<div id="SL_Bproviders"> +<div class="SL_BL_LABLE_ON" id="SL_P0" title="Google">G</div> + +<div class="SL_BL_LABLE_ON" id="SL_P1" title="Microsoft">M</div> + +<div class="SL_BL_LABLE_ON" id="SL_P2" title="Translator">T</div> +</div> + +<div id="SL_alert_bbl" style="display: none;"> +<div id="SLHKclose" style=""> </div> + +<div id="SL_alert_cont"> </div> +</div> + +<div id="SL_TB"> +<table id="SL_tables"> + <tbody> + <tr> + <td class="SL_td"><input></td> + <td class="SL_td"><select><option value="auto">Detect language</option><option value="af">Afrikaans</option><option value="sq">Albanian</option><option value="am">Amharic</option><option value="ar">Arabic</option><option value="hy">Armenian</option><option value="az">Azerbaijani</option><option value="eu">Basque</option><option value="be">Belarusian</option><option value="bn">Bengali</option><option value="bs">Bosnian</option><option value="bg">Bulgarian</option><option value="ca">Catalan</option><option value="ceb">Cebuano</option><option value="ny">Chichewa</option><option value="zh-CN">Chinese (Simplified)</option><option value="zh-TW">Chinese (Traditional)</option><option value="co">Corsican</option><option value="hr">Croatian</option><option value="cs">Czech</option><option value="da">Danish</option><option value="nl">Dutch</option><option value="en">English</option><option value="eo">Esperanto</option><option value="et">Estonian</option><option value="tl">Filipino</option><option value="fi">Finnish</option><option value="fr">French</option><option value="fy">Frisian</option><option value="gl">Galician</option><option value="ka">Georgian</option><option value="de">German</option><option value="el">Greek</option><option value="gu">Gujarati</option><option value="ht">Haitian Creole</option><option value="ha">Hausa</option><option value="haw">Hawaiian</option><option value="iw">Hebrew</option><option value="hi">Hindi</option><option value="hmn">Hmong</option><option value="hu">Hungarian</option><option value="is">Icelandic</option><option value="ig">Igbo</option><option value="id">Indonesian</option><option value="ga">Irish</option><option value="it">Italian</option><option value="ja">Japanese</option><option value="jw">Javanese</option><option value="kn">Kannada</option><option value="kk">Kazakh</option><option value="km">Khmer</option><option value="ko">Korean</option><option value="ku">Kurdish</option><option value="ky">Kyrgyz</option><option value="lo">Lao</option><option value="la">Latin</option><option value="lv">Latvian</option><option value="lt">Lithuanian</option><option value="lb">Luxembourgish</option><option value="mk">Macedonian</option><option value="mg">Malagasy</option><option value="ms">Malay</option><option value="ml">Malayalam</option><option value="mt">Maltese</option><option value="mi">Maori</option><option value="mr">Marathi</option><option value="mn">Mongolian</option><option value="my">Myanmar (Burmese)</option><option value="ne">Nepali</option><option value="no">Norwegian</option><option value="ps">Pashto</option><option value="fa">Persian</option><option value="pl">Polish</option><option value="pt">Portuguese</option><option value="pa">Punjabi</option><option value="ro">Romanian</option><option value="ru">Russian</option><option value="sm">Samoan</option><option value="gd">Scots Gaelic</option><option value="sr">Serbian</option><option value="st">Sesotho</option><option value="sn">Shona</option><option value="sd">Sindhi</option><option value="si">Sinhala</option><option value="sk">Slovak</option><option value="sl">Slovenian</option><option value="so">Somali</option><option value="es">Spanish</option><option value="su">Sundanese</option><option value="sw">Swahili</option><option value="sv">Swedish</option><option value="tg">Tajik</option><option value="ta">Tamil</option><option value="te">Telugu</option><option value="th">Thai</option><option value="tr">Turkish</option><option value="uk">Ukrainian</option><option value="ur">Urdu</option><option value="uz">Uzbek</option><option value="vi">Vietnamese</option><option value="cy">Welsh</option><option value="xh">Xhosa</option><option value="yi">Yiddish</option><option value="yo">Yoruba</option><option value="zu">Zulu</option></select></td> + <td class="SL_td"> + <div id="SL_switch_b" style="" title="Switch languages"> </div> + </td> + <td class="SL_td"><select><option value="af">Afrikaans</option><option value="sq">Albanian</option><option value="am">Amharic</option><option value="ar">Arabic</option><option value="hy">Armenian</option><option value="az">Azerbaijani</option><option value="eu">Basque</option><option value="be">Belarusian</option><option value="bn">Bengali</option><option value="bs">Bosnian</option><option value="bg">Bulgarian</option><option value="ca">Catalan</option><option value="ceb">Cebuano</option><option value="ny">Chichewa</option><option value="zh-CN">Chinese (Simplified)</option><option value="zh-TW">Chinese (Traditional)</option><option value="co">Corsican</option><option value="hr">Croatian</option><option value="cs">Czech</option><option value="da">Danish</option><option value="nl">Dutch</option><option value="en">English</option><option value="eo">Esperanto</option><option value="et">Estonian</option><option value="tl">Filipino</option><option value="fi">Finnish</option><option value="fr">French</option><option value="fy">Frisian</option><option value="gl">Galician</option><option value="ka">Georgian</option><option value="de">German</option><option value="el">Greek</option><option value="gu">Gujarati</option><option value="ht">Haitian Creole</option><option value="ha">Hausa</option><option value="haw">Hawaiian</option><option value="iw">Hebrew</option><option value="hi">Hindi</option><option value="hmn">Hmong</option><option value="hu">Hungarian</option><option value="is">Icelandic</option><option value="ig">Igbo</option><option value="id">Indonesian</option><option value="ga">Irish</option><option value="it">Italian</option><option value="ja">Japanese</option><option value="jw">Javanese</option><option value="kn">Kannada</option><option value="kk">Kazakh</option><option value="km">Khmer</option><option value="ko">Korean</option><option value="ku">Kurdish</option><option value="ky">Kyrgyz</option><option value="lo">Lao</option><option value="la">Latin</option><option value="lv">Latvian</option><option value="lt">Lithuanian</option><option value="lb">Luxembourgish</option><option value="mk">Macedonian</option><option value="mg">Malagasy</option><option value="ms">Malay</option><option value="ml">Malayalam</option><option value="mt">Maltese</option><option value="mi">Maori</option><option value="mr">Marathi</option><option value="mn">Mongolian</option><option value="my">Myanmar (Burmese)</option><option value="ne">Nepali</option><option value="no">Norwegian</option><option value="ps">Pashto</option><option value="fa">Persian</option><option value="pl">Polish</option><option value="pt">Portuguese</option><option value="pa">Punjabi</option><option value="ro">Romanian</option><option value="ru">Russian</option><option value="sm">Samoan</option><option value="gd">Scots Gaelic</option><option value="sr">Serbian</option><option value="st">Sesotho</option><option value="sn">Shona</option><option value="sd">Sindhi</option><option value="si">Sinhala</option><option value="sk">Slovak</option><option value="sl">Slovenian</option><option value="so">Somali</option><option selected value="es">Spanish</option><option value="su">Sundanese</option><option value="sw">Swahili</option><option value="sv">Swedish</option><option value="tg">Tajik</option><option value="ta">Tamil</option><option value="te">Telugu</option><option value="th">Thai</option><option value="tr">Turkish</option><option value="uk">Ukrainian</option><option value="ur">Urdu</option><option value="uz">Uzbek</option><option value="vi">Vietnamese</option><option value="cy">Welsh</option><option value="xh">Xhosa</option><option value="yi">Yiddish</option><option value="yo">Yoruba</option><option value="zu">Zulu</option></select></td> + <td class="SL_td"> </td> + <td class="SL_td"> + <div id="SL_TTS_voice" style="" title="English"> </div> + </td> + <td class="SL_td"> + <div class="SL_copy" id="SL_copy" style="" title="Copy translation"> </div> + </td> + <td class="SL_td"> + <div id="SL_bbl_font_patch"> </div> + + <div class="SL_bbl_font" id="SL_bbl_font" style="" title="Font size"> </div> + </td> + <td class="SL_td"> + <div id="SL_bbl_help" style="" title="Help"> </div> + </td> + <td class="SL_td"> + <div class="SL_pin_off" id="SL_pin" style="" title="Pin pop-up bubble"> </div> + </td> + </tr> + </tbody> +</table> +</div> +</div> + +<div id="SL_shadow_translation_result" style=""> </div> + +<div class="SL_loading" id="SL_loading" style=""> </div> + +<div id="SL_player2"> </div> + +<div id="SL_alert100">Text-to-speech function is limited to 200 characters</div> + +<div id="SL_Balloon_options" style="background: rgb(255, 255, 255);"> +<div id="SL_arrow_down" style=""> </div> + +<table id="SL_tbl_opt" style="width: 100%;"> + <tbody> + <tr> + <td><input></td> + <td> + <div id="SL_BBL_IMG" style="" title="Show Translator's button 3 second(s)"> </div> + </td> + <td><a class="SL_options" title="Show options">Options</a> : <a class="SL_options" title="Translation History">History</a> : <a class="SL_options" title="ImTranslator Feedback">Feedback</a> : <a class="SL_options" href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=GD9D8CPW8HFA2" title="Make a small contribution">Donate</a></td> + <td><span id="SL_Balloon_Close" title="Close">Close</span></td> + </tr> + </tbody> +</table> +</div> +</div> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/as_melhores_praticas_de_experiencia_do_utilizador/index.html b/files/pt-pt/mozilla/add-ons/webextensions/as_melhores_praticas_de_experiencia_do_utilizador/index.html new file mode 100644 index 0000000000..0b3aba116e --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/as_melhores_praticas_de_experiencia_do_utilizador/index.html @@ -0,0 +1,159 @@ +--- +title: As melhores práticas de experiência do utilizador +slug: >- + Mozilla/Add-ons/WebExtensions/As_melhores_praticas_de_experiencia_do_utilizador +tags: + - Extensões + - Extras + - Guía + - IU + - UX +translation_of: Mozilla/Add-ons/WebExtensions/User_experience_best_practices +--- +<div>{{AddonSidebar()}}</div> + +<p dir="ltr" id="docs-internal-guid-04f024b5-ab18-81ba-29b2-520d0891bcac">As melhores extensões do Firefox fornecem aos utilizadores uma nova funcionalidade ou recurso que corresponde a uma necessidade. Ao corresponder a essa necessidade irá ajudar os utilziadores a trabalhar de uma maneira mais inteligente ou eficiente, ou a obter mais prazer com a sua experiência de navegação.</p> + +<p dir="ltr">You will also want to make sure your users have a great experience using your extension and as a result give it great feedback and a good rating on <a href="https://addons.mozilla.org">addons.mozilla.org</a> (AMO).</p> + +<p dir="ltr">Much has been written about what makes software usable. If you are new to the subject, a good place to start is Jakob Nielsen’s <a href="https://en.wikipedia.org/wiki/Heuristic_evaluation#Nielsen">Usability Heuristics</a>. We recommend, whether you are new to extension development or a seasoned pro, using Nielsen’s Heuristics as a checklist when <a href="#Test_test_and_then_test_again">testing your user experience (UX)</a>.</p> + +<p dir="ltr">So, here we discuss much more specific Firefox and browser extension UX features, offering advice and suggestions that will help you build an extension that delights your users.</p> + +<h2 dir="ltr" id="Seja_Firefoxy">Seja <em>Firefoxy</em></h2> + +<p dir="ltr">Your users have chosen Firefox for a reason, possibly several reasons, so match your extension’s philosophy, features, and look and feel to that of Firefox.</p> + +<h3 dir="ltr" id="Design_values">Design values</h3> + +<p dir="ltr">To best meet the needs of Firefox users, align with the Firefox values.</p> + +<p dir="ltr">The <a href="https://design.firefox.com/values/">Firefox Design Values</a> state that we respect the user's privacy and sovereignty and do not surprise them. We start users with smart defaults on the functionality they want to use and enable them to customize those to their personal preferences so that they are in full control of their experience. We add humor and whimsy to our design and pay attention to details, quality, and performance. Local differences in a global world are important to us, and we help people make sense of the web in clear language.</p> + +<h3 dir="ltr" id="Apresentação_e_impressão">Apresentação e impressão</h3> + +<p dir="ltr">To provide your extensions with the best long term fit to Firefox, align with the <a href="http://design.firefox.com/photon">Firefox Photon Design System</a>. Following Photon will ensure that your extension integrates with the Firefox experience and will make it easier for people to use.</p> + +<h2 dir="ltr" id="Mantenha-a_focada">Mantenha-a focada</h2> + +<p dir="ltr">An extension is best when it is centered around one main use case, addressing that use case as well as possible for the target audience. It should add one function or set of closely related functions to the browser, modify a function of the browser, or modify web pages. Determine if you have achieved this by asking whether you can easily communicate the features and purpose of the extension in three (short) sentences or less.</p> + +<div class="note"> +<p dir="ltr">A short summary description of your extension is also very useful when it comes to creating its listing on AMO, see <a href="/en-US/Add-ons/Listing#Make_sure_your_summary_is_just_long_enough">Make sure your summary is just long enough</a> for more details.</p> +</div> + +<h2 dir="ltr" id="Comece_agora_mesmo">Comece agora mesmo</h2> + +<p dir="ltr">Ensure that your extension is ready to be used immediately after installation. It should be optimized for its main use case, and work as expected for most users without the need for customization.</p> + +<p dir="ltr">Do not expect your users to read detailed instructions, other content, or ask them to configure the extension to use it. Doing so could mean they never get started with your extension and, if they do, could result in poor reviews.</p> + +<h2 dir="ltr" id="Dê_aos_utilizadores_o_que_eles_precisam_onde_eles_precisam">Dê aos utilizadores o que eles precisam, onde eles precisam</h2> + +<p dir="ltr">Choosing the right way or combination of ways to make your extension's functionality available to the user can have a significant effect on usability. Asking a few simple questions about your extension’s functionality can quickly guide you to the right choices:</p> + +<h3 dir="ltr" id="A_minha_extensão_funciona_na_maioria_dos_sites_da_Web_e_páginas_da_Web">A minha extensão funciona na maioria dos sites da Web e páginas da Web?</h3> + +<p dir="ltr">If your extension provides the user with features they can use on almost every website or page, give the user access to it from a <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Browser_action">toolbar button</a> using the <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browser action</a>. This might include providing access to your image editor or opening a page from your website.</p> + +<p dir="ltr"><img alt="" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="display: block; height: 387px; margin-left: auto; margin-right: auto; width: 782px;"></p> + +<p dir="ltr">Where you have several features you want to give the user access, you can add a <a href="/en-US/Add-ons/WebExtensions/Popups">popup</a> to the button.</p> + +<h3 dir="ltr" id="A_minha_extensão_funciona_apenas_em_alguns_sites_da_Web_e_páginas">A minha extensão funciona apenas em alguns sites da Web e páginas?</h3> + +<p dir="ltr">If your extension offers a feature for a type of web page or specific domains, give the user access to it from an <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">address bar button</a> using a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">page action</a>. This might include providing access to your RSS reader on pages with RSS feeds or providing an extended feature to pages on your website.</p> + +<p dir="ltr"><img alt="" src="https://mdn.mozillademos.org/files/12960/page-action.png" style="display: block; height: 262px; margin-left: auto; margin-right: auto; width: 850px;"></p> + +<p dir="ltr">Where you have several features you want to give the user access, you can add a <a href="/en-US/Add-ons/WebExtensions/Popups">popup</a> to the button.</p> + +<h3 dir="ltr" id="A_minha_extensão_precisa_de_mostrar_informação_ou_oferecer_ações_em_paralelo_com_as_páginas_da_Web">A minha extensão precisa de mostrar informação ou oferecer ações em paralelo com as páginas da Web?</h3> + +<p dir="ltr">If your extension includes information or actions that a user would want immediate access to while viewing any web page, use a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">sidebar</a>. This might include notes the user can make about a page’s content or a feature offering various font substitutions to improve readability.</p> + +<p dir="ltr"><img alt="" src="https://mdn.mozillademos.org/files/14825/bookmarks-sidebar.png" style="display: block; height: 761px; margin-left: auto; margin-right: auto; width: 728px;"></p> + +<h3 dir="ltr" id="A_minha_extensão_oferece_funcionalidade_especifica_para_o_conteúdo_da_página_ou_outras_funcionalidades_do_navegador">A minha extensão oferece funcionalidade especifica para o conteúdo da página ou outras funcionalidades do navegador?</h3> + +<p dir="ltr">If your extension offers features the user might want to access in context, add them to an appropriate <a href="/en-US/Add-ons/WebExtensions/user_interface/Context_menu_items">context menu</a>. This might include offering access to an image editor on the image context menu or offering extended copy features on the context menu for selected page content.</p> + +<p dir="ltr"><img alt="Example of content menu items added by a WebExtension, from the context-menu-demo example" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="display: block; height: 587px; margin-left: auto; margin-right: auto; width: 573px;"></p> + +<h3 dir="ltr" id="A_minha_extensão_tem_definições_que_o_utilizador_pode_ajustar">A minha extensão tem definições que o utilizador pode ajustar?</h3> + +<p dir="ltr">If your extension enables the user to change and save settings that affect the behavior of the extension, use an <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">options page</a> to provide a standard Preferences link to settings from the Add-on Manager.</p> + +<p dir="ltr"><img alt="Typical preferences button, to access an extension's settings, from the Add-on Manager" src="https://mdn.mozillademos.org/files/15271/add-on-manager-preferences-button.png" style="display: block; height: 80px; margin-left: auto; margin-right: auto; width: 732px;"></p> + +<h3 dir="ltr" id="A_minha_extensão_precisa_de_recolher_muita_informação_ou_exibir_conteúdo_em_adição_aos_separadores_atuais">A minha extensão precisa de recolher muita informação ou exibir conteúdo em adição aos separadores atuais?</h3> + +<p dir="ltr">Where your extension needs to gather or display significant amounts of information (more than is suitable for an <a href="/en-US/docs/Web/API/Window/alert">alert</a> or would benefit from additional formatting) use <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Bundled_web_pages">bundled web pages</a> to deliver forms and similar content.</p> + +<p dir="ltr"><img alt="Example of a simple bundled page displayed as a detached panel." src="https://mdn.mozillademos.org/files/15073/bundled_page_as_panel.png" style="display: block; height: 445px; margin-left: auto; margin-right: auto; width: 680px;"></p> + +<h3 dir="ltr" id="A_minha_extensão_tenta_ajudar_o_utilizador_a_entrar_as_páginas_da_Web_ou_conteúdo">A minha extensão tenta ajudar o utilizador a entrar as páginas da Web ou conteúdo?</h3> + +<p dir="ltr">Where your extension includes a use case to locate web pages or content, for example, offering a site specific search, use <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox">address bar suggestions</a> to deliver those recommendations.</p> + +<p dir="ltr"><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15075/omnibox_example_full.png" style="display: block; height: 325px; margin-left: auto; margin-right: auto; width: 679px;"></p> + +<h3 dir="ltr" id="A_minha_extensão_oferece_ferramentas_para_os_programadores">A minha extensão oferece ferramentas para os programadores?</h3> + +<p dir="ltr">Where you are providing tools for developers, add them to the Firefox developer tools using <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels">developer tools panels</a>.</p> + +<h2 dir="ltr" id="Mantenha_o_utilizador_informado">Mantenha o utilizador informado</h2> + +<p dir="ltr">Ensuring the user knows what will happen, is happening, and has happened in your extension is an essential part of building trust and ensuring a happy user.</p> + +<h3 dir="ltr" id="Diga_ao_utilizador_o_que_irá_acontecer_antes_que_aconteça">Diga ao utilizador o que irá acontecer, antes que aconteça</h3> + +<p dir="ltr">Users should understand what will happen when they click a button. In addition to a meaningful, descriptive button label, provide tooltips that describe the action that the button will perform.</p> + +<div class="note"> +<p dir="ltr">Do not put the name of the extension alone in the tooltip, unless it is descriptive of the action the button will perform.</p> +</div> + +<p dir="ltr">Do not use the tooltip for any other types of information such as elaborate statistics about your extension. Keep the tooltip content simple and focused on what will happen when the user clicks the button.</p> + +<h3 dir="ltr" id="Se_é_realmente_importante_e_o_utilizador_afastou-se_notifique-os">Se é realmente importante e o utilizador afastou-se, notifique-os</h3> + +<p dir="ltr">If your extension has completed a critical, long running background task, when the task completes use the operating system’s native <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications">notifications</a> to update the user. This can be useful where the user may not be focusing on the extension, or the browser, when the process finishes. However, use sparingly. If it is sufficient for the user to discover that a process has completed when they return to the browser or extension, do not use notifications.</p> + +<p dir="ltr"><img alt="" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="display: block; height: 334px; margin-left: auto; margin-right: auto; width: 700px;"></p> + +<h3 dir="ltr" id="Utilizar_browserAction_badges_sparingly">Utilizar browserAction badges sparingly</h3> + +<p dir="ltr">You can <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction/setBadgeText">add a badge</a> over the toolbar icon of a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a>, but do so sparingly to inform users about important events. Do not use them to provide regular or persistent status updates.</p> + +<p dir="ltr">When it comes to <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction/setBadgeBackgroundColor">coloring a badge</a>, using one of four colors for notifications of different severity is recommended:</p> + +<ul> + <li>Casual: azul</li> + <li>Sucesso: verde</li> + <li>Aviso: amarelo</li> + <li>Erro: vermelho</li> +</ul> + +<div class="note"> +<p dir="ltr">Use of Firefox colors is suggested, for more details see <a href="http://design.firefox.com/photon/visuals/color.html">Firefox Colors</a>. However, for compatibility with <a href="https://developer.chrome.com/extensions/browserAction#icon">Chrome</a> and Opera free color selection is supported.</p> +</div> + +<h2 dir="ltr" id="Testar_testar_e_depois_testar_novamente">Testar, testar, e depois testar novamente</h2> + +<p dir="ltr">Testing is a vital part of creating an outstanding UX for your extension. There are two key aspects of testing your UX:</p> + +<ol> + <li>Test across devices and platforms to ensure your extension works and performs well in as many places as possible. This includes considering factors such as the user’s screen size and resolution—just because your extension looks good and is easy to use on your desktop monitor does not mean it looks as good and works as well on a smaller laptop screen, or, indeed, vice versa.</li> + <li>Test with as many users as possible. Do not assume that you know your audience, as people’s backgrounds and experience can make a huge difference to how they interact with your extension. So, allow for user testing as part of your extension’s development.</li> +</ol> + +<p dir="ltr">Dicas de teste:</p> + +<ul> + <li>In AMO you have the option to <a href="/en-US/Add-ons/Distribution/Submitting_an_add-on#Listing_on_AMO">identify your extension as experimental</a> or publish a <a href="/en-US/Add-ons/Distribution#Beta_versions">beta or other non-final release</a>. If you flag your extension as experimental it is listed in AMO, so that any user can find it, but with a lower profile. When you are happy that the extension is ready for a wider audience, you can turn off the experimental flag and your extension will be listed as normal in AMO. If you have a published extension, you can use the Development channel to offer an alpha or beta version for testing. You will need to direct your testers to the Development Channel of your extension’s listing or let your testers know the link to use to install your extension.<br> + <img alt="The development channel section of an extension's listing page, offering access to alpha and beta versions for testing." src="https://mdn.mozillademos.org/files/15273/extensions-development-channel.png" style="display: block; height: 262px; margin-left: auto; margin-right: auto; width: 751px;"><br> + When you are happy with your update, you can publish it as the new release version of your extension.</li> + <li>If you want to distribute your extension to users outside AMO, you can find the instructions for doing so, and the installation instructions you need to provide users, in the article on <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Alternative_distribution_options/Sideloading_add-ons">Sideloading add-ons</a>. Remember that, unlike distribution through AMO, you will need to send users any updated versions of your extension as you make improvements.</li> + <li>Use the <a href="https://developer.mozilla.org/en-US/docs/Tools/Responsive_Design_Mode">Responsive Design Mode</a> to test your extension for its behavior on other screen sizes and device types.</li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/conversao_de_uma_extensao_legada_do_firefox/index.html b/files/pt-pt/mozilla/add-ons/webextensions/conversao_de_uma_extensao_legada_do_firefox/index.html new file mode 100644 index 0000000000..1898b1712a --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/conversao_de_uma_extensao_legada_do_firefox/index.html @@ -0,0 +1,81 @@ +--- +title: Conversão de uma extensão legada do Firefox +slug: Mozilla/Add-ons/WebExtensions/Conversao_de_uma_extensao_legada_do_firefox +translation_of: Mozilla/Add-ons/WebExtensions/Porting_a_legacy_Firefox_add-on +--- +<div>{{AddonSidebar}}</div> + +<p><span class="seoSummary">Se desenvolveu uma extensão do Firefox utilziando XUL/XPCOM ou SDK de EXtras, esta página irá ajudá-lo a migraar a sua extensão para utilizar as APIs das Extensões da Web. O padrão para criar extensões para o Firefox é para utilizar as </span>APIs das Extensões da Web. Este será a único tipo de extensão suportado no Firefox no fim de novembro de 2017, com o lançamento da versão 57 do <a class="external text" href="https://wiki.mozilla.org/RapidRelease/Calendar" rel="nofollow">Firefox</a>.</p> + +<h2 id="Início_rápido">Início rápido</h2> + +<ol> + <li>Get an idea of the main things you'll have to change in your extension: + <ul> + <li>Familiarize yourself with the <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">WebExtension format and structure</a>, and <a href="/en-US/Add-ons/WebExtensions/Your_first_WebExtension">build a basic example</a>.</li> + <li>If your extension is based on XUL and XPCOM, whether it's an <a href="https://developer.mozilla.org/en-US/Add-ons/Overlay_Extensions">overlay extension</a> or a <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/Bootstrapped_extensions">bootstrapped extension</a>, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_XUL_XPCOM_extensions">Comparison with XUL/XPCOM extensions</a> to find out how WebExtensions can correspond with the legacy APIs you're using.</li> + <li>If your extension is based on the Add-on SDK, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK">Comparison with the Add-on SDK</a> to find out how WebExtensions can correspond with the legacy SDK APIs you're using.</li> + </ul> + </li> + <li>Rewrite your extension code. See below for migration paths for different types of extensions. From Firefox 51 onwards, you can embed an extension built using WebExtension APIs in a bootstrapped extension or an SDK add-on, and can thus port a legacy extension a piece at a time, and have a working extension at each step. See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Embedded_WebExtensions">Embedded WebExtensions</a> for more information.</li> + <li>When you're ready to submit the WebExtension version of your extension to AMO... wait a minute... are you truly ready? Because of the extensions permissions model, you cannot revert from WebExtensions back to using a legacy extension format. So test <em>thoroughly</em>, because this is a permanent one-way trip. Also, see the hybrid example below. If you're not ready, you can embed your WebExtension in a legacy extension container, which allows you to test your extension migration but still go back if needed in an emergency.</li> + <li>When you're <em>really</em> ready to submit the WebExtension version of your extension to AMO, first port your old add-on ID to the new WebExtension manifest.json file. Your extension must have the same ID as previous versions. Copy the value in the "id" field from your package.json file into the id field in the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> section of the WebExtension manifest.json file. Then you can submit your extension update to AMO as your normally would.</li> +</ol> + +<div class="note"> +<p>Note that this is a one-way conversion: You <strong>cannot</strong> update an extension using WebExtensions to use a legacy technology. This means that you must be sure that you are ready to commit to using WebExtension APIs before you submit the updated add-on to AMO.</p> +</div> + +<h2 id="Camnihos_de_migração">Camnihos de migração</h2> + +<h3 id="Extensões_SDK">Extensões SDK</h3> + +<p>Here is the comparison chart showing <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK">SDK APIs and their WebExtensions format counterparts</a>. If you don't see the APIs you need to port to use WebExtensions APIs, look below to learn how to request APIs and also how to implement them.</p> + +<h3 id="Extensões_XULXPCOM">Extensões XUL/XPCOM</h3> + +<p>Here is the comparison chart showing <a href="/en-US/Add-ons/WebExtensions/Comparison_with_XUL_XPCOM_extensions">XUL/XPCOM APIs and their WebExtensions format counterparts</a>. If you don't see the APIs you need to port to use WebExtension APIs, look below to learn how to request APIs and also how to implement them.</p> + +<h3 id="Migração_parcial">Migração parcial</h3> + +<p>An <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Embedded_WebExtensions">Embedded WebExtension</a> is an extension that combines two types of extensions in one, by incorporating a WebExtension inside of a bootstrapped or SDK extension. If you have a legacy extension that writes data to the filesystem, and you’re planning to port it to WebExtensions, <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Embedded_WebExtensions">Embedded WebExtensions</a> are available to help you transition. Embedded WebExtensions can be used to transfer the stored data of your add-on to a format that can be used by WebExtensions. This is essential because it lets you to convert your users without the need for them to take any actions.</p> + +<p>It’s important to emphasize that Embedded WebExtensions are intended to be a transition tool, and will not be supported past Firefox 57. They should not be used for add-ons that are not expected to transition to WebExtensions.</p> + +<h2 id="Não_vê_as_APIs_das_Extensões_da_Web_que_precisa">Não vê as APIs das Extensões da Web que precisa?</h2> + +<p><strong>Develop WebExtension APIs for Firefox</strong> - If you're experienced with Mozilla infrastructure and would like to develop WebExtensions APIs directly for Firefox, here is a list of <a href="https://mzl.la/2dVs5Ys">approved APIs</a> that you can start contributing to.</p> + +<p><strong>Experiment with new WebExtension APIs</strong> - If you want to prototype and tinker with WebExtensions APIs without having to build Firefox, <a href="http://webextensions-experiments.readthedocs.io/en/latest/index.html">WebExtensions Experiments</a> is for you!</p> + +<p><strong>Request a new WebExtensions API</strong> - If you want to request a new WebExtensions API, please read <a class="external text" href="https://wiki.mozilla.org/WebExtensions/NewAPIs" rel="nofollow">this page</a>.</p> + +<h2 id="Ferramentas">Ferramentas</h2> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> is a command line tool designed to speed up various parts of the extension development process, making development faster and easier.</li> + <li><a href="https://github.com/mi-g/weh">WebExtensions Helper</a> speeds up browser extension development by providing utilities for WebExtensions-based (Firefox, Chrome, Opera and Edge) extensions</li> + <li><a href="https://github.com/yeoman/generator-chrome-extension">Chrome Extension generator </a>creates everything you need to get started with extension development. You can choose Browser UI(Browser,Page Action, Omnibox) type and select permissions you need.</li> + <li><a href="http://extensionizr.com/">Extensionizr</a> is a wizard that helps you create a basic extension</li> + <li><a href="https://github.com/mahemoff/chrome-boilerplate">Chrome Boilerplate</a> is boilerplate code for Chrome WebE<span class="col-11 mr-2 text-gray-dark">xtension.</span></li> + <li><a href="https://github.com/sitepoint/ChromeSkel_a">Skeleton Chrome Extension</a> is an extension bootstrap and template</li> +</ul> + +<h2 id="Documentação">Documentação</h2> + +<ul> + <li><a href="https://wiki.mozilla.org/Add-ons/developer/communication">WebExtensions Project Page</a> on the Mozilla Wiki</li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions">How-to guides</a> covering common extension developer cases, like <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests">intercepting web requests</a> and <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">adding a button to the toolbar</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK">Comparison with the Add-on SDK</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Comparison_with_XUL_XPCOM_extensions">Comparison with XUL/XPCOM extensions</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">Browser compatibility table</a> for all WebExtensions APIs</li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Examples">Examples of extensions</a></li> +</ul> + +<h2 id="Contactar">Contactar</h2> + +<ul> + <li> + <p>Pode utilizar as hiperligações <a href="https://developer.mozilla.org/pt-PT/docs/Mozilla/Add-ons#Contacte-nos">aqui</a> para obter ajuda, manter-se atualizado com as novidades sobre os extras, e dar-nos a sua opinião.</p> + </li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/dubla_padrões/index.html b/files/pt-pt/mozilla/add-ons/webextensions/dubla_padrões/index.html new file mode 100644 index 0000000000..8c0f5e3480 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/dubla_padrões/index.html @@ -0,0 +1,430 @@ +--- +title: dubla padrões em extensão manifestos +slug: Mozilla/Add-ons/WebExtensions/dubla_padrões +translation_of: Mozilla/Add-ons/WebExtensions/Match_patterns +--- +<div>{{AddonSidebar}}</div> + +<p>Match patterns are a way to specify groups of URLs: a match pattern matches a specific set of URLs. They are used in WebExtensions APIs in a few places, most notably to specify which documents to load <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts</a> into, and to specify which URLs to add <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest">webRequest</a></code> listeners to.</p> + +<p>APIs that use match patterns usually accept a list of match patterns, and will perform the appropriate action if the URL matches any of the patterns. See, for example, the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> key in manifest.json.</p> + +<h2 id="Match_pattern_structure">Match pattern structure</h2> + +<div class="note"> +<p><strong>Note:</strong> Some browsers don’t support certain schemes.<br> + Check the <a href="#Browser_compatibility">Browser compatibility table</a> for details.</p> +</div> + +<p>All match patterns are specified as strings. Apart from the special <code><a href="/en-US/Add-ons/WebExtensions/Match_patterns#%3Call_urls%3E"><all_urls></a></code> pattern, match patterns consist of three parts: <em>scheme</em>, <em>host</em>, and <em>path</em>. The scheme and host are separated by <code>://</code>.</p> + +<pre><scheme>://<host><path></pre> + +<h3 id="scheme">scheme</h3> + +<p>The <em>scheme</em> component may take one of two forms:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 50%;">Form</th> + <th scope="col">Matches</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>*</code></td> + <td>Only "http" and "https" and in some browsers also <a href="/en-US/docs/Web/API/WebSockets_API">"ws" and "wss"</a>.</td> + </tr> + <tr> + <td>One of <code>http</code>, <code>https</code>, <code>ws</code>, <code>wss</code>, <code>ftp</code>, <code>ftps</code>, <code>data</code> or <code>file</code>.</td> + <td>Only the given scheme.</td> + </tr> + </tbody> +</table> + +<h3 id="host">host</h3> + +<p>The <em>host</em> component may take one of three forms:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 50%;">Form</th> + <th scope="col">Matches</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>*</code></td> + <td>Any host.</td> + </tr> + <tr> + <td><code>*.</code> followed by part of the hostname.</td> + <td>The given host and any of its subdomains.</td> + </tr> + <tr> + <td>A complete hostname, without wildcards.</td> + <td>Only the given host.</td> + </tr> + </tbody> +</table> + +<p><em>host</em> must not include a port number.</p> + +<p><em>host</em> is optional only if the <em>scheme</em> is "file".</p> + +<p>Note that the wildcard may only appear at the start.</p> + +<h3 id="path">path</h3> + +<p>The <em>path</em> component must begin with a <code>/</code>.</p> + +<p>After that, it may subsequently contain any combination of the <code>*</code> wildcard and any of the characters that are allowed in URL paths or query strings. Unlike <em>host</em>, the <em>path</em> component may contain the <code>*</code> wildcard in the middle or at the end, and the <code>*</code> wildcard may appear more than once.</p> + +<p>The value for the <em>path</em> matches against the string which is the URL path plus the <a href="https://en.wikipedia.org/wiki/Query_string">URL query string</a>. This includes the <code>?</code> between the two, if the query string is present in the URL. For example, if you want to match URLs on any domain where the URL path ends with <code>foo.bar</code>, then you need to use an array of Match Patterns like <code>['*://*/*foo.bar', '*://*/*foo.bar?*']</code>. The <code>?*</code> is needed, rather than just <code>bar*</code>, in order to anchor the ending <code>*</code> as applying to the URL query string and not some portion of the URL path.</p> + +<p>Neither the <a href="https://en.wikipedia.org/wiki/Fragment_identifier">URL fragment identifier</a>, nor the <code>#</code> which precedes it, are considered as part of the <em>path</em>.</p> + +<div class="blockIndicator note"> +<p><strong>Note</strong>: The path pattern string should not include a port number. Adding a port, as in: <em>"http://localhost:1234/*" </em>causes the match pattern to be ignored. However, "<em>http://localhost:1234</em>" will match with "<em>http://localhost/*</em>"</p> +</div> + +<h3 id="<all_urls>"><all_urls></h3> + +<p>The special value <code><all_urls></code> matches all URLs under any of the supported schemes: that is "http", "https", "ws", "wss", "ftp", "data", and "file".</p> + +<h2 id="Examples">Examples</h2> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col" style="width: 33%;">Pattern</th> + <th scope="col" style="width: 33%;">Example matches</th> + <th scope="col" style="width: 33%;">Example non-matches</th> + </tr> + </thead> + <tbody> + <tr> + <td> + <p><code><all_urls></code></p> + + <p>Match all URLs.</p> + </td> + <td> + <p><code>http://example.org/</code></p> + + <p><code>https://a.org/some/path/</code></p> + + <p><code>ws://sockets.somewhere.org/</code></p> + + <p><code>wss://ws.example.com/stuff/</code></p> + + <p><code>ftp://files.somewhere.org/</code></p> + + <p><code>ftps://files.somewhere.org/</code></p> + </td> + <td> + <p><code>resource://a/b/c/</code><br> + (unsupported scheme)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://*/*</code></p> + + <p>Match all HTTP, HTTPS and WebSocket URLs.</p> + </td> + <td> + <p><code>http://example.org/</code></p> + + <p><code>https://a.org/some/path/</code></p> + + <p><code>ws://sockets.somewhere.org/</code></p> + + <p><code>wss://ws.example.com/stuff/</code></p> + </td> + <td> + <p><code>ftp://ftp.example.org/</code><br> + (unmatched scheme)</p> + + <p><code>ftps://ftp.example.org/</code><br> + (unmatched scheme)</p> + + <p><code>file:///a/</code><br> + (unmatched scheme)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://*.mozilla.org/*</code></p> + + <p>Match all HTTP, HTTPS and WebSocket URLs that are hosted at "mozilla.org" or one of its subdomains.</p> + </td> + <td> + <p><code>http://mozilla.org/</code></p> + + <p><code>https://mozilla.org/</code></p> + + <p><code>http://a.mozilla.org/</code></p> + + <p><code>http://a.b.mozilla.org/</code></p> + + <p><code>https://b.mozilla.org/path/</code></p> + + <p><code>ws://ws.mozilla.org/</code></p> + + <p><code>wss://secure.mozilla.org/something</code></p> + </td> + <td> + <p><code>ftp://mozilla.org/</code><br> + (unmatched scheme)</p> + + <p><code>http://mozilla.com/</code><br> + (unmatched host)</p> + + <p><code>http://firefox.org/</code><br> + (unmatched host)</p> + </td> + </tr> + <tr> + <td> + <p><code>*://mozilla.org/</code></p> + + <p>Match all HTTP, HTTPS and WebSocket URLs that are hosted at exactly "mozilla.org/".</p> + </td> + <td> + <p><code>http://mozilla.org/</code></p> + + <p><code>https://mozilla.org/</code></p> + + <p><code>ws://mozilla.org/</code></p> + + <p><code>wss://mozilla.org/</code></p> + </td> + <td> + <p><code>ftp://mozilla.org/</code><br> + (unmatched scheme)</p> + + <p><code>http://a.mozilla.org/</code><br> + (unmatched host)</p> + + <p><code>http://mozilla.org/a</code><br> + (unmatched path)</p> + </td> + </tr> + <tr> + <td> + <p><code>ftp://mozilla.org/</code></p> + + <p>Match only "ftp://mozilla.org/".</p> + </td> + <td><code>ftp://mozilla.org</code></td> + <td> + <p><code>http://mozilla.org/</code><br> + (unmatched scheme)</p> + + <p><code>ftp://sub.mozilla.org/</code><br> + (unmatched host)</p> + + <p><code>ftp://mozilla.org/path</code><br> + (unmatched path)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://*/path</code></p> + + <p>Match HTTPS URLs on any host, whose path is "path".</p> + </td> + <td> + <p><code>https://mozilla.org/path</code></p> + + <p><code>https://a.mozilla.org/path</code></p> + + <p><code>https://something.com/path</code></p> + </td> + <td> + <p><code>http://mozilla.org/path</code><br> + (unmatched scheme)</p> + + <p><code>https://mozilla.org/path/</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/a</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/path?foo=1</code><br> + (unmatched path due to URL query string)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://*/path/</code></p> + + <p>Match HTTPS URLs on any host, whose path is "path/" and which has no URL query string.</p> + </td> + <td> + <p><code>https://mozilla.org/path/</code></p> + + <p><code>https://a.mozilla.org/path/</code></p> + + <p><code>https://something.com/path</code>/</p> + </td> + <td> + <p><code>http://mozilla.org/path/</code><br> + (unmatched scheme)</p> + + <p><code>https://mozilla.org/path</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/a</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/path/</code><code>?foo=1</code><br> + (unmatched path due to URL query string)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/*</code></p> + + <p>Match HTTPS URLs only at "mozilla.org", with any URL path and URL query string.</p> + </td> + <td> + <p><code>https://mozilla.org/</code></p> + + <p><code>https://mozilla.org/path</code></p> + + <p><code>https://mozilla.org/another</code></p> + + <p><code>https://mozilla.org/path/to/doc</code></p> + + <p><code>https://mozilla.org/path/to/doc?foo=1</code></p> + </td> + <td> + <p><code>http://mozilla.org/path</code><br> + (unmatched scheme)</p> + + <p><code>https://mozilla.com/path</code><br> + (unmatched host)</p> + </td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p>Match only this URL, or this URL with any URL fragment.</p> + </td> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p><code>https://mozilla.org/a/b/c/#section1</code></p> + </td> + <td>Anything else.</td> + </tr> + <tr> + <td> + <p><code>https://mozilla.org/*/b/*/</code></p> + + <p>Match HTTPS URLs hosted on "mozilla.org", whose path contains a component "b" somewhere in the middle. Will match URLs with query strings, if the string ends in a <code>/</code>.</p> + </td> + <td> + <p><code>https://mozilla.org/a/b/c/</code></p> + + <p><code>https://mozilla.org/d/b/f/</code></p> + + <p><code>https://mozilla.org/a/b/c/d/</code></p> + + <p><code>https://mozilla.org/a/b/c/d/#section1</code></p> + + <p><code>https://mozilla.org/a/b/c/d/?foo=/</code></p> + + <p><code>https://mozilla.org/a?foo=21314&bar=/b/&extra=c/</code></p> + </td> + <td> + <p><code>https://mozilla.org/b/*/</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/a/b/</code><br> + (unmatched path)</p> + + <p><code>https://mozilla.org/a/b/c/d/?foo=bar</code><br> + (unmatched path due to URL query string)</p> + </td> + </tr> + <tr> + <td> + <p><code>file:///blah/*</code></p> + + <p>Match any FILE URL whose path begins with "blah".</p> + </td> + <td> + <p><code>file:///blah/</code></p> + + <p><code>file:///blah/bleh</code></p> + </td> + <td><code>file:///bleh/</code><br> + (unmatched path)</td> + </tr> + </tbody> +</table> + +<h3 id="Invalid_match_patterns">Invalid match patterns</h3> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Invalid pattern</th> + <th scope="col">Reason</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>resource://path/</code></td> + <td>Unsupported scheme.</td> + </tr> + <tr> + <td><code>https://mozilla.org</code></td> + <td>No path.</td> + </tr> + <tr> + <td><code>https://mozilla.*.org/</code></td> + <td>"*" in host must be at the start.</td> + </tr> + <tr> + <td><code>https://*zilla.org/</code></td> + <td>"*" in host must be the only character or be followed by ".".</td> + </tr> + <tr> + <td><code>http*://mozilla.org/</code></td> + <td>"*" in scheme must be the only character.</td> + </tr> + <tr> + <td><code>https://mozilla.org:80/</code></td> + <td>Host must not include a port number.</td> + </tr> + <tr> + <td><code>*://*</code></td> + <td>Empty path: this should be "<code>*://*/*</code>".</td> + </tr> + <tr> + <td><code>file://*</code></td> + <td>Empty path: this should be "<code>file:///*</code>".</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<h3 id="scheme_2">scheme</h3> + + + +<p>{{Compat("webextensions.match_patterns.scheme",10)}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/e_a_seguir/index.html b/files/pt-pt/mozilla/add-ons/webextensions/e_a_seguir/index.html new file mode 100644 index 0000000000..f16f7e619b --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/e_a_seguir/index.html @@ -0,0 +1,60 @@ +--- +title: E a seguir? +slug: Mozilla/Add-ons/WebExtensions/E_a_seguir +tags: + - Extensão da Web + - Extensões + - Principiante +translation_of: Mozilla/Add-ons/WebExtensions/What_next_ +--- +<div>{{AddonSidebar}}</div> + +<p>Agora, irá estar pronto para começar a transformar a sua ideia de uma extensão de navegador em realidade. Antes de começar essa jornada, vale a pena estar ciente de algumas coisas que irão ajudar a facilitar.</p> + +<h2 id="O_seu_ambiente_de_desenvolvimento">O seu ambiente de desenvolvimento</h2> + +<p>You don't need any special development or build environment tools to create browser extensions: It's entirely possible to create great browser extensions with no more than a text editor. However, you may have been developing for the web and have a set of tools and an environment you want to reuse. If you do, you need to be aware of a couple of things.</p> + +<p>If you use minification or obfuscation tools to deliver your final code, you’ll need to provide your source code to <a href="#The_review_process">the AMO review process</a>. Also, the tools you use—those for minification, obfuscation, and build processes—will need to be open source (or offer unlimited free use) and be available to run on the reviewer’s computer (Windows, Mac, or Linux). Unfortunately, our reviewers can't work with commercial or web-based tools.</p> + +<p><a href="/en-US/Add-ons/Source_Code_Submission#About_build_tools">Learn more about build tools</a></p> + +<h2 id="Bibliotecas_de_terceiros">Bibliotecas de terceiros</h2> + +<p>Third-party libraries are a great way to add complex features or functionality to your browser extensions quickly. When you submit an extension to the <a href="#The_review_processv">AMO review process</a>, the process will also consider any third-party libraries used. To streamline the review, make sure you always download third-party libraries from their official website or repository, and if the library is minified provide a link to the source code. Please note that third-party libraries cannot be modified in any way.</p> + +<p><a href="/en-US/Add-ons/Source_Code_Submission">Learn more about submitting source code</a></p> + +<h2 id="O_Acordo_de_Distribuição_do_Extra_do_Firefox">O Acordo de Distribuição do Extra do Firefox</h2> + +<p>Browser extensions need to be signed to install into the release or beta versions of Firefox. Signing takes place in addons.mozilla.org (AMO) and is subject to the terms and conditions of the Firefox Add-on Distribution Agreement. The goal of the agreement is to ensure Firefox users get access to well supported, quality add-ons that enhance the Firefox experience.</p> + +<p><a href="/pt-PT/docs/Mozilla/Add-ons/AMO/Policy/Agreement">Leia o acordo</a></p> + +<p><a href="/en-US/Add-ons/WebExtensions/Distribution">Learn more about signing</a></p> + +<h2 id="O_processo_de_revisão">O processo de revisão</h2> + +<p>When a browser extension is submitted for signing, it's subject to automated review. It may also be subject to a manual review, when the automated review determines that a manual review is needed. Your browser extension won't be signed until it’s passed the automated review and may have its signing revoked if it fails to pass the manual review. The review process follows a strict set of guidelines, so it’s easy to check and avoid any likely review problems.</p> + +<p><a href="/en-US/Add-ons/AMO/Policy/Reviews">Check out the review policy and guidelines</a></p> + +<h2 id="Extensões_do_navegador_em_destaque_no_AMO">Extensões do navegador em destaque no AMO</h2> + +<p>If you choose to list your browser extension on AMO, your extension could be featured on the AMO website, in the Firefox browser’s add-on manager, or elsewhere on a Mozilla website. We've compiled a list of guidelines about how extensions are selected for featuring, by following these guidelines you give your extension the best chance of being featured.</p> + +<p><a href="/pt-PT/docs/Mozilla/Add-ons/AMO/Policy/Em_destaque">Saiba mais sobre como colocar os seus extras em destaque</a></p> + +<h2 id="Continue_a_sua_experiência_de_aprendizagem">Continue a sua experiência de aprendizagem</h2> + +<p>Now you know what lies ahead, it's time to dive into more details about browser extension development. In the sections that follow, you’ll discover:</p> + +<ul> + <li>More about the fundamental concepts behind browser extensions, starting with details on how to <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Using_the_JavaScript_APIs">use the JavaScript APIs</a>.</li> + <li>A guide to the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface">user interface components</a> available to your browser extensions.</li> + <li>A collection of how-to guides on achieving key tasks in your extensions or making use of the JavaScript APIs.</li> + <li>Information on how to port other browser extensions to Firefox.</li> + <li>Details about the Firefox specific workflows you can use to develop browser extensions.</li> + <li>A full reference guide to the JavaScript APIs.</li> + <li>A full reference guide to the Manifest keys.</li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/exemplos_extensoes/index.html b/files/pt-pt/mozilla/add-ons/webextensions/exemplos_extensoes/index.html new file mode 100644 index 0000000000..4a68068c6a --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/exemplos_extensoes/index.html @@ -0,0 +1,28 @@ +--- +title: Exemplos de extensões +slug: Mozilla/Add-ons/WebExtensions/Exemplos_extensoes +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Examples +--- +<div>{{AddonSidebar}}</div> + +<p>Para ajudar a ilustrar como desenvolver extensões, nós mantemos um repositório de exemplos de extensões simples em <a href="https://github.com/mdn/webextensions-examples">https://github.com/mdn/webextensions-examples</a>. Este artigo descreve as APIs de Extensão da Web utilizadas nesse repositório.</p> + +<p>Estes exemplos funcionam no Firefox Nightly: a maioria funciona nas versões anteriores do Firefox, mas verifique a chave <a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">strict_min_version</a> em manifest.json da extensão para se certificar.</p> + +<p>Se quiser experimentar estes exemplos, tem três opções principais:</p> + +<ol> + <li>Clone o repositório, depois carregue a extensão diretamente da sua diretoria fonte, utilizando a funcionalidade <a href="/pt-PT/Add-ons/WebExtensions/Instalacao_temporaria_no_Firefox">"Carregar Temporariamente os Extras"</a>. A extensão permanecerá carregada até que reinicie o Firefox.</li> + <li>Clone o repositório, depois utilize a ferramenta de linha de comando <a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Primeiros_passos_com_web-ext">web-ext</a> para executar o Firefox com a extensão instalada.</li> + <li>Clone o repositório, depois vá para a diretoria de <em><a href="https://github.com/mdn/webextensions-examples/tree/master/build">build</a></em>. Esta contém as versões criadas e assinadas de todos os exemplos, e assim pode abri-las no Firefox (utilizando Ficheiro/Abrir Ficheiro) e instale-as permanentemente, tal como uma extensão que instalaria a partir de <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a>.</li> +</ol> + +<div class="warning"> +<p><strong>Importante</strong>: Por favor, não submeta estes exemplos dos exemplos da 'Extensão da Web' para AMO (addons.mozilla.org), não precisa de assinar o extra para executar os exemplos da 'Extensão da Web'. Basta seguir os passos acima.</p> +</div> + +<p>Se desejar contribuir para o repositório, <a href="https://github.com/mdn/webextensions-examples/blob/master/CONTRIBUTING.md">envie-nos um pedido de submissão!</a></p> + +<p>{{WebExtAllExamples}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/extennsoesweb_e_a_id_do_extra/index.html b/files/pt-pt/mozilla/add-ons/webextensions/extennsoesweb_e_a_id_do_extra/index.html new file mode 100644 index 0000000000..a462a1c02d --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/extennsoesweb_e_a_id_do_extra/index.html @@ -0,0 +1,78 @@ +--- +title: Extensões e a Id. do extra +slug: Mozilla/Add-ons/WebExtensions/ExtennsoesWeb_e_a_id_do_extra +tags: + - Extensões da Web + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID +--- +<div>{{AddonSidebar}}</div> + +<div class="summary"> +<p>Os extras do Firefox contêm uma Id. única que é utilziada para distinguir este extra de qualquer outro extra do Firefox.</p> + +<p>Este artigo descreve como as Ids. de extra são tratados para as extensões criadas com APIs WebExtensions.</p> +</div> + +<p>Firefox add-ons contain a unique identifier which is used both inside Firefox itself and on the <a href="https://addons.mozilla.org/">addons.mozilla.org</a> (AMO) website. For example, it's used by Firefox to check for updates to installed add-ons and to identify which objects (such as data stores) are controlled by this add-on.</p> + +<p>With older types of Firefox add-on, the add-on developer must set the add-on ID explicitly. XUL/XPCOM add-ons set the ID in the <a href="/en-US/docs/Mozilla/Add-ons/Install_Manifests">install manifest</a>, while SDK add-ons set it in the <a href="/en-US/docs/Mozilla/Add-ons/SDK/Tools/package_json">package.json</a>.</p> + +<p>However, from Firefox 48 you can develop, debug, publish, and update extensions without needing to set an explicit ID at all.</p> + +<div class="note"> +<p>Note that the ability to develop and debug WebExtensions that don't include an ID is new in Firefox 48. If you need to use an earlier version of Firefox, then you must use the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> key to set an ID explicitly.</p> +</div> + +<h2 id="Basic_workflow_with_no_add-on_ID">Basic workflow with no add-on ID</h2> + +<p>Extensions can explicitly set the add-on ID using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> key in manifest.json. However, this key is usually optional. If you don't set it, then you can usually develop, debug, publish, and update your extension without ever having to deal with an ID. One advantage of this is that Google Chrome does not recognize the <code>applications</code> key and will show a warning if you include it.</p> + +<p>Note, though, that some WebExtension APIs use the add-on ID and expect it to be the same from one browser session to the next. If you use these APIs in Firefox, then you must set the ID explicitly using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> key. See <a href="/en-US/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID#When_do_you_need_an_add-on_ID">When do you need an Add-on ID?</a>.</p> + +<h3 id="Developing_and_debugging">Developing and debugging</h3> + +<p>Starting in Firefox 48, if your manifest.json does not contain an ID then the extension will be assigned a randomly-generated temporary ID when you <a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">install it in Firefox</a> through about:debugging. If you then reload the extension using the "Reload" button, the same ID will be used. If you then restart Firefox and load the add-on again, it will get a new ID.</p> + +<p>If you turn the extension into an .xpi or .zip and install it through about:addons, it will not work. To have it work in this scenario, you will need to add in the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> key in manifest.json</p> + +<h3 id="Publishing">Publishing</h3> + +<p>Once you have finished developing the extension, you can <a href="/en-US/Add-ons/WebExtensions/Publishing_your_WebExtension">package it and submit it to AMO for review and signing</a>. If the packaged extension you upload does not contain an ID, AMO will generate one for you. It's only at this point that the add-on will be assigned a permanent ID, which will be embedded in the signed packaged extension.</p> + +<p>Note that once an extension has been given a permanent ID, you can't then update it to use the Add-on SDK or legacy XUL/XPCOM techniques. If you do switch to one of these platforms, you must submit it as a distinct new add-on, with a new ID.</p> + +<h3 id="Updating">Updating</h3> + +<p>Even after this point, though, you don't generally have to deal with the ID at all. You can continue to develop the add-on without an ID, and when you want to update, upload the new version by visiting the add-on's AMO page. Because you are uploading the add-on through that page, AMO knows that this is an update to this particular add-on, even though it doesn't contain an ID.</p> + +<div class="note"> +<p>It's essential with this workflow that you update the add-on <em>manually using its page on AMO</em>, otherwise AMO will not understand that the submission is an update to an existing add-on, and will treat the update as a brand-new add-on.</p> +</div> + +<p>You can do the same thing if you are updating from an older add-on type, such as a XUL/XPCOM add-on, to use WebExtensions APIs. Just visit the old add-on's page on AMO, upload the new extension there, and it will be treated as an update to the old version.</p> + +<h2 id="Quando_é_que_precisa_de_uma_Id._de_extra">Quando é que precisa de uma Id. de extra?</h2> + +<ul> + <li>If you are loading the add-on from its XPI file, are not loading it temporarily using about:debugging and it is not signed.</li> + <li>If you use <a href="https://addons-server.readthedocs.io/en/latest/topics/api/signing.html">AMO's API</a> for uploading your add-on, rather than uploading it manually on its page, then you need to include the add-on's ID in the request.</li> + <li>Some WebExtension APIs use the add-on ID and expect it to be the same from one browser session to the next. If you use these APIs, then you must set the ID explicitly using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> key. This applies to the following APIs: + <ul> + <li>{{WebExtAPIRef("storage.managed")}}</li> + <li>{{WebExtAPIRef("storage.sync")}}</li> + <li>{{WebExtAPIRef("identity.getRedirectURL")}}</li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging">Native messaging</a></li> + <li>{{WebExtAPIRef("pkcs11")}}</li> + <li>{{WebExtAPIRef("runtime.onMessageExternal")}}</li> + <li>{{WebExtAPIRef("runtime.onConnectExternal")}}</li> + </ul> + </li> + <li>Using Firefox for Android. See <a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">applications in manifest.json</a>.</li> +</ul> + +<p> </p> + +<p> </p> + +<p> </p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/extensão_das_ferramentas_de_desenvolvimento/index.html b/files/pt-pt/mozilla/add-ons/webextensions/extensão_das_ferramentas_de_desenvolvimento/index.html new file mode 100644 index 0000000000..dc98e7fd37 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/extensão_das_ferramentas_de_desenvolvimento/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> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/index.html b/files/pt-pt/mozilla/add-ons/webextensions/index.html new file mode 100644 index 0000000000..4c894e2cf1 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/index.html @@ -0,0 +1,135 @@ +--- +title: Extensões de Navegador +slug: Mozilla/Add-ons/WebExtensions +tags: + - Extensões da Web + - Extras + - Landing +translation_of: Mozilla/Add-ons/WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<p>As extensões podem ampliar e modificar a capacidade de um navegador. As extensões para Firefox são criadas utilizando a API de WebExtensions, um sistema de navegador cruzado para desenvolver extensões. Em grande medida, o sistema é compatível com a <a class="external-icon external" href="https://developer.chrome.com/extensions">API de extensão</a> suportada pelo Google Chrome, Opera e <a href="https://browserext.github.io/browserext/">W3C Draft Community Group</a>.</p> + +<p>As extensões escritas para estes navegadores irão na maioria dos casos ser executadas no Firefox ou <a href="https://docs.microsoft.com/pt-pt/microsoft-edge/extensions">Microsoft Edge</a> com <a href="/pt-PT/Add-ons/WebExtensions/Trasnsferir_extensao_Google_Chrome">apenas algumas alterações</a>. A API também é totalmente compatível com <a href="/pt-PT/Firefox/Multiprocess_Firefox">os multiprocessos do Firefox</a>.</p> + +<p>Se tiver ideias ou questões, ou precisar de ajuda para migrar um extra legado para utilizar as APIs de WebExtensions, pode contactar-nos em <a href="https://mail.mozilla.org/listinfo/dev-addons">lista de discussões dev-addons</a> ou <a href="irc://irc.mozilla.org/webextensions">#webextensions</a> no <a href="https://wiki.mozilla.org/IRC">IRC</a></p> + +<div class="row topicpage-table"> +<div class="section"> +<h2 id="Começar">Começar</h2> + +<ul> + <li><a href="/pt-PT/Add-ons/WebExtensions/O_que_sao_WebExtensions">O que são extensões?</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/A_sua_primeira_extensao">A sua primeira extensão</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/A_sua_segunda_extensao">A sua seguna extensão</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/Anatomia_de_uma_extensao">Anatomia de uma extensã</a>o</li> + <li><a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Exemplos_extensoes">Exemplos de Extensões</a></li> + <li><a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/E_a_seguir">E a seguir?</a></li> +</ul> + +<h2 id="Conceitos">Conceitos</h2> + +<ul> + <li><a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/API">Resumo da API de JavaScript</a></li> + <li><a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Scripts_Conteudo">Scripts de Conteúdo</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Match_patterns">Match patterns</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_files">Working with files</a></li> + <li><a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Internationalization">Internationalização</a> (Tradução)</li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Security_best_practices">Security best practices</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging">Native messaging</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Using_the_devtools_APIs">Using the devtools APIs</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/User_experience_best_practices">User experience best practices</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Native_manifests">Native manifests</a></li> +</ul> + +<h2 id="Interface_do_utilizador">Interface do utilizador</h2> + +<ul> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador">Introdução</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Ação_navegador">Botão da barra de ferramentas do navegador</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Popups">Botão da barra de ferramentas do navegador com uma janela (<em>popup</em>)</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Acoes_pagina">Botão da barra de endereço</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Popups">Botão da barra de endereço com uma janela (<em>popup</em>)</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Itens_do_menu_de_contexto">Itens do menu de contexto</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Barras_laterais">Barras laterais</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Options_pages">Página de opções</a></li> + <li><a href="https://developer.mozilla.org/pt-PT/docs/Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Paginas_de_extens%C3%A3o">Páginas de extensão</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Notificacoes">Notificações</a></li> + <li><a href="https://developer.mozilla.org/pt-PT/docs/Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Omnibox">Sugestões da barra de endereço</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/devtools_panels">Painés das ferramentas de desenvolvimento</a></li> + <li><a href="https://developer.mozilla.org/pt-PT/docs/Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Estilos_de_navegador">Estilos de navegador</a></li> +</ul> + +<h2 id="Como...">Como...</h2> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests">Intercept HTTP requests</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Modify_a_web_page">Modify a web page</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">Add a button to the toolbar</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page">Implement a settings page</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard">Interact with the clipboard</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_the_Tabs_API">Work with the Tabs API</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_the_Bookmarks_API">Work with the Bookmarks API</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_the_Cookies_API">Work with the Cookies API</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities">Work with contextual identities</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Safely_inserting_external_content_into_a_page">Insert external content</a></li> +</ul> + +<ul> +</ul> + +<h2 id="Porting">Porting</h2> + +<ul> + <li><a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Trasnsferir_extensao_Google_Chrome">Conversão de uma extensão do Google Chrome</a></li> + <li><a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Conversao_de_uma_extensao_legada_do_firefox">Conversão de uma extensão legada do Firefox</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android">Developing for Firefox for Android</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Embedded_WebExtensions">Embedded WebExtensions</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK">Comparison with the Add-on SDK</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_XUL_XPCOM_extensions">Comparison with XUL/XPCOM extensions</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities">Chrome incompatibilities</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Differences_between_desktop_and_Android">Differences between desktop and Android</a></li> +</ul> + +<h2 id="Fluxo_de_trabalho_do_Firefox">Fluxo de trabalho do Firefox</h2> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/User_experience_best_practices">User experience</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">Installation</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Debugging">Debugging</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Testing_persistent_and_restart_features">Testing persistent and restart features</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">Getting started with web-ext</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/web-ext_command_reference">web-ext command reference</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">Extensions and the Add-on ID</a></li> + <li><a href="/en-US/Add-ons/WebExtensions/Alternative_distribution_options">Alternative distribution options</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Request_the_right_permissions">Request the right permissions</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts">Sharing objects with page scripts</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Retiring_your_extension">Retiring your extension</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Tips">Tips and Tricks</a></li> +</ul> +</div> + +<div class="section"> +<h2 id="Referência">Referência</h2> + +<h3 id="APIS_de_JavaScript">APIS de JavaScript</h3> + +<ul> + <li><a href="/pt-PT/Add-ons/WebExtensions/API">Sinopse de API de JavaScript API</a></li> + <li><a href="/pt-PT/Add-ons/WebExtensions/Suporte_navegador_APIs_JavaScript">Tabelas de compatibilidade de navegador para as APIs de JavaScript</a></li> +</ul> + +<div class="twocolumns">{{ ListSubpages ("/en-US/Add-ons/WebExtensions/API") }}</div> + +<h3 id="idManifest_keys>Manifest_keys">id="Manifest_keys">Manifest keys</h3> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json overview</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json">Browser compatibility for manifest.json</a></li> +</ul> + +<div class="twocolumns">{{ ListSubpages ("/en-US/Add-ons/WebExtensions/manifest.json") }}</div> +</div> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/instalacao_temporaria_no_firefox/index.html b/files/pt-pt/mozilla/add-ons/webextensions/instalacao_temporaria_no_firefox/index.html new file mode 100644 index 0000000000..47730abceb --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/instalacao_temporaria_no_firefox/index.html @@ -0,0 +1,50 @@ +--- +title: Instalação temporária no Firefox +slug: Mozilla/Add-ons/WebExtensions/Instalacao_temporaria_no_Firefox +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Temporary_Installation_in_Firefox +--- +<div>{{AddonSidebar}}</div> + +<p>Este artigo descreve como um programador de extra (add-on) pode instalar temporariamente uma extensão no Firefox para testes e depuração. A extensão permanecerá instalada até que reinicie o Firefox. Pode utilizar este método com qualquer tipo de extensão sem reinício, incluindo as <a href="/pt-PT/docs/Archive/Add-ons/Extensoes_bootstrapped">extensões bootstrapped</a> e <a href="/pt-PT/Add-ons/SDK">extras de Add-on SDK</a>.</p> + +<p>Note that this is <em>not</em> how end users should install add-ons in Firefox. End users will install add-ons by downloading and opening packaged add-ons that have been signed by Mozilla. To learn how an extension developer can get an add-on packaged and signed, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension">Publishing your extension</a>.</p> + +<p>To install an extension temporarily:</p> + +<ul> + <li>open Firefox</li> + <li>enter "about:debugging" in the URL bar</li> + <li>click "Load Temporary Add-on"</li> + <li>open the extension's directory and select any file inside the extension.</li> +</ul> + +<p>The extension will be installed, and will stay installed until you restart Firefox.</p> + +<p>{{EmbedYouTube("cer9EUKegG4")}}</p> + +<h2 id="Recarregar_uma_extensão_temporária">Recarregar uma extensão temporária</h2> + +<p>Starting in Firefox 48, there's a new button labeled "Reload" next to the extension's entry in about:debugging:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13462/reload.png" style="display: block; height: 544px; margin-left: auto; margin-right: auto; width: 848px;">This does what it says:</p> + +<ul> + <li>reloading any persistent scripts, such as <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background scripts</a></li> + <li>parsing the <code>manifest.json</code> file again, so changes to <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> or any other keys will take effect.</li> +</ul> + +<p>{{EmbedYouTube("NuajE60jfGY")}}</p> + +<div class="note"> +<p>Note that in Firefox 48 only, "Reload" does not update the extension's name and description that are displayed in about:debugging and about:addons. This is fixed in Firefox 49.</p> +</div> + +<h2 id="Utilizar_a_linha_de_comando">Utilizar a linha de comando</h2> + +<p>If you are already using the command line for development, check out the <a href="/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> tool. It automates the temporary installation step and automatically reloads your extension when its source code changes.</p> + +<h2 id="Detetar_instalaçao_temporária">Detetar instalaçao temporária</h2> + +<p>Your extension can detect whether it was installed from about:debugging rather than as a built and signed extension downloaded from <a href="https://addons.mozilla.org">addons.mozilla.org</a>. Listen for the {{WebExtAPIRef("runtime.onInstalled")}} event, and check the value of <code>details.temporary</code>.</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interceptar_pedidos_http/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interceptar_pedidos_http/index.html new file mode 100644 index 0000000000..b938b514d4 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interceptar_pedidos_http/index.html @@ -0,0 +1,160 @@ +--- +title: Interceptar Pedidos HTTP +slug: Mozilla/Add-ons/WebExtensions/Interceptar_Pedidos_HTTP +tags: + - Add-ons + - Como-fazer + - Extensões + - ExtensõesWeb +translation_of: Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests +--- +<div>{{AddonSidebar}}</div> + +<p>Para interceptar pedidos HTTP, use a {{WebExtAPIRef("webRequest")}} API. Esta API permite que você adicione ouvintes para várias etapas ao fazer uma solicitação HTTP. Nos ouvintes, você pode:</p> + +<ul> + <li>obter acesso para solicitar cabeçalhos e corpos e cabeçalhos de resposta.</li> + <li>pedidos de cancelamento e redirecionamento</li> + <li>modificar pedidos e cabeçalhos de resposta</li> +</ul> + +<p>Neste articulo nós vamos dar uma olhada a tres usos diferentes para o modulo <code>webRequest</code>:</p> + +<ul> + <li>Logar pedidos URLs quando eles são feitos.</li> + <li>Redirecionar pedidos.</li> + <li>Modificar cabeçalhos de pedidos.</li> +</ul> + +<h2 id="Loggar_pedidos_URLs">Loggar pedidos URLs</h2> + +<p>Crie um diretorio chamado "requests". Nesse diretorio crie um ficheiro chamado "manifest.json" com o seguinte conteudo:</p> + +<pre class="brush: json">{ + "description": "Demonstração webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest", + "<all_urls>" + ], + + "background": { + "scripts": ["background.js"] + } +}</pre> + +<p>De seguida, crie um ficheiro chamado "background.js" com o seguinte conteudo:</p> + +<pre class="brush: js">function logURL(requestDetails) { + console.log("A carregar: " + requestDetails.url); +} + +browser.webRequest.onBeforeRequest.addListener( + logURL, + {urls: ["<all_urls>"]} +); + +</pre> + +<p>Here we use {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} to call the <code>logURL()</code> function just before starting the request. The <code>logURL()</code> function grabs the URL of the request from the event object and logs it to the browser console. The <code>{urls: ["<all_urls>"]}</code> <a href="/en-US/Add-ons/WebExtensions/Match_patterns">pattern</a> means we will intercept HTTP requests to all URLs.</p> + +<p>To test it out, <a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">install the extension</a>, <a href="/en-US/docs/Tools/Browser_Console">open the Browser Console</a>, and open some Web pages. In the Browser Console, you should see the URLs for any resources that the browser requests:</p> + +<p>{{EmbedYouTube("X3rMgkRkB1Q")}}</p> + +<h2 id="Redirecting_requests">Redirecting requests</h2> + +<p>Now let's use <code>webRequest</code> to redirect HTTP requests. First, replace manifest.json with this:</p> + +<pre class="brush: json">{ + + "description": "Demonstrating webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest", + "webRequestBlocking", + "https://developer.mozilla.org/", + "https://mdn.mozillademos.org/" + ], + + "background": { + "scripts": ["background.js"] + } + +}</pre> + +<p>The only change here is to add the <code>"webRequestBlocking"</code> <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a></code>. We need to ask for this extra permission whenever we are actively modifying a request.</p> + +<p>Next, replace "background.js" with this:</p> + +<pre class="brush: js">var pattern = "https://mdn.mozillademos.org/*"; + +function redirect(requestDetails) { + console.log("Redirecting: " + requestDetails.url); + return { + redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif" + }; +} + +browser.webRequest.onBeforeRequest.addListener( + redirect, + {urls:[pattern], types:["image"]}, + ["blocking"] +);</pre> + +<p>Again, we use the {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} event listener to run a function just before each request is made. This function will replace the target URL with the <code>redirectUrl</code> specified in the function.</p> + +<p>This time we are not intercepting every request: the <code>{urls:[pattern], types:["image"]}</code> option specifies that we should only intercept requests (1) to URLs residing under "https://mdn.mozillademos.org/" (2) for image resources. See {{WebExtAPIRef("webRequest.RequestFilter")}} for more on this.</p> + +<p>Also note that we're passing an option called <code>"blocking"</code>: we need to pass this whenever we want to modify the request. It makes the listener function block the network request, so the browser waits for the listener to return before continuing. See the {{WebExtAPIRef("webRequest.onBeforeRequest")}} documentation for more on <code>"blocking"</code>.</p> + +<p>To test it out, open a page on MDN that contains a lot of images (for example <a href="https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor">https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor</a>), <a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox#Reloading_a_temporary_add-on">reload the extension</a>, and then reload the MDN page:</p> + +<p>{{EmbedYouTube("ix5RrXGr0wA")}}</p> + +<h2 id="Modifying_request_headers">Modifying request headers</h2> + +<p>Finally we'll use <code>webRequest</code> to modify request headers. In this example we'll modify the "User-Agent" header so the browser identifies itself as Opera 12.16, but only when visiting pages under http://useragentstring.com/".</p> + +<p>The "manifest.json" can stay the same as in the previous example.</p> + +<p>Replace "background.js" with code like this:</p> + +<pre class="brush: js">var targetPage = "http://useragentstring.com/*"; + +var ua = "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12.16"; + +function rewriteUserAgentHeader(e) { + for (var header of e.requestHeaders) { + if (header.name.toLowerCase() == "user-agent") { + header.value = ua; + } + } + return {requestHeaders: e.requestHeaders}; +} + +browser.webRequest.onBeforeSendHeaders.addListener( + rewriteUserAgentHeader, + {urls: [targetPage]}, + ["blocking", "requestHeaders"] +);</pre> + +<p>Here we use the {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}} event listener to run a function just before the request headers are sent.</p> + +<p>The listener function will be called only for requests to URLs matching the <code>targetPage</code> <a href="/en-US/Add-ons/WebExtensions/Match_patterns">pattern</a>. Also note that we've again passed <code>"blocking"</code> as an option. We've also passed <code>"requestHeaders"</code>, which means that the listener will be passed an array containing the request headers that we expect to send. See {{WebExtAPIRef("webRequest.onBeforeSendHeaders")}} for more information on these options.</p> + +<p>The listener function looks for the "User-Agent" header in the array of request headers, replaces its value with the value of the <code>ua</code> variable, and returns the modified array. This modified array will now be sent to the server.</p> + +<p>To test it out, open <a href="http://useragentstring.com/">useragentstring.com</a> and check that it identifies the browser as Firefox. Then reload the extension, reload <a href="http://useragentstring.com/">useragentstring.com</a>, and check that Firefox is now identified as Opera:</p> + +<p>{{EmbedYouTube("SrSNS1-FIx0")}}</p> + +<h2 id="Learn_more">Learn more</h2> + +<p>To learn about all the things you can do with the <code>webRequest</code> API, see its <a href="/en-US/Add-ons/WebExtensions/API/WebRequest">reference documentation</a>.</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/acoes_pagina/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/acoes_pagina/index.html new file mode 100644 index 0000000000..7093d3355c --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/acoes_pagina/index.html @@ -0,0 +1,50 @@ +--- +title: Botão da barra de endereço +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Acoes_pagina +tags: + - Extensões da Web + - Interface do Utilizador +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +--- +<div>{{AddonSidebar}}</div> + +<p>Normalmente referido como uma <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">ação da página</a>, esta opção da inteface do utilizador é um botão adicionado à barra de endereço do navegador. Os utilziadores clicam no botão para interagir com a sua extensão.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/12960/page-action.png" style="display: block; height: 262px; margin-left: auto; margin-right: auto; width: 850px;"></p> + +<p>Use this button when a feature is only relevant for some web pages. By default, the address bar button is hidden in all browser tabs, and you call <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/PageAction/show" title="Shows the page action for a given tab. The page action is shown whenever the given tab is the active tab."><code>pageAction.show()</code></a> and <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/PageAction/hide" title="Hides the page action for a given tab."><code>pageAction.hide()</code></a> to show or hide it in specific tabs.</p> + +<p>Compare to the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_action">toolbar button</a>, which offers similar behavior but is used in situations where the extension's features are applicable to almost every web page.</p> + +<h2 id="Especificar_a_ação_da_página">Especificar a ação da página</h2> + +<p>You define the page action's properties using the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code> key in manifest.json:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"page_action":</span> <span class="punctuation token">{</span> + <span class="key token">"browser_style":</span> <span class="keyword token">true</span><span class="punctuation token">,</span> + <span class="key token">"default_icon":</span> <span class="punctuation token">{</span> + <span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span> + <span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span> +<span class="punctuation token">}</span></code></pre> + +<p>The only mandatory key is <code>default_icon</code>.</p> + +<p>There are two ways to specify a page action: with or without a <a href="/en-US/Add-ons/WebExtensions/Popups">popup</a>. If you don't specify a popup, when the user clicks the button an event is dispatched to the extension, which the extension listens for using <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction/onClicked" title="Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup."><code>pageAction.onClicked</code></a>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>pageAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>If you specify a popup, the click event is not dispatched: instead, the popup is shown when the user clicks the button. The user is able to interact with the popup and it closes automatically when the user clicks outside it. See the <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Popups">Popup </a>article for more details on creating and managing popups.</p> + +<p>Note that your extension can have one page action only.</p> + +<p>You can change any of the page action properties programmatically using the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">pageAction</a></code> API.</p> + +<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 page action:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/chill-out">chill-out</a> uses a page action without a popup.</li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/ação_navegador/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/ação_navegador/index.html new file mode 100644 index 0000000000..c5da78003b --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/ação_navegador/index.html @@ -0,0 +1,50 @@ +--- +title: Botão da Barra de Ferramentas +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Ação_navegador +tags: + - Extensão da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +--- +<div>{{AddonSidebar}}</div> + +<p>Normalmente referido como uma <a href="/pt-PT/Add-ons/WebExtensions/API/browserAction">ação do navegador</a>, esta opção da interface do utilizador é um botão adicionado à barra de ferramentas do navegador. Os utilizadores clicam no botão para interagir com a sua extensão.<br> + <img alt="" src="https://mdn.mozillademos.org/files/15751/browser-action.png" style="display: block; height: 182px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>The toolbar button (browser action) is very like the address bar button (page action). For the differences, and guidance on when to use what, see <a href="/en-US/Add-ons/WebExtensions/user_interface/Page_actions#Page_actions_and_browser_actions">Page actions and browser actions</a>.</p> + +<h2 id="Especificar_a_ação_do_navegador">Especificar a ação do navegador</h2> + +<p>Define as propriedades da ação do navegador utilizando a chave <code><a href="/pt-PT/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> em manifest.json:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"browser_action":</span> <span class="punctuation token">{</span> + <span class="key token">"default_icon":</span> <span class="punctuation token">{</span> + <span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span> + <span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span> + <span class="punctuation token">}</span><span class="punctuation token">,</span> + <span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span> +<span class="punctuation token">}</span></code></pre> + +<p>The only mandatory key is <code>default_icon</code>.</p> + +<p>There are two ways to specify a browser action: with or without a <a href="/en-US/Add-ons/WebExtensions/Popups">popup</a>. If you don't specify a popup, when the user clicks the button an event is dispatched to the extension, which the extension listens for using <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/BrowserAction/onClicked" title="Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup."><code>browserAction.onClicked</code></a>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>browserAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>If you specify a popup, the click event is not dispatched: instead, the popup is shown when the user clicks the button. The user is able to interact with the popup and it closes automatically when the user clicks outside it. See the <a href="/en-US/Add-ons/WebExtensions/Popups">Popup </a>article for more details on creating and managing popups.</p> + +<p>Note that your extension can have only one browser action.</p> + +<p>You can change any of the browser action properties programmatically using the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> API.</p> + +<h2 id="Ícones">Ícones</h2> + +<p>For details on how to create icons to use with your browser action, see <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a> in the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Exemplos">Exemplos</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository on GitHub contains two examples of extensions that implement browser actions:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/blob/master/bookmark-it/">bookmark-it</a> uses a browser action without a popup.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> uses a browser action with a popup.</li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/barras_laterais/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/barras_laterais/index.html new file mode 100644 index 0000000000..2cfa1800a7 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/barras_laterais/index.html @@ -0,0 +1,57 @@ +--- +title: Barras laterais +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Barras_laterais +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +--- +<div>{{AddonSidebar}}</div> + +<div> +<p> </p> + +<p>Uma barra lateral é um painel que é exibido no lado esquerdo da janela do navegador, ao lado da página da Web. O navegador fornece uma IU que permite ao utilizador ver as barras laterais atualmente disponíveis e selecionar uma barra lateral para exibir. Por exemplo, o Firefox tem um menu 'Ver -> Barra lateral'. Apenas pode ser exibida uma barra lateral de cada vez, e essa barra lateral será exibida para todos os separadores e todas as janelas do navegador.</p> + +<p>O navegador poderá incluir uma série de barras laterais integradas. Por exemplo, o Firefox inclui uma barra lateral para interagir com marcadores:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14825/bookmarks-sidebar.png" style="display: block; height: 761px; margin-left: auto; margin-right: auto; width: 728px;">Using the <code>sidebar_action</code> manifest.json key, an extension can add its own sidebar to the browser. It will be listed alongside the built-in sidebars, and the user will be able to open it using the same mechanism as for the built-in sidebars.</p> + +<p>Like a browser action popup, you specify the sidebar's contents as an HTML document. When the user opens the sidebar, its document is loaded into every open browser window. Each window gets its own instance of the document. When new windows are opened, they get their own sidebar documents as well.</p> + +<p>You can set a document for a particular tab using the {{WebExtAPIRef("sidebarAction.setPanel()")}} function. A sidebar can figure out which window it belongs to using the {{WebExtAPIRef("windows.getCurrent()")}} API:</p> + +<pre class="brush: js">// sidebar.js +browser.windows.getCurrent({populate: true}).then((windowInfo) => { + myWindowId = windowInfo.id; +});</pre> + +<p>This is useful if a sidebar wants to display different content for different windows. For an example of this, see the <a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">"annotate-page" example</a>.</p> + +<p>Sidebar documents get access to the same set of privileged JavaScript APIs that the extension's background and popup scripts get. They can get direct access to the background page (unless the sidebar belongs to incognito mode window) using {{WebExtAPIRef("runtime.getBackgroundPage()")}}, and can interact with content scripts or native applications using messaging APIs like {{WebExtAPIRef("tabs.sendMessage()")}} and {{WebExtAPIRef("runtime.sendNativeMessage()")}}.</p> + +<p>Sidebar documents are unloaded when their browser window is closed or when the user closes the sidebar. This means that unlike background pages, sidebar documents don't stay loaded all the time, but unlike browser action popups, they stay loaded while the user interacts with web pages.</p> + +<p>When an extension that defines a sidebar is first installed, its sidebar will be opened automatically. This is intended to help the user understand that the extension includes a sidebar. Note that it's not possible for extension to open sidebars programmatically: sidebars can only be opened by the user.</p> + +<h2 id="Especificar_barras_laterais">Especificar barras laterais</h2> + +<p>To specify a sidebar, define the default document with the <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code> manifest.json key, alongside a default title and icon:</p> + +<pre class="brush: json">"sidebar_action": { + "default_title": "My sidebar", + "default_panel": "sidebar.html", + "default_icon": "sidebar_icon.png" +}</pre> + +<p>You can change the title, panel, and icon programmatically using the {{WebExtAPIRef("sidebarAction")}} API.</p> + +<p>Title and icon are shown to the user in any UI provided by the browser to list sidebars, such as the "View > Sidebar" menu in Firefox.</p> + +<h2 id="Exemplo">Exemplo</h2> + +<p>O repositório de <a href="https://github.com/mdn/webextensions-examples">exemplos das extensões da Web</a> no GitHub, contém vários exemplos de extensões que utilizam a barra lateral:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">annotate-page</a> utiliza uma barra lateral.</li> +</ul> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/devtools_panels/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/devtools_panels/index.html new file mode 100644 index 0000000000..a2bc9921ad --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/devtools_panels/index.html @@ -0,0 +1,62 @@ +--- +title: Painéis das ferramentas de desenvolvimento +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/devtools_panels +tags: + - Extensões da Web + - Guía + - Interface do Utilizador + - Principiante +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>Esta funcionalidade está disponível desde o Firefox 54.</p> +</div> + +<p>Quando uma extensão fornece ferramentas que são úteis para os programadores, é possível adicionar uma IU para as mesmas para as ferramentas de desenvolvimento do navegador como um novo painel.</p> + +<p><img alt='Simple example showing the addition of "My panel" to the Developer Tools tabs.' src="https://mdn.mozillademos.org/files/15035/devtools_panel_example.png" style="height: 352px; width: 1192px;"></p> + +<h2 id="Especificar_um_painel_de_ferramentas_de_desenvolvimento">Especificar um painel de ferramentas de desenvolvimento</h2> + +<p>Um painél das ferramentas de desenvovlimento é adicionado utilizando a API <code><a href="/pt-PT/Add-ons/WebExtensions/API/devtools.panels">devtools.panels</a></code>, que precisa de ser executada a partir de uma página de <em>devtools</em> especial.</p> + +<p>Adicione a páginas de devtools, incluindo a chave <code><a href="/pt-PT/Add-ons/WebExtensions/manifest.json/devtools_page">devtools_page</a></code> na extensão de <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> e forneça a localização do ficheiro HTML da página na extensão:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"devtools_page":</span> <span class="string token">"devtools-page.html"</span></code></pre> + +<p>From the devtools page, call a script that will add the devtools panel:</p> + +<pre class="brush: html"><body> + <script src="devtools.js"></script> +</body></pre> + +<p>In the script, create the devtools panel by specifying the panel's title, icon, and HTML file that provides the panel's content:</p> + +<pre class="brush: js">function handleShown() { + console.log("panel is being shown"); +} + +function handleHidden() { + console.log("panel is being hidden"); +} + +browser.devtools.panels.create( + "My Panel", // title + "icons/star.png", // icon + "devtools/panel/panel.html" // content +).then((newPanel) => { + newPanel.onShown.addListener(handleShown); + newPanel.onHidden.addListener(handleHidden); +});</pre> + +<p>The extension can now run code in the inspected window using <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow/eval"><code>devtools</code>.inspectedWindow.eval()</a></code> or by injecting a content script via the background script by passing a message. You can find more details on how to do this in <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">Extending the developer tools.</a></p> + +<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><a href="https://github.com/mdn/webextensions-examples/blob/master/devtools-panels/">devtools-panels</a> use devtools panels:</li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/estilos_de_navegador/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/estilos_de_navegador/index.html new file mode 100644 index 0000000000..bc2f1bd2da --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/estilos_de_navegador/index.html @@ -0,0 +1,453 @@ +--- +title: Estilos de navegador +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Estilos_de_navegador +tags: + - Extensões + - Extensões da Web + - Extras +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles +--- +<div>{{AddonSidebar}}</div> + +<p>Certain user interface components - browser and page action <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">popups</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">sidebars</a>, and <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Options_pages">options pages</a> - are specified by your extension in essentially the same way:</p> + +<ol> + <li>create an HTML file defining the structure of the UI element</li> + <li>add a manifest.json key (<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code>, or <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code>) pointing to that HTML file.</li> +</ol> + +<p>One of the challenges with this approach is styling the element in such a way that it fits in with the browser's own style. To help with this, the manifest.json keys include an extra optional property: <code>browser_style</code>. If this is included and set to <code>true</code>, then your document will get one or more extra stylesheets that will help make it look consistent with the browser's UI and with other extensions that use the <code>browser_style</code> property.</p> + +<p>In Firefox, the stylesheet can be seen at <code>chrome://browser/content/extension.css</code>. The extra stylesheet at <code>chrome://browser/content/extension-mac.css</code> is also included on OS X.</p> + +<p>Most styles are automatically applied, but some elements require you to add the <span style="white-space: nowrap;">non-standard</span> <code style="white-space: nowrap;">browser-style</code> class to get their styling since Firefox 55, as detailed in the table below:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Elemento</th> + <th scope="col">Exemplo</th> + </tr> + </thead> + <tbody> + <tr> + <td><code><a href="/en-US/docs/Web/HTML/Element/button"><button></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<button class="browser-style">Click me</button>{{non-standard_inline}}</pre> + </td> + </tr> + <tr> + <td> + <p><code><a href="/en-US/docs/Web/HTML/Element/select"><select></a></code></p> + </td> + <td> + <pre class="brush: html no-line-numbers"> +<select class="browser-style" name="select"> + <option value="value1">Value 1</option> + <option value="value2" selected>Value 2</option> + <option value="value3">Value 3</option> +</select></pre> + </td> + </tr> + <tr> + <td><code><a href="/en-US/docs/Web/HTML/Element/textarea"><textarea></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<textarea class="browser-style">Write here</textarea></pre> + </td> + </tr> + <tr> + <td>Parent of an <code><a href="/en-US/docs/Web/HTML/Element/input"><input></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<div class="browser-style"> + <input type="radio" id="op1" name="choices" value="op1"> + <label for="op1">Option 1</label> + + <input type="radio" id="op2" name="choices" value="op2"> + <label for="op2">Option 2</label> +</div></pre> + </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + + + +<p>{{Compat("webextensions.browser_style")}}</p> + +<h2 id="Componentes_de_Painel_do_Firefox">Componentes de Painel do Firefox</h2> + +<div class="overheadIndicator nonStandard nonStandardHeader"> +<p><strong>{{NonStandardBadge(1)}} Non-Standard</strong><br> + This feature is non-standard and only works in Firefox.</p> +</div> + +<p>The <code>chrome://browser/content/extension.css</code> stylesheet also contains the styles for the Firefox Panel Components.</p> + +<p>The <a href="https://firefoxux.github.io/StyleGuide/#/navigation">legacy Firefox Style Guide</a> documents proper usage.</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Elemento</th> + <th scope="col">Exemplo</th> + </tr> + </thead> + <tbody> + <tr> + <td>Cabeçalho</td> + <td> + <pre class="brush: html"> +<header class="panel-section panel-section-header"> + <div class="icon-section-header"><img src="image.svg"/></div> + <div class="text-section-header">Header</div> +</header></pre> + </td> + </tr> + <tr> + <td>Rodapé</td> + <td> + <pre class="brush: html"> +<footer class="panel-section panel-section-footer"> + <button class="panel-section-footer-button">Cancel</button> + <div class="panel-section-footer-separator"></div> + <button class="panel-section-footer-button default">Confirm</button> +</footer></pre> + </td> + </tr> + <tr> + <td>Separadores</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-tabs"> + <button class="panel-section-tabs-button selected">Tab</button> + <div class="panel-section-tabs-separator"></div> + <button class="panel-section-tabs-button">Tab</button> + <div class="panel-section-tabs-separator"></div> + <button class="panel-section-tabs-button">Tab</button> +</div></pre> + </td> + </tr> + <tr> + <td>Form</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-formElements"> + <div class="panel-formElements-item"> + <label for="name01">Label:</label> + <input type="text" value="Name" id="name01" /> + </div> + <div class="panel-formElements-item"> + <label for="picker01">Label:</label> + <select id="picker01"> + <option value="value1" selected="true">Dropdown</option> + <option value="value2">List Item</option> + <option value="value3">List Item</option> + </select> + </div> + <div class="panel-formElements-item"> + <label for="placeholder01">Label:</label> + <input type="text" placeholder="Placeholder" id="placeholder01" /> + <button name="expander" class="expander"></button> + </div> +</div></pre> + </td> + </tr> + <tr> + <td>Menu</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-list"> + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut">Ctrl-L</div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item disabled"> + <div class="icon"></div> + <div class="text">Disabled List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> +</div></pre> + </td> + </tr> + </tbody> +</table> + +<h3 id="Exemplo">Exemplo</h3> + +<h4 id="HTML">HTML</h4> + +<pre class="brush: html"><header class="panel-section panel-section-header"> + <div class="icon-section-header"><!-- An image goes here. --></div> + <div class="text-section-header">Header</div> +</header> + +<div class="panel-section panel-section-list"> + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut">Ctrl-L</div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item disabled"> + <div class="icon"></div> + <div class="text">Disabled List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> +</div> + +<footer class="panel-section panel-section-footer"> + <button class="panel-section-footer-button">Cancel</button> + <div class="panel-section-footer-separator"></div> + <button class="panel-section-footer-button default">Confirm</button> +</footer></pre> + +<div class="hidden"> +<h4 id="CSS">CSS</h4> + +<pre class="brush: css">/* Global */ +html, +body { + background: white; + box-sizing: border-box; + color: #222426; + cursor: default; + display: flex; + flex-direction: column; + font: caption; + margin: 0; + padding: 0; + -moz-user-select: none; +} + +body * { + box-sizing: border-box; + text-align: start; +} + +button.panel-section-footer-button, +button.panel-section-tabs-button { + color: inherit; + background-color: unset; + font: inherit; + text-shadow: inherit; + -webkit-appearance: none; + -moz-appearance: none; + appearance: none; + border: none; +} + +/* Panel Section */ +.panel-section { + display: flex; + flex-direction: row; +} + +.panel-section-separator { + background-color: rgba(0, 0, 0, 0.15); + min-height: 1px; +} + +/* Panel Section - Header */ +.panel-section-header { + border-bottom: 1px solid rgba(0, 0, 0, 0.15); + padding: 16px; +} + +.panel-section-header > .icon-section-header { + background-position: center center; + background-repeat: no-repeat; + height: 32px; + margin-right: 16px; + position: relative; + width: 32px; +} + +.panel-section-header > .text-section-header { + align-self: center; + font-size: 1.385em; + font-weight: lighter; +} + +/* Panel Section - List */ +.panel-section-list { + flex-direction: column; + padding: 4px 0; +} + +.panel-list-item { + align-items: center; + display: flex; + flex-direction: row; + height: 24px; + padding: 0 16px; +} + +.panel-list-item:not(.disabled):hover { + background-color: rgba(0, 0, 0, 0.06); + border-bottom: 1px solid rgba(0, 0, 0, 0.1); + border-top: 1px solid rgba(0, 0, 0, 0.1); +} + +.panel-list-item:not(.disabled):hover:active { + background-color: rgba(0, 0, 0, 0.1); +} + +.panel-list-item.disabled { + color: #999; +} + +.panel-list-item > .icon { + flex-grow: 0; + flex-shrink: 0; +} + +.panel-list-item > .text { + flex-grow: 10; +} + +.panel-list-item > .text-shortcut { + color: #808080; + font-family: "Lucida Grande", caption; + font-size: .847em; + justify-content: flex-end; +} + +.panel-section-list .panel-section-separator { + margin: 4px 0; +} + +/* Panel Section - Footer */ +.panel-section-footer { + background-color: rgba(0, 0, 0, 0.06); + border-top: 1px solid rgba(0, 0, 0, 0.15); + color: #1a1a1a; + display: flex; + flex-direction: row; + height: 41px; + margin-top: -1px; + padding: 0; +} + +.panel-section-footer-button { + flex: 1 1 auto; + height: 100%; + margin: 0 -1px; + padding: 12px; + text-align: center; +} + +.panel-section-footer-button > .text-shortcut { + color: #808080; + font-family: "Lucida Grande", caption; + font-size: .847em; +} + +.panel-section-footer-button:hover { + background-color: rgba(0, 0, 0, 0.06); +} + +.panel-section-footer-button:hover:active { + background-color: rgba(0, 0, 0, 0.1); +} + +.panel-section-footer-button.default { + background-color: #0996f8; + box-shadow: 0 1px 0 #0670cc inset; + color: #fff; +} + +.panel-section-footer-button.default:hover { + background-color: #0670cc; + box-shadow: 0 1px 0 #005bab inset; +} + +.panel-section-footer-button.default:hover:active { + background-color: #005bab; + box-shadow: 0 1px 0 #004480 inset; +} + +.panel-section-footer-separator { + background-color: rgba(0, 0, 0, 0.1); + width: 1px; + z-index: 99; +}</pre> + +<hr> +<pre class="brush: css">/* Example specific – not part of chrome://browser/content/extension.css */ +body { + background: #fcfcfc; + background-clip: padding-box; + border: 1px solid rgba(24,26,27,.2); + box-shadow: 0 3px 5px rgba(24,26,27,.1),0 0 7px rgba(24,26,27,.1); + box-sizing: content-box; + margin: 2em auto .5em; + width: 384px; +} + +html { + min-height: 100vh; +} + +html > body { + margin: auto; +} + +.icon-section-header { + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgdmlld0JveD0iMCAwIDMyIDMyIj48Y2lyY2xlIGZpbGw9IiMzNjM5NTkiIGN4PSIxNSIgY3k9IjE1IiByPSIxNSIvPjwvc3ZnPg=="); +}</pre> +</div> + +<h4 id="Result">Result</h4> + +<p>{{EmbedLiveSample("Example","640","360")}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/index.html new file mode 100644 index 0000000000..6ec29a7fcf --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/index.html @@ -0,0 +1,93 @@ +--- +title: Interface do utilizador +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador +tags: + - Interface do Utilizador + - Landing + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +<div>{{AddonSidebar}}</div> + +<p>As extensões que utilizam as APIs de WebExtension são fornecidas com várias opções de interface do utilizador, e assim, as suas funcionalidades podem ficar disponíveis para o utilizador. Um resumo dessas opções é fornecido abaixo, com uma introdução mais detalhada para cada opção da interface do utilziador nesta secção .</p> + +<div class="note"> +<p>For advice on using these UI components to create a great user experience in your extension, please see the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/User_experience_best_practices">User experience best practices</a> article.</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Opção de UI</th> + <th scope="col">Descrição</th> + <th scope="col" style="width: 350px;">Exemplo</th> + </tr> + </thead> + <tbody> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">Browser toolbar button</a></td> + <td>A button on the browser toolbar that dispatches an event to the extension when clicked. By default, the button is visible in all tabs.</td> + <td><img alt="Example of a WebExtension toolbar button" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="height: 99px; width: 350px;"></td> + </tr> + <tr> + <td>Browser toolbar button with a <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">popup</a></td> + <td>A popup on a button in the browser toolbar that opens when the button is clicked. The popup is defined in an HTML document that handles the user interaction.</td> + <td><img alt="Example of a WebExtension toolbar button with a popup" src="https://mdn.mozillademos.org/files/14039/popup-shadow.png" style="height: 156px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">Address bar button</a></td> + <td>A button on the browser address bar that dispatches an event to the extension when clicked. By default, the button is hidden in all tabs.</td> + <td><img alt="Example showing an address bar button (page action)" src="https://mdn.mozillademos.org/files/15047/address_bar_button.png" style="height: 127px; width: 350px;"></td> + </tr> + <tr> + <td>Address bar button with a <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">popup</a></td> + <td>A popup on a button in the browser address bar that opens when the button is clicked. The popup is defined in an HTML document that handles the user interaction.</td> + <td><img alt="Example of a popup on the address bar button" src="https://mdn.mozillademos.org/files/15053/page_action_popup.png" style="height: 250px; width: 330px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items">Context menu items</a></td> + <td>Menu items, checkboxes, and radio buttons on one or more of the browser's context menus. Also, menus can be structured by adding separators. When menu items are clicked, an event is dispatched to the extension.</td> + <td><img alt="" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="height: 359px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">Sidebar</a></td> + <td> + <p dir="ltr">An HTML document displayed next to a web page, with the option for unique content per page. The sidebar is opened when the extension is installed, then obeys the user's sidebar visibility selection. User interaction within the sidebar is handled by its HTML document.</p> + </td> + <td><img alt="Example of a WebExtension's sidebar" src="https://mdn.mozillademos.org/files/14825/bookmarks-sidebar.png" style="height: 209px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">Options page</a></td> + <td>A page that enables you to define preferences for your extension that your users can change. The user can access this page in the from the browser's add-ons manager.</td> + <td><img alt="Example showing the options page content added in the favorite colors example." src="https://mdn.mozillademos.org/files/15055/options_page.png" style="height: 259px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Bundled_web_pages">Bundled web pages</a></td> + <td>Use web pages included in your extension to provide forms, help, or any other content required, within windows or tabs.</td> + <td><img alt="Example of a simple bundled page displayed as a detached panel." src="https://mdn.mozillademos.org/files/15063/bundled_page_as_panel_small.png" style="height: 180px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications">Notifications</a></td> + <td>Transient notifications displayed to the user through the underlying operating system's notifications mechanism. Dispatches an event to the extension when the user clicks a notification, or when a notification closes (either automatically or at the user's request).</td> + <td><img alt="Example notification from a WebExtension" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="height: 95px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox">Address bar suggestions</a></td> + <td>Offer custom address bar suggestions when the user enters a keyword.</td> + <td><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15059/omnibox_example_small.png" style="height: 242px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels">Developer tools panels</a></td> + <td>A tab with an associated HTML document that displays in the browser's developer tools.</td> + <td><img alt="New panel tab in the Developer Tools tab bar" src="https://mdn.mozillademos.org/files/15049/developer_panel_tab.png" style="height: 180px; width: 350px;"></td> + </tr> + </tbody> +</table> + +<p>The following how-to guides provide step-by-step guidance to creating some of these user interface options:</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">Add a button to the toolbar</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page">Implement a settings page</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">Extending the developer tools</a></li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/itens_do_menu_de_contexto/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/itens_do_menu_de_contexto/index.html new file mode 100644 index 0000000000..231a800bc3 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/itens_do_menu_de_contexto/index.html @@ -0,0 +1,51 @@ +--- +title: Itens do menu de contexto +slug: >- + Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Itens_do_menu_de_contexto +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>Essa opção da interface do utilizador adiciona um ou mais itens a um menu de contexto do navegador.</p> + +<p><img alt="Example of content menu items added by a WebExtension, from the context-menu-demo example" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="display: block; height: 587px; margin-left: auto; margin-right: auto; width: 573px;"></p> + +<p>You would use this option to expose features that are relevant to specific browser or web page contexts. For example, you could show features to open a graphic editor when the user clicks on an image or offer a feature to save page content when part of a page is selected. You can add plain menu items, checkbox items, radio button groups, and separators to menus. Once a context menu item has been added using {{WebExtAPIRef("contextMenus.create")}} it's displayed in all browser tabs, but you can hide it by removing it with {{WebExtAPIRef("contextMenus.remove")}}.</p> + +<h2 id="Especificar_itens_do_menu_de_contexto">Especificar itens do menu de contexto</h2> + +<p>You manage context menu items programmatically, using the {{WebExtAPIRef("contextMenus")}} API. However, you need to request the <code>contextMenus</code> permission in your manifest.json to be able to take advantage of the API.</p> + +<pre class="brush: json">"permissions": ["contextMenus"]</pre> + +<p>You can then add (and update or delete) the context menu items in your extension's background script. To create a menu item you specify an id, its title, and the context menus it should appear on:</p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "log-selection", + title: browser.i18n.getMessage("contextMenuItemSelectionLogger"), + contexts: ["selection"] +}, onCreated);</pre> + +<p>Your extension then listens for clicks on the menu items. The passed information about the item clicked, the context where the click happened, and details of the tab where the click took place can then be used to invoke the appropriate extension functionality.</p> + +<pre class="brush: js">browser.contextMenus.onClicked.addListener(function(info, tab) { + switch (info.menuItemId) { + case "log-selection": + console.log(info.selectionText); + break; + ... + } +})</pre> + +<h2 id="Exemplos">Exemplos</h2> + +<p>O repositório de <a class="external external-icon" href="https://github.com/mdn/webextensions-examples">wexemplos das Extensões da Web </a>no GitHub, contém vários exemplos de extensões que utilizam os itens do menu de contexto:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/menu-demo">menu-demo</a> adds several items to the browser's context menu.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-copy-link-with-types">context-menu-copy-link-with-types</a> adds a context menu item to links that copies the URL to the clipboard, as plain text and rich HTML.</li> +</ul> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/notificacoes/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/notificacoes/index.html new file mode 100644 index 0000000000..5b38d4f29f --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/notificacoes/index.html @@ -0,0 +1,50 @@ +--- +title: Notificações +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Notificacoes +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Notifications +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>As notificações permitem-lhe comunicar a informação sobre a sua extensão ou o seu conteúdo utilizando o serviço de notificação do sistema operativo subjacente:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="display: block; height: 334px; margin-left: auto; margin-right: auto; width: 700px;"></p> + +<p>As notificações podem incluir uma chamada para ação para o utilizador, e o seu extra pode escutar o utilizador a clicar na notificação ou a notificação a fechar.</p> + +<h2 id="Especificar_as_notificações">Especificar as notificações</h2> + +<p>Pode gerir as notificações programaticamente, utilizando a API {{WebExtAPIRef("notifications")}}. Para utilizar esta API deve solicitar a permissão de <em><code>notifications</code></em> no seu manifest.json:</p> + +<pre class="brush: json"><span class="pl-s"><span class="pl-pds">"</span>permissions<span class="pl-pds">"</span></span>: [<span class="pl-s"><span class="pl-pds">"</span>notifications<span class="pl-pds">"</span></span>]</pre> + +<p>Depois, pode utilziar {{WebExtAPIRef("notifications.create")}} para criar as suas notificações, como neste exemplo de <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n:</a></p> + +<pre class="brush: js">var title = browser.i18n.getMessage("notificationTitle"); +var content = browser.i18n.getMessage("notificationContent", message.url); +browser.notifications.create({ + "type": "basic", + "iconUrl": browser.extension.getURL("icons/link-48.png"), + "title": title, + "message": content +});</pre> + +<p>Este código cria uma notificação com um ícone, título, e mensagem.</p> + +<p>Se a notificação incluir uma chamada para ação, pode escutar o utilizador a clicar na notificação para chamar a ação para manipular a ação:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>notifications<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span> +</code></pre> + +<p>Se estiver a enviar chamadas para ação através das notificações, também irá querer definir a notificação opcional <code>id</code>, e assim, pode saber qual a chamada para ação que o utilizador selecionou.</p> + +<h2 id="Exemplos">Exemplos</h2> + +<p>O repositório dos <a href="https://github.com/mdn/webextensions-examples">exemplos da extensões da Web</a> no GitHub, contém vários exemplos das extensões que utilizam <em>creates notifications</em>:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> utiliza <em>creates notifications</em>.</li> +</ul> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/omnibox/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/omnibox/index.html new file mode 100644 index 0000000000..c0f9f41dca --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/omnibox/index.html @@ -0,0 +1,70 @@ +--- +title: Sugestões da barra de endereço +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Omnibox +tags: + - Extensões da Web + - Interface do Utilizador +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Omnibox +--- +<div>{{AddonSidebar()}}</div> + +<p>Using the {{WebExtAPIRef("omnibox")}} API, extensions can customize the suggestions offered in the browser address bar's drop-down when the user enters a keyword.</p> + +<p><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15749/omnibox_example_small.png" style="display: block; height: 232px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>This enables your extension to, for example, search a library of free ebooks or, as in the example above, a repository of code examples.</p> + +<h2 id="Especificando_a_personalização_de_omnibox">Especificando a personalização de omnibox</h2> + +<p>You tell your extension that it is going to customize the address bar suggestions by including the <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/omnibox">omnibox</a> key and definition of the trigger keyword in its <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> file:</p> + +<pre class="brush: json line-numbers language-json"> "omnibox": { "keyword" : "cs" }</pre> + +<p>In the extension's background JavaScript file, using {{WebExtAPIRef("omnibox.setDefaultSuggestion()")}}, you can optionally define the first suggestion to be displayed in the address bar drop-down. Use this to provide a hint on how to use the feature:</p> + +<pre class="brush: js line-numbers language-js">browser.omnibox.setDefaultSuggestion({ + description: `Search the firefox codebase + (e.g. "hello world" | "path:omnibox.js onInputChanged")` +});</pre> + +<p>You can then add the code to provide the customized content by listening for {{WebExtAPIRef("omnibox.onInputStarted")}}, which is dispatched when the user has typed the keyword and a space, and {{WebExtAPIRef("omnibox.onInputChanged")}}, which is dispatched whenever the user updates the address bar entry. You can then populate the suggestions, in this case building a search of https://searchfox.org/mozilla-central using the term entered by the user:</p> + +<pre class="brush: js">browser.omnibox.onInputChanged.addListener((text, addSuggestions) => { + let headers = new Headers({"Accept": "application/json"}); + let init = {method: 'GET', headers}; + let url = buildSearchURL(text); + let request = new Request(url, init); + + fetch(request) + .then(createSuggestionsFromResponse) + .then(addSuggestions); +});</pre> + +<p>If the extension set a default suggestion using {{WebExtAPIRef("omnibox.setDefaultSuggestion()")}}, then this will appear first in the drop-down.</p> + +<p>The extension can then listen for the user clicking one of the suggestions, using {{WebExtAPIRef("omnibox.onInputEntered")}}. If the default suggestion is clicked the user's custom term is returned, otherwise the suggestion's string is returned. This also passes information on the user's browser preferences for handling new links. In the code below the user's custom term is used to create a search, otherwise the suggested URL is opened:</p> + +<pre class="brush: js">browser.omnibox.onInputEntered.addListener((text, disposition) => { + let url = text; + if (!text.startsWith(SOURCE_URL)) { + // Update the url if the user clicks on the default suggestion. + url = `${SEARCH_URL}?q=${text}`; + } + switch (disposition) { + case "currentTab": + browser.tabs.update({url}); + break; + case "newForegroundTab": + browser.tabs.create({url}); + break; + case "newBackgroundTab": + browser.tabs.create({url, active: false}); + break; + } +});</pre> + +<p> </p> + +<h2 id="Exemplos">Exemplos</h2> + +<p>O repositório dos <a href="https://github.com/mdn/webextensions-examples">exemplos das extensões da Web</a> no GitHub inclui o exemplo <a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/firefox-code-search">firefox-code-search</a> que personaliza a barra de pesquisa.</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/options_pages/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/options_pages/index.html new file mode 100644 index 0000000000..b3bee11990 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/options_pages/index.html @@ -0,0 +1,64 @@ +--- +title: Página de opções +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Options_pages +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Options_pages +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>Uma página de <strong>Opções</strong> permite-lhe definir as preferências para sua extensão que os seus utilizadores podem alterar. Os utilizadores podem aceder á página das opções para uma extensão a partir do do gestor de extras do navegador:</p> + +<p>{{EmbedYouTube("02oXAcbUv-s")}}</p> + +<p>The way users access the page, and the way it's integrated into the browser's user interface, will vary from one browser to another.</p> + +<ul> +</ul> + +<p>You can open the page programmatically by calling <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/Runtime/openOptionsPage" title="If your add-on does not have an options page, or the browser failed to create one for some other reason, runtime.lastError will be set."><code>runtime.openOptionsPage()</code></a>.</p> + +<p>Options pages have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>. See <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> for more details.</p> + +<h2 id="Especificar_a_página_de_opções">Especificar a página de opções</h2> + +<p>To create an options page, write an HTML file defining the page. This page can include CSS and JavaScript files, like a normal web page. This page, from the <a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">favourite-colour</a> example, includes a JavaScript file:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + </head> + +<body> + <form> + <label>Favourite colour</label> + <input type="text" id="colour" > + <button type="submit">Save</button> + </form> + <script src="options.js"></script> +</body> + +</html></pre> + +<p>JavaScript em execução na página pode utilizar a <a href="/pt-PT/Add-ons/WebExtensions/API">API das Extensões da Web</a> que o extra tem <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissões</a> para. Em particular, pode utilziar a APi de <a href="/pt-PT/Add-ons/WebExtensions/API/Armazenamento" title="Enables WebExtensions to store and retrieve data, and listen for changes to stored items."><code>armazenamento</code></a> para manter as preferências.</p> + +<p>Package the page's files in your extension.</p> + +<p>You also need to include the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code> key in your manifest.json file, giving it the URL to the page.</p> + +<pre class="brush: json">"options_ui": { + "page": "options.html", + "browser_style": true +},</pre> + +<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 an options page:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">favourite-colour</a> example extension with options page</li> +</ul> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/paginas_de_extensão/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/paginas_de_extensão/index.html new file mode 100644 index 0000000000..4bf94b9653 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/paginas_de_extensão/index.html @@ -0,0 +1,64 @@ +--- +title: Páginas de extensão +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Paginas_de_extensão +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages +--- +<div>{{AddonSidebar()}}</div> + +<p>Pode inclur páginas html na sua extensão para fornecer formulários, ajuda, ou qualquer outro conteúdo que a sua extensão precisar.</p> + +<p><img alt="Example of a simple bundled page displayed as a detached panel." src="https://mdn.mozillademos.org/files/15752/bundled_page_as_panel_small.png" style="display: block; height: 216px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>These pages also get access to the same privileged JavaScript APIs that are available to your extension's background scripts.</p> + +<h2 id="Especificar_páginas_de_extensão">Especificar páginas de extensão</h2> + +<p>You can include HTML files, and their associated CSS or JavaScript files, in your extension. The files can be included in the root or organized within meaningful sub-folders.</p> + +<pre>/my-extension + /manifest.json + /my-page.html + /my-page.js</pre> + +<h2 id="Exibir_páginas_de_extensão">Exibir páginas de extensão</h2> + +<p>There are two options for displaying extension pages: {{WebExtAPIRef("windows.create()")}} and {{WebExtAPIRef("tabs.create()")}}.</p> + +<p>Using <code>windows.create()</code>, for example, you can open an HTML page into a detached panel (a window without the normal browser UI of address bar, bookmark bar, and alike) to create a dialog-like user experience:</p> + +<pre class="brush: js">var createData = { + type: "detached_panel", + url: "panel.html", + width: 250, + height: 100 +}; +var creating = browser.windows.create(createData);</pre> + +<p>When the window is no longer needed, it can be closed programmatically, for example, after the user clicks a button, by passing the id of the current window to {{WebExtAPIRef("windows.remove()")}}:</p> + +<pre class="brush: js">document.getElementById("closeme").addEventListener("click", function(){ + var winId = browser.windows.WINDOW_ID_CURRENT; + var removing = browser.windows.remove(winId); +}); </pre> + +<h2 id="Páginas_de_extensão_e_histório">Páginas de extensão e histório</h2> + +<p>By default, pages you open in this way will be stored in the user's history, just like normal web pages. If you don't want to have this behavior, use {{WebExtAPIRef("history.deleteUrl()")}} to remove the browser's record:</p> + +<pre class="comment-text " id="ct-4">function onVisited(historyItem) { + if (historyItem.url == browser.extension.getURL(myPage)) { + browser.history.deleteUrl({url: historyItem.url}); + } +} + +browser.history.onVisited.addListener(onVisited);</pre> + +<p>To use the history API, you must request the "history" <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a> in your <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></code> file.</p> + +<h2 id="Desenho_da_página_da_Web">Desenho da página da Web</h2> + +<p>For details on how to design your web page's to match the style of Firefox, see the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Exemplos">Exemplos</h2> + +<p>The <a class="external external-icon" href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository on GitHub includes the <a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/window-manipulator">window-manipulator</a> example, which implements several of the options for creating windows.</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/popups/index.html b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/popups/index.html new file mode 100644 index 0000000000..6bbf3f7ce8 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/interface_do_utilizador/popups/index.html @@ -0,0 +1,60 @@ +--- +title: Janelas (Popups) +slug: Mozilla/Add-ons/WebExtensions/interface_do_utilizador/Popups +tags: + - Extensions + - IU + - Interface do Utilizador + - Janela + - popup +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Popups +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>Uma janela (<em>popup)</em> é uma janela que está associada com um <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Ação_navegador">botão da barra de ferramentas</a> ou <a href="/pt-PT/Add-ons/WebExtensions/interface_do_utilizador/Acoes_pagina">botão da barra de endereço</a>.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15747/page_action_popup.png" style="display: block; height: 282px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>Quando o usuário clica no botão, a janela popup é exibida. Quando o usuário clica em qualquer lugar fora do popup, ele é fechado. O popup pode ser fechado via programação usando a função <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/close">window.close()</a></code> em um script sendo executado no popup. Entretanto, você não pode abrir o popup via programação a partir do código JavaScript da extensão: ele somente se abre em resposta a uma ação do usuário.</p> + +<p>Você pode definir um atalho de teclado que abre o popup usando <code>"_execute_browser_action"</code> and <code>"_execute_page_action"</code>. Veja a documentação da chave <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands">commands</a></code><span style="display: none;"> </span> no manifest.json.</p> + +<h2 id="Especificar_uma_janela">Especificar uma janela</h2> + +<p>O popup é definido por um arquivo HTML, que pode incluir arquivos CSS e JavaScript, como uma página comum. Diferentemente de uma página comum, o código JavaScript pode usar todos os <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> que a extensão tem <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a> .</p> + +<p>O documento do popup é carregado toda vez que ele é exibido, e descarregado quando o popup é fechado.</p> + +<p>O arquivo HTML é incluído na extensão e especificado como parte do <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> ou chave <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a> por <code>"default_popup"</code> no arquivo manifest.json:</p> + +<pre class="brush: json"> "browser_action": { + "default_icon": "icons/beasts-32.png", + "default_title": "Beastify", + "default_popup": "popup/choose_beast.html" + }</pre> + +<p>You can ask the browser to include a stylesheet in your popup that will make it look consistent with the browser's UI. To do this, include <code>"browser_style": true</code> in the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> or <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a> key.</p> + +<p>Popups have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>. See <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> for more details on this.</p> + +<h2 id="Depurar_janelas">Depurar janelas</h2> + +<p>You can debug a popup's markup and JavaScript using the Add-on Debugger, but you'll need to turn on the Disable popup auto hide feature to prevent popups from hiding when you click outside them.<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Debugging#Debugging_popups"> Read about debugging popups</a>.</p> + +<h2 id="Redimensionar_janelas">Redimensionar janelas</h2> + +<p>Popups resize automatically to fit their content. The algorithm for this may differ from one browser to another.</p> + +<p>In Firefox, the size is calculated just before the popup is shown, and at most 10 times per second after DOM mutations. For strict mode documents, the size is calculated based on the layout size of the <code><a href="/en-US/docs/Web/HTML/Element/body"><body></a></code> element. For quirks mode, it's the <code><a href="/en-US/docs/Web/HTML/Element/html"><html></a></code> element. Firefox calculates the preferred width of the contents of that element, reflows it to that width, and then resizes so there's no vertical scrolling. It will grow to a size of <strong>800x600 pixels</strong> at most if that fits on the user's screen. If the user <a href="https://support.mozilla.org/en-US/kb/customize-firefox-controls-buttons-and-toolbars#w_customize-the-menu-or-the-toolbar">moves the extension's button to the menu</a> or it appears in the toolbar overflow, then the popup appears inside the menu's panel and is given a fixed width.</p> + +<p>No Firefox Android 57, <em>popup </em>é mostrada como uma página normal num novo separador.</p> + +<h2 id="Desenho_de_janela">Desenho de janela</h2> + +<p>Para obter detalhes sobre como desenhar a sua janela (popup) da página da Web para combinar com o estilo do Firefox, consulte a documentação <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a>.</p> + +<h2 id="Exemplos">Exemplos</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository on GitHub includes the <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> example which implements a browser action with a popup.</p> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/internationalization/index.html b/files/pt-pt/mozilla/add-ons/webextensions/internationalization/index.html new file mode 100644 index 0000000000..4892048ba8 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/internationalization/index.html @@ -0,0 +1,417 @@ +--- +title: Internationalization +slug: Mozilla/Add-ons/WebExtensions/Internationalization +tags: + - Artigo + - Extensões da Web + - Guía + - Internacionalização + - Localização + - Tradução + - i18n + - mensagens predefinidas + - messages.json + - placeholders + - símbolos +translation_of: Mozilla/Add-ons/WebExtensions/Internationalization +--- +<div>{{AddonSidebar}}</div> + +<p>A API das <a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions">Extensões da Web</a> tem um módulo bastante útil disponível para a internacionalização das extensões — <a href="/pt-PT/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a>. Neste artigo, nós iremos explorar as suas funcionaldiades e fornecemos um exemplo prático de como este funciona. O sistema i18n para as extensões criadas utilizando as APIs da Extensão da Web é semelhante às bibliotecas de JavaScript comuns do i18n, tal como <a href="http://i18njs.com/">i18n.js</a>.</p> + +<div class="note"> +<p>The example extension featured in this article — <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> — is available on GitHub. Follow along with the source code as you go through the sections below.</p> +</div> + +<h2 id="Anatomia_de_uma_extensão_internacionalizada">Anatomia de uma extensão internacionalizada</h2> + +<p>An internationalized extension can contain the same features as any other extension — <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background scripts</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts</a>, etc. — but it also has some extra parts to allow it to switch between different locales. These are summarized in the following directory tree:</p> + +<ul class="directory-tree"> + <li>extension-root-directory/ + <ul> + <li>_locales + <ul> + <li>en + <ul> + <li>messages.json + <ul> + <li>English messages (strings)</li> + </ul> + </li> + </ul> + </li> + <li>de + <ul> + <li>messages.json + <ul> + <li>German messages (strings)</li> + </ul> + </li> + </ul> + </li> + <li>etc.</li> + </ul> + </li> + <li>manifest.json + <ul> + <li>locale-dependent metadata</li> + </ul> + </li> + <li>myJavascript.js + <ul> + <li>JavaScript for retrieving browser locale, locale-specific messages, etc.</li> + </ul> + </li> + <li>myStyles.css + <ul> + <li>locale-dependent CSS</li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Let's explore each of the new features in turn — each of the below sections represents a step to follow when internationalizing your extension.</p> + +<h2 id="Fornecer_strings_traduzidas_em__locales">Fornecer <em>strings</em> traduzidas em _locales</h2> + +<div class="pull-aside"> +<div class="moreinfo">You can look up language subtags using the <em>Find</em> tool on the <a href="https://r12a.github.io/app-subtags/">Language subtag lookup page</a>. Note that you need to search for the English name of the language.</div> +</div> + +<p>Every i18n system requires the provision of strings translated into all the different locales you want to support. In extensions, these are contained within a directory called <code>_locales</code>, placed inside the extension root. Each individual locale has its strings (referred to as messages) contained within a file called <code>messages.json</code>, which is placed inside a subdirectory of <code>_locales</code>, named using the language subtag for that locale's language.</p> + +<p>Note that if the subtag includes a basic language plus a regional variant, then the language and variant are conventionally separated using a hyphen: for example, "en-US". However, in the directories under <code>_locales</code>, <strong>the separator must be an underscore</strong>: "en_US".</p> + +<p>So <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n/_locales">for example, in our sample app</a> we have directories for "en" (English), "de" (German), "nl" (Dutch), and "ja" (Japanese). Each one of these has a <code>messages.json</code> file inside it.</p> + +<p>Let's now look at the structure of one of these files (<a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/_locales/en/messages.json">_locales/en/messages.json</a>):</p> + +<pre class="brush: json">{ + "extensionName": { + "message": "Notify link clicks i18n", + "description": "Name of the extension." + }, + + "extensionDescription": { + "message": "Shows a notification when the user clicks on links.", + "description": "Description of the extension." + }, + + "notificationTitle": { + "message": "Click notification", + "description": "Title of the click notification." + }, + + "notificationContent": { + "message": "You clicked $URL$.", + "description": "Tells the user which link they clicked.", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } + } +}</pre> + +<p>This file is standard JSON — each one of its members is an object with a name, which contains a <code>message</code> and a <code>description</code>. All of these items are strings; <code>$URL$</code> is a placeholder, which is replaced with a substring at the time the <code>notificationContent</code> member is called by the extension. You'll learn how to do this in the {{anch("Retrieving message strings from JavaScript")}} section.</p> + +<div class="note"> +<p><strong>Note</strong>: You can find much more information about the contents of <code>messages.json</code> files in our <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference">Locale-Specific Message reference</a>.</p> +</div> + +<h2 id="Internacionalizar_manifest.json">Internacionalizar manifest.json</h2> + +<p>There are a couple of different tasks to carry out to internationalize your manifest.json.</p> + +<h3 id="Obter_as_strings_traduzidas_em_manifests">Obter as <em>strings</em> traduzidas em <em>manifests</em></h3> + +<p>Your <a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/manifest.json">manifest.json</a> includes strings that are displayed to the user, such as the extension's name and description. If you internationalize these strings and put the appropriate translations of them in messages.json, then the correct translation of the string will be displayed to the user, based on the current locale, like so.</p> + +<p>To internationalize strings, specify them like this:</p> + +<pre class="brush: json">"name": "__MSG_extensionName__", +"description": "__MSG_extensionDescription__",</pre> + +<p>Here, we are retrieving message strings dependant on the browser's locale, rather than just including static strings.</p> + +<p>To call a message string like this, you need to specify it like this:</p> + +<ol> + <li>Two underscores, followed by</li> + <li>The string "MSG", followed by</li> + <li>One underscore, followed by</li> + <li>The name of the message you want to call as defined in <code>messages.json</code>, followed by</li> + <li>Two underscores</li> +</ol> + +<pre><strong>__MSG_</strong> + <em>messageName</em> + <strong>__</strong></pre> + +<h3 id="Especificar_uma_locale_predefinida">Especificar uma <em>locale</em> predefinida</h3> + +<p>Another field you should specify in your manifest.json is <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/default_locale">default_locale</a>:</p> + +<pre class="brush: json">"default_locale": "en"</pre> + +<p>This specifies a default locale to use if the extension doesn't include a localized string for the browser's current locale. Any message strings that are not available in the browser locale are taken from the default locale instead. There are some more details to be aware of in terms of how the browser selects strings — see {{anch("Localized string selection")}}.</p> + +<h2 id="Locale-dependent_CSS">Locale-dependent CSS</h2> + +<p>Note that you can also retrieve localized strings from CSS files in the extension. For example, you might want to construct a locale-dependent CSS rule, like this:</p> + +<pre class="brush: css">header { + background-image: url(../images/__MSG_extensionName__/header.png); +}</pre> + +<p>This is useful, although you might be better off handling such a situation using {{anch("Predefined messages")}}.</p> + +<h2 id="Obter_strings_a_partir_de_JavaScript">Obter <em>strings</em> a partir de JavaScript</h2> + +<p>So, you've got your message strings set up, and your manifest. Now you just need to start calling your message strings from JavaScript so your extension can talk the right language as much as possible. The actual <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n API</a> is pretty simple, containing just four main methods:</p> + +<ul> + <li>You'll probably use {{WebExtAPIRef("i18n.getMessage()")}} most often — this is the method you use to retrieve a specific language string, as mentioned above. We'll see specific usage examples of this below.</li> + <li>The {{WebExtAPIRef("i18n.getAcceptLanguages()")}} and {{WebExtAPIRef("i18n.getUILanguage()")}} methods could be used if you needed to customize the UI depending on the locale — perhaps you might want to show preferences specific to the users' preferred languages higher up in a prefs list, or display cultural information relevant only to a certain language, or format displayed dates appropriately according to the browser locale.</li> + <li>The {{WebExtAPIRef("i18n.detectLanguage()")}} method could be used to detect the language of user-submitted content, and format it appropriately.</li> +</ul> + +<p>In our <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> example, the<a href="https://github.com/mdn/webextensions-examples/blob/master/notify-link-clicks-i18n/background-script.js"> background script</a> contains the following lines:</p> + +<pre class="brush: js">var title = browser.i18n.getMessage("notificationTitle"); +var content = browser.i18n.getMessage("notificationContent", message.url);</pre> + +<p>The first one just retrieves the <code>notificationTitle message</code> field from the available <code>messages.json</code> file most appropriate for the browser's current locale. The second one is similar, but it is being passed a URL as a second parameter. What gives? This is how you specify the content to replace the <code>$URL$</code> placeholder we see in the <code>notificationContent message</code> field:</p> + +<pre class="brush: json">"notificationContent": { + "message": "You clicked $URL$.", + "description": "Tells the user which link they clicked.", + "placeholders": { + "url" : { + "content" : "$1", + "example" : "https://developer.mozilla.org" + } + } +} +</pre> + +<p>The <code>"placeholders"</code> member defines all the placeholders, and where they are retrieved from. The <code>"url"</code> placeholder specifies that its content is taken from $1, which is the first value given inside the second parameter of <code>getMessage()</code>. Since the placeholder is called <code>"url"</code>, we use <code>$URL$</code> to call it inside the actual message string (so for <code>"name"</code> you'd use <code>$NAME$</code>, etc.) If you have multiple placeholders, you can provide them inside an array that is given to {{WebExtAPIRef("i18n.getMessage()")}} as the second parameter — <code>[a, b, c]</code> will be available as <code>$1</code>, <code>$2</code>, and <code>$3</code>, and so on, inside <code>messages.json</code>.</p> + +<p>Let's run through an example: the original <code>notificationContent</code> message string in the <code>en/messages.json</code> file is</p> + +<pre>You clicked $URL$.</pre> + +<p>Let's say the link clicked on points to <code>https://developer.mozilla.org</code>. After the {{WebExtAPIRef("i18n.getMessage()")}} call, the contents of the second parameter are made available in messages.json as <code>$1</code>, which replaces the <code>$URL$</code> placeholder as defined in the <code>"url"</code> placeholder. So the final message string is</p> + +<pre>You clicked https://developer.mozilla.org.</pre> + +<h3 id="Direct_placeholder_usage">Direct placeholder usage</h3> + +<p>It is possible to insert your variables (<code>$1</code>, <code>$2</code>, <code>$3</code>, etc.) directly into the message strings, for example we could rewrite the above <code>"notificationContent"</code> member like this:</p> + +<pre class="brush: json">"notificationContent": { + "message": "You clicked $1.", + "description": "Tells the user which link they clicked." +}</pre> + +<p>This may seem quicker and less complex, but the other way (using <code>"placeholders"</code>) is seen as best practice. This is because having the placeholder name (e.g. <code>"url"</code>) and example helps you to remember what the placeholder is for — a week after you write your code, you'll probably forget what <code>$1</code>–<code>$8</code> refer to, but you'll be more likely to know what your placeholder names refer to.</p> + +<h3 id="Hardcoded_substitution">Hardcoded substitution</h3> + +<p>It is also possible to include hardcoded strings in placeholders, so that the same value is used every time, instead of getting the value from a variable in your code. For example:</p> + +<pre class="brush: json">"mdn_banner": { + "message": "For more information on web technologies, go to $MDN$.", + "description": "Tell the user about MDN", + "placeholders": { + "mdn": { + "content": "https://developer.mozilla.org/" + } + } +}</pre> + +<p>In this case we are just hardcoding the placeholder content, rather than getting it from a variable value like <code>$1</code>. This can sometimes be useful when your message file is very complex, and you want to split up different values to make the strings more readable in the file, plus then these values could be accessed programmatically.</p> + +<p>In addition, you can use such substitutions to specify parts of the string that you don't want to be translated, such as person or business names.</p> + +<h2 id="Seleção_de_string_traduzida">Seleção de string traduzida</h2> + +<p>Locales can be specified using only a language code, like <code>fr</code> or <code>en</code>, or they may be further qualified with a region code, like <code>en_US</code> or <code>en_GB</code>, which describes a regional variant of the same basic language. When you ask the i18n system for a string, it will select a string using the following algorithm:</p> + +<ol> + <li>if there is a <code>messages.json</code> file for the exact current locale, and it contains the string, return it.</li> + <li>Otherwise, if the current locale is qualified with a region (e.g. <code>en_US</code>) and there is a <code>messages.json</code> file for the regionless version of that locale (e.g. <code>en</code>), and that file contains the string, return it.</li> + <li>Otherwise, if there is a <code>messages.json</code> file for the <code>default_locale</code> defined in the <code>manifest.json</code>, and it contains the string, return it.</li> + <li>Otherwise return an empty string.</li> +</ol> + +<p>Take the following example:</p> + +<ul class="directory-tree"> + <li>extension-root-directory/ + <ul> + <li>_locales + <ul> + <li>en_GB + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "colour", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + en + + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "color", "description": "Color." }, ... }</code></li> + </ul> + </li> + </ul> + </li> + <li>fr + <ul> + <li>messages.json + <ul> + <li><code>{ "colorLocalised": { "message": "<span lang="fr">couleur</span>", "description": "Color." }, ...}</code></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> +</ul> + +<p>Suppose the <code>default_locale</code> is set to <code>fr</code>, and the browser's current locale is <code>en_GB</code>:</p> + +<ul> + <li>If the extension calls <code>getMessage("colorLocalised")</code>, it will return "colour".</li> + <li>If "colorLocalised" were not present in <code>en_GB</code>, then <code>getMessage("colorLocalised")</code>, would return "color", not "couleur".</li> +</ul> + +<h2 id="Mensagens_predefinidas">Mensagens predefinidas</h2> + +<p>The i18n module provides us with some predefined messages, which we can call in the same way as we saw earlier in {{anch("Calling message strings from manifests and extension CSS")}}. For example:</p> + +<pre>__MSG_extensionName__</pre> + +<p>Predefined messages use exactly the same syntax, except with <code>@@</code> before the message name, for example</p> + +<pre>__MSG_@@ui_locale__</pre> + +<p>The following table shows the different available predefined messages:</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Nome da mensagem</th> + <th scope="col">Descrição</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>@@extension_id</code></td> + <td> + <p>The extension's internally-generated UUID. You might use this string to construct URLs for resources inside the extension. Even unlocalized extensions can use this message.</p> + + <p>You can't use this message in a manifest file.</p> + + <p>Also note that this ID is <em>not</em> the add-on ID returned by {{WebExtAPIRef("runtime.id")}}, and that can be set using the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a> key in manifest.json. It's the generated UUID that appears in the add-on's URL. This means that you can't use this value as the <code>extensionId</code> parameter to {{WebExtAPIRef("runtime.sendMessage()")}}, and can't use it to check against the <code>id</code> property of a {{WebExtAPIRef("runtime.MessageSender")}} object.</p> + </td> + </tr> + <tr> + <td><code>@@ui_locale</code></td> + <td>The current locale; you might use this string to construct locale-specific URLs.</td> + </tr> + <tr> + <td><code>@@bidi_dir</code></td> + <td>The text direction for the current locale, either "ltr" for left-to-right languages such as English or "rtl" for right-to-left languages such as Arabic.</td> + </tr> + <tr> + <td><code>@@bidi_reversed_dir</code></td> + <td>If the <code>@@bidi_dir</code> is "ltr", then this is "rtl"; otherwise, it's "ltr".</td> + </tr> + <tr> + <td><code>@@bidi_start_edge</code></td> + <td>If the <code>@@bidi_dir</code> is "ltr", then this is "left"; otherwise, it's "right".</td> + </tr> + <tr> + <td><code>@@bidi_end_edge</code></td> + <td>If the <code>@@bidi_dir</code> is "ltr", then this is "right"; otherwise, it's "left".</td> + </tr> + </tbody> +</table> + +<p>Going back to our earlier example, it would make more sense to write it like this:</p> + +<pre class="brush: css">header { + background-image: url(../images/__MSG_@@ui_locale__/header.png); +}</pre> + +<p>Now we can just store our local specific images in directories that match the different locales we are supporting — en, de, etc. — which makes a lot more sense.</p> + +<p>Let's look at an example of using <code>@@bidi_*</code> messages in a CSS file:</p> + +<pre class="brush: css">body { + direction: __MSG_@@bidi_dir__; +} + +div#header { + margin-bottom: 1.05em; + overflow: hidden; + padding-bottom: 1.5em; + padding-__MSG_@@bidi_start_edge__: 0; + padding-__MSG_@@bidi_end_edge__: 1.5em; + position: relative; +}</pre> + +<p>For left-to-right languages such as English, the CSS declarations involving the predefined messages above would translate to the following final code lines:</p> + +<pre class="brush: css">direction: ltr; +padding-left: 0; +padding-right: 1.5em; +</pre> + +<p>For a right-to-left language like Arabic, you'd get:</p> + +<pre class="brush: css">direction: rtl; +padding-right: 0; +padding-left: 1.5em;</pre> + +<h2 id="Testar_a_sua_extensão">Testar a sua extensão</h2> + +<p>Starting in Firefox 45, you can install extensions temporarily from disk — see <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Packaging_and_installation#Loading_from_disk">Loading from disk</a>. Do this, and then try testing out our <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> extension. Go to one of your favourite websites and click a link to see if a notification appears reporting the URL of the clicked link.</p> + +<p>Next, change Firefox's locale to one supported in the extension that you want to test.</p> + +<ol> + <li>Open "about:config" in Firefox, and search for the <code>intl.locale.requested</code> preference (bear in mind that before Firefox 59, this pref is called <code>general.useragent.locale</code>).</li> + <li>If the preference exists, double-click it (or press Return/Enter) to select it, enter the language code for the locale you want to test, then click "OK" (or press Return/Enter). For example in our example extension, "en" (English), "de" (German), "nl" (Dutch), and "ja" (Japanese) are supported. You can also set the value to an empty string (<code>""</code>), which will cause the browser to use the OS default locale.</li> + <li>If the <code>intl.locale.requested</code> preference does not exist, right-click the list of preferences (or activate the context menu using the keyboard), and choose "New" followed by "String". Enter <code>intl.locale.requested</code> for the preference name and, "de", or "nl", etc. for the preference value, as described in step 2 above.</li> + <li>Search for <code>intl.locale.matchOS</code> and, if the preference exists and has the value <code>true</code>, double-click it so that it is set to <code>false</code>.</li> + <li>Restart your browser to complete the change.</li> +</ol> + +<div class="note"> +<p><strong>Nota</strong>: This works to change the browser's locale, even if you haven't got the <a href="https://addons.mozilla.org/en-US/firefox/language-tools/">language pack</a> installed for that language. You'll just get the browser UI in your default language if this is the case.</p> +</div> + +<ol> +</ol> + +<div class="note"> +<p><strong>Nota:</strong> To change the result of <code>getUILanguage</code> the language pack is required, since it reflects the browser UI language and not the language used for extension messages.</p> +</div> + +<p>Load the extension temporarily from disk again, then test your new locale:</p> + +<ul> + <li>Visit "about:addons" again — you should now see the extension listed, with its icon, plus name and description in the chosen language.</li> + <li>Test your extension again. In our example, you'd go to another website and click a link, to see if the notification now appears in the chosen language.</li> +</ul> + +<p>{{EmbedYouTube("R7--fp5pPGg")}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/browser_action/index.html b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/browser_action/index.html new file mode 100644 index 0000000000..41b720af8b --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/browser_action/index.html @@ -0,0 +1,236 @@ +--- +title: browser_action +slug: Mozilla/Add-ons/WebExtensions/manifest.json/browser_action +tags: + - Extensões + - Extensões da Web + - Extras +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/browser_action +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Tipo</th> + <td><code>Objeto</code></td> + </tr> + <tr> + <th scope="row">Obrigatório</th> + <td>Não</td> + </tr> + <tr> + <th scope="row">Exemplo</th> + <td> + <pre class="brush: json no-line-numbers"> +"browser_action": { + "browser_style": true, + "default_icon": { + "16": "button/geo-16.png", + "32": "button/geo-32.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html", + "theme_icons": [{ + "light": "icons/geo-32-light.png", + "dark": "icons/geo-32.png", + "size": 32 + }] +}</pre> + </td> + </tr> + </tbody> +</table> + +<p>A browser action is a button that your extension adds to the browser's toolbar. The button has an icon, and may optionally have a popup whose content is specified using HTML, CSS, and JavaScript.</p> + +<p>If you supply a popup, then the popup is opened when the user clicks the button, and your JavaScript running in the popup can handle the user's interaction with it. If you don't supply a popup, then a click event is dispatched to your extension's <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background scripts</a> when the user clicks the button.</p> + +<p>You can also create and manipulate browser actions programmatically using the <a href="/en-US/Add-ons/WebExtensions/API/browserAction">browserAction API</a>.</p> + +<h2 id="Sintaxe">Sintaxe</h2> + +<p>The <code>browser_action</code> key is an object that may have any of the following properties, all optional:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Nome</th> + <th scope="col">Tipo</th> + <th scope="col">Descrição</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>browser_style</code></td> + <td><code>Booliano</code></td> + <td> + <div class="geckoVersionNote">Novo no Firefox 48</div> + + <p>Optional, defaulting to <code>false</code>.</p> + + <p>Use this to include a stylesheet in your popup that will make it look consistent with the browser's UI and with other extensions that use the <code>browser_style</code> property. Although this key defaults to <code>false</code>, it's recommended that you include it and set it to <code>true</code>.</p> + + <p>In Firefox, the stylesheet can be seen at chrome://browser/content/extension.css, or chrome://browser/content/extension-mac.css on OS X.</p> + + <p>The <a href="https://firefoxux.github.io/StyleGuide/#/controls">Firefox Style Guide</a> describes the classes you can apply to elements in the popup in order to get particular styles.</p> + + <p>The <a href="https://github.com/mdn/webextensions-examples/tree/master/latest-download">latest-download</a> example extension uses <code>browser_style</code> in its popup.</p> + </td> + </tr> + <tr> + <td><code>default_area</code></td> + <td><code>String</code></td> + <td> + <div class="geckoVersionNote">Novo no Firefox 54</div> + + <p>Defines the part of the browser in which the button is initially placed. This is a string that may take one of four values:</p> + + <ul> + <li>"navbar": the button is placed in the main browser toolbar, alongside the URL bar.</li> + <li>"menupanel": the button is placed in a popup panel.</li> + <li>"tabstrip": the button is placed in the toolbar that contains browser tabs.</li> + <li>"personaltoolbar": the button is placed in the bookmarks toolbar.</li> + </ul> + + <p>This property is only supported in Firefox.</p> + + <p>This property is optional, and defaults to "navbar".</p> + + <p>An extension can't change the location of the button after it has been installed, but the user may be able to move the button using the browser's built-in UI customization mechanism.</p> + </td> + </tr> + <tr> + <td><code>default_icon</code></td> + <td><code>Object</code> or <code>String</code></td> + <td> + <p>Use this to specify one or more icons for the browser action. The icon is shown in the browser toolbar by default.</p> + + <p>Icons are specified as URLs relative to the manifest.json file itself.</p> + + <p>You can specify a single icon file by supplying a string here:</p> + + <pre class="brush: json no-line-numbers"> +"default_icon": "path/to/geo.svg"</pre> + + <p>To specify multiple icons in different sizes, specify an object here. The name of each property is the icon's height in pixels, and must be convertible to an integer. The value is the URL. For example:</p> + + <pre class="brush: json no-line-numbers"> + "default_icon": { + "16": "path/to/geo-16.png", + "32": "path/to/geo-32.png" + }</pre> + + <p>See <a href="/en-US/Add-ons/WebExtensions/manifest.json/browser_action#Choosing_icon_sizes">Choosing icon sizes</a> for more guidance on this.</p> + </td> + </tr> + <tr> + <td><code>default_popup</code></td> + <td><code>String</code></td> + <td> + <p>The path to an HTML file containing the specification of the popup.</p> + + <p>The HTML file may include CSS and JavaScript files using <code><a href="/en-US/docs/Web/HTML/Element/link"><link></a></code> and <code><a href="/en-US/docs/Web/HTML/Element/script"><script></a></code> elements, just like a normal web page.</p> + + <p>Unlike a normal web page, JavaScript running in the popup can access all the <a href="/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> (subject, of course, to the extension having the appropriate <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a>).</p> + + <p>This is a <a href="/en-US/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">localizable property</a>.</p> + </td> + </tr> + <tr> + <td><code>default_title</code></td> + <td><code>String</code></td> + <td> + <p>Tooltip for the button, displayed when the user moves their mouse over it. If the button is added to the browser's menu panel, this is also shown under the app icon.</p> + + <p>This is a <a href="/en-US/Add-ons/WebExtensions/Internationalization#Internationalizing_manifest.json">localizable property</a>.</p> + </td> + </tr> + <tr> + <td><code>theme_icons</code></td> + <td><code>Array</code></td> + <td> + <p>This property enables you to specify different icons for dark and light themes.</p> + + <p>If this property is present, it's an array containing at least one <code>ThemeIcons</code> object. A <code>ThemeIcons</code> object contains three properties, all mandatory:</p> + + <dl> + <dt><code>"dark"</code></dt> + <dd>A URL pointing to an icon. This icon will be selected when themes with dark text are active (e.g. Firefox's Light theme, and the Default theme if no default_icon is specified).</dd> + <dt><code>"light"</code></dt> + <dd>A URL pointing to an icon. This icon will be selected when themes with light text are active (e.g. Firefox's Dark theme).</dd> + <dt><code>"size"</code></dt> + <dd>The size of the two icons in pixels.</dd> + </dl> + + <p>Icons are specified as URLs relative to the manifest.json file itself.</p> + + <p>Providing multiple <code>ThemeIcons</code> objects enables you to supply a set of icon pairs in different sizes.</p> + </td> + </tr> + </tbody> +</table> + +<h2 id="Escolher_os_tamanhos_do_ícone">Escolher os tamanhos do ícone</h2> + +<p>The browser action's icon may need to be displayed in different sizes in different contexts:</p> + +<ul> + <li>The icon is displayed by default in the browser toolbar, but the user can move it into the browser's menu panel (the panel that opens when the user clicks the "hamburger" icon). The icon in the toolbar is smaller than the icon in the menu panel.</li> + <li>On a high-density display like a Retina screen, icons needs to be twice as big.</li> +</ul> + +<p>If the browser can't find an icon of the right size in a given situation, it will pick the best match and scale it. Scaling may make the icon appear blurry, so it's important to choose icon sizes carefully.</p> + +<p>There are two main approaches to this. You can supply a single icon as an SVG file, and it will be scaled correctly:</p> + +<pre class="brush: json no-line-numbers">"default_icon": "path/to/geo.svg"</pre> + +<p>Alternatively, you can supply several icons in different sizes, and the browser will pick the best match.</p> + +<p>In Firefox:</p> + +<ul> + <li>The default height and width for icons in the toolbar is 16 * <code><a href="/en-US/docs/Web/API/Window/devicePixelRatio">window.devicePixelRatio</a></code>.</li> + <li>The default height and width for icons in the menu panel is 32 * <code><a href="/en-US/docs/Web/API/Window/devicePixelRatio">window.devicePixelRatio</a></code>.</li> +</ul> + +<p>So you can specify icons that match exactly, on both normal and Retina displays, by supplying three icon files, and specifying them like this:</p> + +<pre class="brush: json no-line-numbers"> "default_icon": { + "16": "path/to/geo-16.png", + "32": "path/to/geo-32.png", + "64": "path/to/geo-64.png" + }</pre> + +<p>If Firefox can't find an exact match for the size it wants, then it will pick the smallest icon specified that's bigger than the ideal size. If all icons are smaller than the ideal size, it will pick the biggest icon specified.</p> + +<h2 id="Exemplo">Exemplo</h2> + +<pre class="brush: json no-line-numbers">"browser_action": { + "default_icon": { + "16": "button/geo-16.png", + "32": "button/geo-32.png" + } +}</pre> + +<p>A browser action with just an icon, specified in 2 different sizes. The extension's background scripts can receive click events when the user clicks the icon using code like this:</p> + +<pre class="brush: js no-line-numbers"> browser.browserAction.onClicked.addListener(handleClick);</pre> + +<pre class="brush: json">"browser_action": { + "default_icon": { + "16": "button/geo-16.png", + "32": "button/geo-32.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" +}</pre> + +<p>A browser action with an icon, a title, and a popup. The popup will be shown when the user clicks the button.</p> + +<p>For a simple, but complete, extension that uses a browser action, see the <a href="/en-US/Add-ons/WebExtensions/Your_second_WebExtension">walkthrough tutorial</a>.</p> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p>{{Compat("webextensions.manifest.browser_action", 10)}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.html b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.html new file mode 100644 index 0000000000..3d52790362 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/browser_specific_settings/index.html @@ -0,0 +1,107 @@ +--- +title: applications +slug: Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings +tags: + - Extensões + - Extensões da Web + - Extras +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Tipo</th> + <td><code>Object</code></td> + </tr> + <tr> + <th scope="row">Obrigatório</th> + <td>Usually, no (but see also <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID#When_do_you_need_an_add-on_ID">When do you need an Add-on ID?</a>). Mandatory before Firefox 48 (desktop) and Firefox for Android.</td> + </tr> + <tr> + <th scope="row">Exemplo</th> + <td> + <pre class="brush: json no-line-numbers"> +"applications": { + "gecko": { + "id": "addon@example.com", + "strict_min_version": "42.0" + } +}</pre> + </td> + </tr> + </tbody> +</table> + +<h2 id="Descrição">Descrição</h2> + +<p>A chave <code>applications</code> contém chaves que são especificas de uma <em>application</em> de um anfitrião em particular.</p> + +<h3 id="Propriedadee_(Gecko)_do_Firefox">Propriedadee (Gecko) do Firefox</h3> + +<p>Currently this contains just one key, <code>gecko</code>, which may contain four string attributes:</p> + +<ul> + <li><code>id</code> is the extension ID. Optional from Firefox 48, mandatory before Firefox 48. See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">Extensions and the Add-on ID</a> to see when you need to specify an add-on ID.</li> + <li><code>strict_min_version</code>: minimum version of Gecko to support. Versions containing a "*" are not valid in this field. Defaults to "42a1".</li> + <li><code>strict_max_version</code>: maximum version of Gecko to support. If the Firefox version on which the extension is being installed or run is above this version, then the extension will be disabled, or not permitted to be installed. Defaults to "*", which disables checking for a maximum version.</li> + <li><code>update_url</code> is a link to an <a href="/en-US/Add-ons/Updates">extension update manifest</a>. Note that the link must begin with "https". This key is for managing extension updates yourself (i.e. not through AMO).</li> +</ul> + +<p>Consulte a lista das <a href="https://addons.mozilla.org/pt-PT/firefox/pages/appversions/">versões válidas de Gecko</a>.</p> + +<h4 id="Formato_da_Id._da_Extensão">Formato da Id. da Extensão</h4> + +<p>A Id. da extensão deve ser uma das seguintes:</p> + +<ul> + <li><a href="https://en.wikipedia.org/wiki/Universally_unique_identifier" title="Generating_GUIDs">GUID</a></li> + <li>A string formatted like an email address: <code class="plain">extensionname@example.org</code></li> +</ul> + +<p>The latter format is easier to generate and manipulate. Be aware that using a real email address here may attract spam.</p> + +<p>Por exemplo:</p> + +<pre class="brush:json;auto-links:false no-line-numbers">"id": "extensionname@example.org", + +"id": "{daf44bf7-a45e-4450-979c-91cf07434c3d}"</pre> + +<h3 id="Propriedades_do_Microsoft_Edge">Propriedades do Microsoft Edge</h3> + +<p>Microsoft Edge stores its browser specific settings in the <code>edge</code> subkey, which has the following properties:</p> + +<dl> + <dt><code>browser_action_next_to_addressbar</code></dt> + <dd> + <p>Boolean property which controls the placement of the <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_actions">browser action</a>.</p> + + <ul> + <li><code>true</code> is equivalent to setting <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action#Syntax">browser_action.default_area</a></code> to <code>navbar</code>.</li> + <li><code>false</code> is equivalent to setting <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action#Syntax">browser_action.default_area</a></code> to <code>menupanel</code>.</li> + </ul> + </dd> +</dl> + +<h2 id="Exemplos">Exemplos</h2> + +<p>Example with all possible keys. Note that most extensions will omit <code>strict_max_version</code> and <code>update_url</code>.</p> + +<pre class="brush: json no-line-numbers">"applications": { + "gecko": { + "id": "addon@example.com", + "strict_min_version": "42.0", + "strict_max_version": "50.*", + "update_url": "https://example.com/updates.json" + }, + "edge": { + <code>"browser_action_next_to_addressbar": true</code> + } +}</pre> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.manifest.browser_specific_settings")}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/devtools_page/index.html b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/devtools_page/index.html new file mode 100644 index 0000000000..6f53c96b01 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/devtools_page/index.html @@ -0,0 +1,42 @@ +--- +title: devtools_page +slug: Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Tipo</th> + <td><code>String</code></td> + </tr> + <tr> + <th scope="row">Obrigatório</th> + <td>Não</td> + </tr> + <tr> + <th scope="row">Exemplo</th> + <td> + <pre class="brush: json no-line-numbers"> +"devtools_page": "devtools/my-page.html"</pre> + </td> + </tr> + </tbody> +</table> + +<p>Utilziae esta chave para permitir que a sua extensão amplie as <em>devtools </em>do navegador integradas.</p> + +<p>esta chave é definida como um URL para um ficheiro HTML. O ficheiro HTML deverá ser incorporado com a extensão, e o URL é relativo à raiz das extensões.</p> + +<p>Consulte <a href="/pt-PT/Add-ons/WebExtensions/Extensão_das_ferramentas_de_desenvolvimento">Extensão das ferramentas de desenvolvimento</a> para saber mais.</p> + +<h2 id="Exemplo">Exemplo</h2> + +<pre class="brush: json no-line-numbers">"devtools_page": "devtools/my-page.html"</pre> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p class="hidden">A tabela de compatibilidade nesta página é gerada a partir dos dados estruturados. Se pretender contribuir para os dados, por favor, consulte <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> e envie-nos um pedido de submissão (<em>pull</em>).</p> + +<p>{{Compat("webextensions.manifest.devtools_page")}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/icones/index.html b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/icones/index.html new file mode 100644 index 0000000000..c9fd687771 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/icones/index.html @@ -0,0 +1,78 @@ +--- +title: Ícones (icons) +slug: Mozilla/Add-ons/WebExtensions/manifest.json/icones +tags: + - Extensões + - Extensões da Web + - Extras +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/icons +--- +<div>{{AddonSidebar}}</div> + +<table class="fullwidth-table standard-table"> + <tbody> + <tr> + <th scope="row" style="width: 30%;">Tipo</th> + <td><code>Objeto</code></td> + </tr> + <tr> + <th scope="row">Obrigatório</th> + <td>Não</td> + </tr> + <tr> + <th scope="row">Exemplo</th> + <td> + <pre class="brush: json no-line-numbers"> +"icons": { + "48": "icon.png", + "96": "icon@2x.png" +}</pre> + </td> + </tr> + </tbody> +</table> + +<p>The <code>icons</code> key specifies icons for your extension. Those icons will be used to represent the extension in components such as the Add-ons Manager.</p> + +<p>It consists of key-value pairs of image size in px and image path relative to the root directory of the extension.</p> + +<p>If <code>icons</code> is not supplied, a standard extension icon will be used by default.</p> + +<p>You should supply at least a main extension icon, ideally 48x48 px in size. This is the default icon that will be used in the Add-ons Manager. You may, however, supply icons of any size and Firefox will attempt to find the best icon to display in different components.</p> + +<p>Firefox will consider the screen resolution when choosing an icon. To deliver the best visual experience to users with high-resolution displays, such as Retina displays, provide double-sized versions of all your icons.</p> + +<h2 id="Exemplo">Exemplo</h2> + +<p>The keys in the <code>icons</code> object specify the icon size in px, values specify the relative icon path. This example contains a 48px extension icon and a larger version for high-resolution displays.</p> + +<pre class="brush: json no-line-numbers">"icons": { + "48": "icon.png", + "96": "icon@2x.png" +}</pre> + +<h2 id="SVG">SVG</h2> + +<p>You can use SVG and the browser will scale your icon appropriately. There are currently two caveats though:</p> + +<ol> + <li>You need to specify a viewBox in the image. E.g.: + <pre class="brush: html"><svg viewBox="0 0 48 48" width="48" height="48" ...</pre> + </li> + <li>Even though you can use one file, you still need to specify various size of the icon in your manifest. E.g.: + <pre class="brush: json">"icons": { + "48": "icon.svg", + "96": "icon.svg" +}</pre> + </li> +</ol> + +<div class="note"> +<p>If you are using a program like Inkscape for creating SVG, you might want to save it as a "plain SVG". Firefox might be confused by various special namespaces and not display your icon.</p> +</div> + +<h2 id="Compatibilidade_de_navegador">Compatibilidade de navegador</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.manifest.icons")}}</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/index.html b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/index.html new file mode 100644 index 0000000000..4f8e087281 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/manifest.json/index.html @@ -0,0 +1,132 @@ +--- +title: manifest.json +slug: Mozilla/Add-ons/WebExtensions/manifest.json +tags: + - Add-ons + - Extensões + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json +--- +<div>{{AddonSidebar}}</div> + +<p>O ficheiro manifest.json é o único ficheiro que deve ser incluído em extensões que usem APIs de WebExtension.</p> + +<p>Com o <code>manifest.json</code>, é possível especificar metadados sobre a extensão a que pertence, tal como o nome, a versão, e funcionalidades como <em>scripts </em>de <em>background</em>, <em>scripts</em> de conteúdo, e ações de <em>browser</em>.</p> + +<p>O <code>manifest.json</code><em> </em>é um ficheiro em formato <a href="https://wiki.developer.mozilla.org/en-US/docs/Glossary/JSON">JSON</a>, mas também suporta comentários do tipo "//".</p> + +<h2 id="Propriedades_do_manifest.json">Propriedades do manifest.json</h2> + +<p>Seguem-se as propriedades que o <code>manifest.json</code> suporta:</p> + +<div class="twocolumns">{{ ListSubpages ("/en-US/Add-ons/WebExtensions/manifest.json") }}</div> + +<div class="twocolumns"></div> + +<h3 id="Notas_sobre_propriedades_do_manifest.json">Notas sobre propriedades do manifest.json</h3> + +<ul> + <li><code>as únicas <strong>propriedades obrigatórias</strong> são "manifest_version"</code>, <code>"version"</code>, e <code>"name"</code>. <code>"default_locale"</code> só é obrigatório se existir uma pasta "_locales". Caso contrário, a propriedade não pode existir.</li> + <li> + <p><code>"browser_specific_settings"</code> não é compatível com Google Chrome.</p> + </li> +</ul> + +<h3 id="Como_aceder_a_propriedades_manifest.json_em_runtime">Como aceder a propriedades manifest.json em <em>runtime</em></h3> + +<p>É possível aceder ao <code>manifest.json</code> de uma extensão a partir de um <em>script</em><em> </em>da mesma, com a função de JavaScript {{WebExtAPIRef("runtime.getManifest()")}}:</p> + +<pre class="brush: js notranslate">browser.runtime.getManifest().version;</pre> + +<h2 id="Compatibilidade_de_browsers">Compatibilidade de <em>browsers</em></h2> + +<p>{{Compat("webextensions.manifest")}}</p> + +<h2 id="Exemplo">Exemplo</h2> + +<p>Os exemplos seguintes demonstram como funcionam algumas propriedades comuns nos <em>manifest.json.</em> </p> + +<div class="blockIndicator note"> +<p><strong>Nota:</strong> Estes exemplos não funcionam se forem simplesmente copiados e colados. As propriedades necessárias são determinadas pelas características de cada extensão</p> +</div> + +<p>Para ver exemplos completos de extensões, veja a página <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Examples">Exemplos de extensões</a>.</p> + +<pre class="brush: json notranslate">{ + "applications": { + "gecko": { + "id": "addon@example.com", + "strict_min_version": "42.0" + } + }, + + "background": { + "scripts": ["jquery.js", "my-background.js"], + "page": "my-background.html" + }, + + "browser_action": { + "default_icon": { + "19": "button/geo-19.png", + "38": "button/geo-38.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" + }, + + "commands": { + "toggle-feature": { + "suggested_key": { + "default": "Ctrl+Shift+Y", + "linux": "Ctrl+Shift+U" + }, + "description": "Send a 'toggle-feature' event" + } + }, + + "content_security_policy": "script-src 'self' https://example.com; object-src 'self'", + + "content_scripts": [ + { + "exclude_matches": ["*://developer.mozilla.org/*"], + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } + ], + + "default_locale": "en", + + "description": "...", + + "icons": { + "48": "icon.png", + "96": "icon@2x.png" + }, + + "manifest_version": 2, + + "name": "...", + + "page_action": { + "default_icon": { + "19": "button/geo-19.png", + "38": "button/geo-38.png" + }, + "default_title": "Whereami?", + "default_popup": "popup/geo.html" + }, + + "permissions": ["webNavigation"], + + "version": "0.1", + + "web_accessible_resources": ["images/my-image.png"] +}</pre> + +<h2 id="Compatibilidade_de_browsers_2">Compatibilidade de <em>browsers</em></h2> + +<p>Consulte a <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json">tabela de compatibilidade de browsers do manifest.json</a> para saber que <em>browsers </em>suportam cada propriedade do <code>manifest.json</code>.</p> + +<h2 id="Ver_também">Ver também</h2> + +<p>{{WebExtAPIRef("permissions")}} JavaScript API</p> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/o_que_sao_webextensions/index.html b/files/pt-pt/mozilla/add-ons/webextensions/o_que_sao_webextensions/index.html new file mode 100644 index 0000000000..c2d7ef5d71 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/o_que_sao_webextensions/index.html @@ -0,0 +1,59 @@ +--- +title: O que são extensões? +slug: Mozilla/Add-ons/WebExtensions/O_que_sao_WebExtensions +tags: + - Extensões + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/What_are_WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<p>Uma extensão adiciona funcionalidades e funções a um navegador. É criada, utilizando a tecnologia padrão baseada na Web - CSS, HTML e JavaScript. Esta tira vantagem de algumas APIs da Web, como JavaScript pode em uma página da web, mas uma extensão também tem acesso ao seu próprio conjunto de APIs de JavaScript. Isto significa que pode fazer muito mais numa extensão do que pode com o código numa página da Web. Aqui estão apenas alguns exemplos das coisas que pode fazer.</p> + +<p><strong>Melhore ou complemente um site da Web</strong>: utilize um extra para fornecer funcionalidades adicionais no navegador ou informação do seu site da Web. Permita que os utilizadores recolham detalhes das páginas que eles visitam, para melhorar o serviço que oferece.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15808/Amazon_add_on.png"></p> + +<p>Exemplos: <a href="https://addons.mozilla.org/en-US/firefox/addon/amazon-browser-bar/">Amazon Assistant para Firefox</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/onenote-clipper/">OneNote Web Clipper</a>, e <a href="https://addons.mozilla.org/en-US/firefox/addon/grammarly-1/">Grammarly for Firefox</a></p> + +<p><strong>Deixe que os utilizadores mostrem a sua personalidade</strong>: Browser extensions can manipulate the content of pages browsed by a user. Help the user add a favorite logo or picture as the background to every page they visit. Extensions also give you the ability to update the look of the Firefox UI. (Update the Firefox UI using standalone <a href="https://developer.mozilla.org/en-US/Add-ons/Themes/Theme_concepts">theme add-ons</a> too).</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15809/MyWeb_New_Tab_add_on.png" style="height: 398px; width: 540px;"></p> + +<p>Exemplos: <a href="https://addons.mozilla.org/en-US/firefox/addon/myweb-new-tab/">MyWeb New Tab</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/tabliss/">Tabliss</a>, e <a href="https://addons.mozilla.org/en-US/firefox/addon/vivaldifox/">VivaldiFox</a></p> + +<p><strong>Adicionar ou remover conteúdo das páginas da Web</strong>: You might want to help users block intrusive ads from web pages, provide access to a travel guide whenever a country or city is mentioned in a web page, or reformat page content to offer a consistent reading experience. With the ability to access and update both a page’s HTML and CSS, you can help users see the web the way they want to.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15807/ublock_origin_add_on.png" style="height: 480px; width: 640px;"></p> + +<p>Exemplos: <a href="https://addons.mozilla.org/en-US/firefox/addon/ublock-origin/">uBlock Origin</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/reader/">Reader</a>, e <a href="https://addons.mozilla.org/en-US/firefox/addon/toolbox-google-play-store/">Toolbox para Google Play Store™</a></p> + +<p><strong>Adicionar ferramentas e novas funcionalidades de navegação</strong>: Add new features to a taskboard, or generate QR code images from URLs, hyperlinks, or page text. With flexible UI options and the power of the WebExtensions APIs you can easily add new features to a browser. And, you can enhance almost any website’s features or functionality, it doesn't have to be your website.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15806/QR_Code_Image_Generator_add_on.png"></p> + +<p>Examples: <a href="https://addons.mozilla.org/en-US/firefox/addon/qr-code-image-generator/">QR Code Image Generator</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/swimlanes-for-trello/">Swimlanes for Trello</a>, and <a href="https://addons.mozilla.org/en-US/firefox/addon/tomato-clock/">Tomato Clock</a></p> + +<p><strong>Jogos</strong>: Offer traditional computer games, with off-line play features, but also explore new game possibilities, for example, by incorporating gameplay into everyday browsing.</p> + +<p> <img alt="" src="https://mdn.mozillademos.org/files/15805/Asteroids_in_Popup_add_on%20.png" style="height: 438px; width: 700px;"></p> + +<p>Examples: <a href="https://addons.mozilla.org/en-US/firefox/addon/asteroids-in-popup/">Asteroids in Popup</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/solitaire-card-game-new-tab/">Solitaire Card Game New Tab</a>, and <a href="https://addons.mozilla.org/en-US/firefox/addon/2048-prime/">2048 Prime</a>.</p> + +<p><strong>Adicionar ferramentas de desenvolvimento</strong>: You may provide web development tools as your business or have developed a useful technique or approach to web development that you want to share. Either way, you can enhance the built-in Firefox developer tools by adding a new tab to the developer toolbar.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15804/aXe_Developer_Tools_add_on.png" style="height: 261px; width: 700px;"></p> + +<p>Examples: <a href="https://addons.mozilla.org/en-US/firefox/addon/web-developer/">Web Developer</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/react-devtools/">Web React Developer Tools</a>, and <a href="https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/">aXe Developer Tools</a></p> + +<p>Extensions for Firefox are built using the WebExtensions APIs, a cross-browser system for developing extensions. To a large extent, the API is compatible with the <a class="external external-icon" href="https://developer.chrome.com/extensions">extension API</a> supported by Google Chrome and Opera. Extensions written for these browsers will in most cases run in Firefox or Microsoft Edge with just a few <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Porting_a_Google_Chrome_extension">changes</a>. The API is also fully compatible with <a href="/en-US/Firefox/Multiprocess_Firefox">multiprocess Firefox</a>.</p> + +<p>If you have ideas or questions, or need help migrating a legacy add-on to WebExtensions APIs, you can reach us on the <a class="external external-icon" href="https://mail.mozilla.org/listinfo/dev-addons">dev-addons mailing list</a> or in <a href="irc://irc.mozilla.org/extdev">#extdev</a> on <a class="external external-icon" href="https://wiki.mozilla.org/IRC">IRC</a>.</p> + +<h2 id="E_a_seguir">E a seguir?</h2> + +<ul> + <li>Consulte o desenvolvimento de uma extensão simples em <a href="https://developer.mozilla.org/pt-PT/Add-ons/WebExtensions/A_sua_primeira_extensao">A sua primeira extensão</a>.</li> + <li>Saiba sobre a estrutura de uma extensão em <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">Anatomia de uma extensão</a>.</li> + <li>Experimente alguns exemplos de extensões em <a href="/pt-PT/Add-ons/WebExtensions/Exemplos_extensoes">Exemplos de extensões</a>.</li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/primeiros_passos_com_web-ext/index.html b/files/pt-pt/mozilla/add-ons/webextensions/primeiros_passos_com_web-ext/index.html new file mode 100644 index 0000000000..a6eb21ffc1 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/primeiros_passos_com_web-ext/index.html @@ -0,0 +1,304 @@ +--- +title: Primeiros passos com web-ext +slug: Mozilla/Add-ons/WebExtensions/Primeiros_passos_com_web-ext +tags: + - Extensão da Web + - Ferramentas + - Guía + - Instalação + - Testes + - empacotamento + - web-ext +translation_of: Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext +--- +<div>{{AddonSidebar}}</div> + +<p class="summary">web-ext é uma ferramenta da linha de comando desenhada para acelerar várias partes do processo de desenvolvimento da extensão, tornado o desenvolvimento mais rápido e fácil. Este artigo explica como instalar e utilizar web-ext.</p> + +<h2 id="Instalação">Instalação</h2> + +<p>web-ext is a node-based application that you install with the <a href="https://nodejs.org/">nodejs/npm</a> tool. Install web-ext using the following command:</p> + +<pre class="brush: bash"><code>npm install --global web-ext</code></pre> + +<p>web-ext requires the current <a href="https://github.com/nodejs/Release#release-schedule">LTS</a> (long-term support) version of <a href="https://nodejs.org/">NodeJS</a>.</p> + +<p>To test whether the installation worked run the following command, which displays the web-ext version number:</p> + +<pre class="brush: bash"><code>web-ext --version</code></pre> + +<h2 id="Utilizar_web-ext">Utilizar web-ext</h2> + +<p>Before you start using web-ext, locate an example extension to use—if you don't have one, use one from the <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repo.</p> + +<h3 id="Testar_uma_extensão">Testar uma extensão</h3> + +<p>Test an extension in Firefox by <code>cd</code>'ing into your extension's root directory and entering:</p> + +<pre class="brush: bash"><code>web-ext run</code></pre> + +<p>This starts Firefox and loads the extension temporarily in the browser, just as you can on the <a href="/en-US/docs/Tools/about:debugging#Add-ons">about:debugging page</a>.</p> + +<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_run">run reference guide</a> to learn more.</p> + +<h3 id="Recarregamento_automático_da_extensão">Recarregamento automático da extensão</h3> + +<p>The <code>run</code> command watches your source files and tells Firefox to reload the extension after you edit and save a file. For example, if you changed the <code>name</code> property in your <code>manifest.json</code> file, Firefox displays the new name. This makes it easy to try out new features because you can see the effect immediately. The automatic reloading feature is active by default, you use it like this:</p> + +<pre class="brush: bash"><code>web-ext run</code></pre> + +<p>You can also press the <code>r</code> key in the <code>web-ext</code> terminal to trigger an extension reload.</p> + +<p>If you experience unexpected behavior with the reloading feature, please <a href="https://github.com/mozilla/web-ext/issues">file a bug</a>. You can also disable reloading like this:</p> + +<pre class="brush: bash"><code>web-ext run --no-reload</code></pre> + +<div class="note"> +<p>O reccaregamento da extensão só é suportado a paratir da versão do Firefox 49 ou superior .</p> +</div> + +<h3 id="Testar_em_versões_diferentes_do_Firefox">Testar em versões diferentes do Firefox</h3> + +<p>To run your extension in a version of <a href="https://www.mozilla.org/en-US/firefox/">Firefox Desktop</a> other than the default, use the <code>--firefox</code> option to specify a full path to the binary file. Here is an example for Mac OS:</p> + +<pre class="brush: bash">web-ext run --firefox=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin</pre> + +<p>On Windows, the path needs to include <code>firefox.exe</code>, for example:</p> + +<pre class="brush: bash">web-ext run --firefox="C:\Program Files\Mozilla Firefox\firefox.exe"</pre> + +<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_run">run command</a> reference to learn more.</p> + +<h3 id="Testar_no_Firefox_48">Testar no Firefox 48</h3> + +<p>Firefox 48 was the first stable version to use the WebExtension platform, but it doesn't allow <code>web-ext</code> to install an extension remotely. You need to run your extension in Firefox 48 using:</p> + +<pre class="brush: bash">web-ext run --pre-install</pre> + +<h3 id="Testar_no_Firefox_para_Android">Testar no Firefox para Android</h3> + +<p>To run your extension in <a href="https://www.mozilla.org/en-US/firefox/mobile/">Firefox for Android</a>, follow these instructions to <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android#Set_up_your_computer_and_Android_emulator_or_device">set up your computer and device</a>.</p> + +<p>With your device connected to your development computer, run:</p> + +<pre class="brush: bash">web-ext run --target=firefox-android</pre> + +<p>This command displays the device ID for your connected Android device or devices. If you don't see a list of device IDs, make sure you set up the device for development correctly.</p> + +<p><span style="background-color: #ffffff;">N</span>ow, add the device ID to the command:</p> + +<pre class="brush: bash">web-ext run --target=firefox-android --android-device=<device ID></pre> + +<p>If you've multiple versions of Firefox installed, you may need to choose a specific version. For example:</p> + +<pre class="brush: bash">web-ext run --target=firefox-android ... --firefox-apk=org.mozilla.firefox</pre> + +<p>The first time you run this command, you may need to grant Android permissions for the APK. This is because the command needs read / write access to the device storage, so that Firefox for Android can run on a temporary profile. The <code>web-ext</code> output guides you in how to grant these permissions.</p> + +<p>The <code>web-ext</code> command does not alter any of your existing Firefox for Android preferences or data. To see more information about how <code>web-ext</code> is interacting with your device, run the command with <code>--verbose</code>.</p> + +<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_run">run command</a> reference to learn more.</p> + +<h3 id="Depurar_no_Firefox_para_Android">Depurar no Firefox para Android</h3> + +<p>When using <code>web-ext run</code> to test an extension on Firefox for Android, you'll notice a message like this in the console output:</p> + +<pre>You can connect to this Android device on TCP port 51499 +</pre> + +<p>This is a remote debugger port that you can <a href="/en-US/docs/Tools/Remote_Debugging/Firefox_for_Android#Connecting">connect to with Firefox's developer tools</a>. In this case, you'd connect to host <code>localhost</code> on port <code>51499</code>.</p> + +<p>See <a href="/en-US/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android#Debug_your_extension">this guide</a> for more information about debugging an extension on Firefox for Android.</p> + +<h3 id="Testar_extensões_não_assinadas">Testar extensões não assinadas</h3> + +<p>When you execute <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_run">web-ext run</a>, the extension gets installed temporarily until you close Firefox. This does not violate any signing restrictions. If instead you create a zip file with <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_build">web-ext build</a> and try to install it into Firefox, you will see an error telling you that the add-on is not signed. You will need to use an <a href="https://wiki.mozilla.org/Addons/Extension_Signing#Unbranded_Builds">unbranded build</a> or use a <a href="https://www.mozilla.org/en-US/firefox/developer/">development build</a> to install unsigned extensions.</p> + +<h3 id="Utilizar_um_perfil_personalizado">Utilizar um perfil personalizado</h3> + +<p>By default, the <code>run</code> command will create a temporary Firefox profile. To run your extension with a specific profile use the <code>--firefox-profile</code> option, like this:</p> + +<pre class="brush: bash">web-ext run --firefox-profile=your-custom-profile</pre> + +<p>This option accepts a string containing the name of your profile or an absolute path to the profile directory. This is helpful if you want to manually configure some settings that will always be available to the <code>run</code> command.</p> + +<h3 id="Manter_alterações_de_perfil">Manter alterações de perfil</h3> + +<p>The <code>run</code> command does not save any changes made to the custom profile specified by <code>--firefox-profile</code>. To keep changes, add this option:</p> + +<pre class="brush: bash">web-ext run --keep-profile-changes --firefox-profile=your-custom-profile</pre> + +<p>This may be helpful if your extension has many different run states.</p> + +<div class="warning"> +<p>This option makes the profile specified by <code>--firefox-profile</code> completely insecure for daily use. It turns off auto-updates and allows silent remote connections, among other things. Specifically, it will make destructive changes to the profile that are required for <code>web-ext</code> to operate.</p> +</div> + +<h3 id="Empacotar_a_sua_extensão">Empacotar a sua extensão</h3> + +<p>Once you've tested your extension and verified that it's working, you can turn it into a package for submitting to <a href="https://addons.mozilla.org">addons.mozilla.org</a> using the following command:</p> + +<pre class="brush: bash"><code>web-ext build</code></pre> + +<p>This outputs a full path to the generated <code>.zip</code> file that can be loaded into a browser.</p> + +<div class="warning"> +<p>The generated <code>.zip</code> file doesn't work on Firefox without signing or adding <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">applications</a>.gecko.id</code> key into <code><a href="/en-US/Add-ons/WebExtensions/manifest.json">manifest.json</a></code>. For more information, please refer <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">WebExtensions and the Add-on ID</a> page.</p> +</div> + +<p><code>web-ext build</code> is designed to ignore files that are commonly not wanted in packages, such as <code>.git</code>, <code>node_modules</code>, and other artifacts.</p> + +<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_build">build reference guide</a> to learn more.</p> + +<h3 id="Assinar_a_sua_extensão_para_distribuição">Assinar a sua extensão para distribuição</h3> + +<p>As an alternative to publishing your extension on <a href="https://addons.mozilla.org/">addons.mozilla.org</a>, you can self-host your package file but it needs to be <a href="https://developer.mozilla.org/Add-ons/Distribution">signed by Mozilla</a> first. The following command packages and signs a ZIP file, then returns it as a signed XPI file for distribution:</p> + +<pre class="brush: bash"><code>web-ext sign --api-key=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET </code></pre> + +<p>The API options are required to specify your <a href="https://addons.mozilla.org/en-US/developers/addon/api/key/">addons.mozilla.org credentials</a>.</p> + +<ul> + <li><code>--api-key</code>: the API key (JWT issuer) from <code>addons.mozilla.org</code> needed to sign the extension. This is a string that will look something like <code>user:12345:67</code>.</li> + <li><code>--api-secret</code>: the API secret (JWT secret) from <code>addons.mozilla.org</code> needed to sign the extension. This is a string that will look something like <code>634f34bee43611d2f3c0fd8c06220ac780cff681a578092001183ab62c04e009</code>.</li> +</ul> + +<p>See the <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_sign">sign reference guide</a> to learn more.</p> + +<h3 id="Assinar_as_extensões_sem_uma_Id._explicita">Assinar as extensões sem uma Id. explicita</h3> + +<p><code>web-ext</code> supports signing extensions that do not declare the <a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">applications.gecko.id</a> property in their manifest. The first time you sign an extension without an explicit ID, <a href="https://addons.mozilla.org/">addons.mozilla.org</a> will generate an ID and <code>web-ext</code> will save it to <code>.web-extension-id</code> in the working directory. You should save the ID file so that you can sign future versions of the same extension. If you lose the ID file, you will have to add back the <code>applications.gecko.id</code> property or use the <code>--id</code> option when signing, for example:</p> + +<pre class="brush: bash"><code>web-ext sign --api-key=... --api-secret=... --id="</code>{c23c69a7-f889-447c-9d6b-7694be8035bc}<code>"</code></pre> + +<h3 id="Assinar_num_ambiente_restringido">Assinar num ambiente restringido</h3> + +<p>If you're working in an environment that restricts access to certain domains, you can try using a proxy when signing:</p> + +<pre class="brush: bash"><code>web-ext sign --api-key=... --api-secret=... --api-proxy=https://yourproxy:6000</code></pre> + +<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#--api-proxy">--api-proxy</a> option to learn more.</p> + +<p>The following domains are used for signing and downloading files:</p> + +<ul> + <li><code>addons.mozilla.org</code></li> + <li><code>addons.cdn.mozilla.net</code></li> +</ul> + +<h3 id="Verificar_com_o_código_lint">Verificar com o código "lint"</h3> + +<p>Before trying out your extension with the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_run">run</a> command or submitting your package to <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a>, use the <code>lint</code> command to make sure your <a href="/en-US/Add-ons/WebExtensions/manifest.json">manifest</a> and other source files do not contain any errors. Example:</p> + +<pre class="brush: bash">web-ext lint</pre> + +<p>This uses the <a href="https://github.com/mozilla/addons-linter">addons-linter</a> library to walk through your source code directory and report any errors, such as the declaration of an unknown permission.</p> + +<p>See the <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#web-ext_lint">lint reference guide</a> to learn more.</p> + +<h3 id="Definindo_as_predefinições_de_opção_num_ficheiro_de_configuração">Definindo as predefinições de opção num ficheiro de configuração</h3> + +<p>You can specify <code>--config=my-config.js</code> to set default values for any option. Here is an example with the <code>build</code> command:</p> + +<pre class="brush: bash">web-ext --config=my-config.js build</pre> + +<p>The file should be a CommonJS module <a href="https://nodejs.org/docs/latest/api/modules.html#modules_modules">as understood by NodeJS</a> and must export each configuration value. Here is how you would set the default value of <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#--verbose_-v">--verbose</a> to <code>true</code>:</p> + +<pre class="brush: javascript">module.exports = { + verbose: true, +};</pre> + +<p>If you want to specify options that only apply to a specific command, you nest the configuration under the command name. Here is an example of adding configuration for <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#--overwrite-dest_-o">--overwrite-dest</a> that only applies to the <code>build</code> command as well as <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#--firefox_-f">--firefox</a> that only applies to the <code>run</code> command:</p> + +<pre class="brush: javascript">module.exports = { + // Global options: + verbose: true, + // Command options: + build: { + overwriteDest: true, + }, + run: { + firefox: 'nightly', + }, +};</pre> + +<p>To create a configuration key for a command line option, you remove the preceding dashes and convert the name to camel case. As you can see from this example, <code>--overwrite-dest</code> was converted to <code>overwriteDest</code>.</p> + +<p>If an option can be specified multiple times on the command line then you define it as an array. For example, here is how to specify multiple <a href="/en-US/Add-ons/WebExtensions/web-ext_command_reference#--ignore-files_-i">--ignore-files</a> patterns:</p> + +<pre class="brush: javascript">module.exports = { + ignoreFiles: [ + 'package-lock.json', + 'yarn.lock', + ], +};</pre> + +<h3 id="Automatic_discovery_of_configuration_files">Automatic discovery of configuration files</h3> + +<p><code>web-ext</code> will load existing configuration files in the following order:</p> + +<ul> + <li>A config file named <code>.web-ext-config.js</code> in your home directory, for example: + + <ul> + <li>On Windows: <code>C:\Users\<username>\.web-ext-config.js</code></li> + <li>On macOS: <code>/Users/<username>/.web-ext-config.js</code></li> + <li>On Linux: <code>/home/<username>/.web-ext-config.js</code></li> + </ul> + </li> + <li>A config file named <code>web-ext-config.js</code> in the current directory.</li> +</ul> + +<p>If a home directory config and a local directory config define the same option, the value from the latter file will be used.</p> + +<p>To disable automatic loading of configuration files, set this option:</p> + +<pre class="brush: bash">web-ext --no-config-discovery run</pre> + +<p>To diagnose an issue related to config files, re-run your command with <code>--verbose</code>. This will tell you which config file affected which option value.</p> + +<h3 id="Specifying_different_source_and_destination_directories">Specifying different source and destination directories</h3> + +<p>The preceding commands use default directories for the extension source and artifact creation (for example, built <code>.zip</code> files). The defaults are:</p> + +<ul> + <li>Source: The directory you are in.</li> + <li>Artifacts: A directory called <code>./web-ext-artifacts</code>, created inside the current directory.</li> +</ul> + +<p>You can specify different source and destination directories using the <code>--source-dir</code> and <code>--artifacts-dir</code> options when running your commands. Their values can be relative or absolute paths, but must always be specified as strings. Here is an example of specifying both options when building an extension:</p> + +<pre class="brush: bash"><code>web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips</code></pre> + +<h3 id="Outputting_verbose_messages">Outputting verbose messages</h3> + +<p>To see in detail what web-ext is doing when you run a command, include the <code>--verbose</code> option. For example:</p> + +<pre class="brush: bash"><code>web-ext build --verbose</code></pre> + +<h3 id="Viewing_all_commands_and_options">Viewing all commands and options</h3> + +<p>You can list all commands and options like this:</p> + +<pre class="brush: bash"><code>web-ext --help</code></pre> + +<p>You can list options for a specific command by adding it as an argument:</p> + +<pre class="brush: bash"><code>web-ext --help run</code></pre> + +<h3 id="Detecting_temporary_installation">Detecting temporary installation</h3> + +<p>Your extension can detect whether it was installed using <code>web-ext run</code>, rather than as a built and signed extension downloaded from <code>addons.mozilla.org</code>. Listen for the {{WebExtAPIRef("runtime.onInstalled")}} event and check the value of <code>details.temporary</code>.</p> + +<h3 id="Using_web-ext_from_a_script">Using web-ext from a script</h3> + +<p>You can use <code>web-ext</code> as a <code>NodeJS</code> module. Here is <a href="https://github.com/mozilla/web-ext#using-web-ext-in-nodejs-code">more information</a>, with example code.</p> + +<h2 id="Consulte_também">Consulte também</h2> + +<ul> + <li><a class="external external-icon" href="https://github.com/mozilla/web-ext">web-ext repo</a></li> + <li> + <p><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/web-ext_command_reference">web-ext command reference</a></p> + </li> +</ul> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/publicar_a_sua_extensao/index.html b/files/pt-pt/mozilla/add-ons/webextensions/publicar_a_sua_extensao/index.html new file mode 100644 index 0000000000..acc5d21d53 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/publicar_a_sua_extensao/index.html @@ -0,0 +1,62 @@ +--- +title: Publicar a sua extensão +slug: Mozilla/Add-ons/WebExtensions/Publicar_a_sua_extensao +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Package_your_extension_ +--- +<div>{{AddonSidebar}}</div> + +<p> </p> + +<div class="pull-aside"> +<div class="moreinfo"> +<p>Packaged extensions in Firefox are called "XPI files", which are ZIP files with a different extension.</p> + +<p>You don't have to use the XPI extension when uploading to AMO.</p> +</div> +</div> + +<p> </p> + +<p>During development, your extension will consist of a directory containing a manifest.json file and the other files it needs—scripts, icons, HTML documents, and so on. You need to zip these into a single file for uploading to AMO.</p> + +<p>If you're using web-ext, use <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/web-ext_command_reference#web-ext_build">web-ext build </a>to package your extension. Otherwise, follow the instructions below for your chosen operating system.</p> + +<div class="note"> +<p><strong>Dica</strong>: The ZIP file must be a ZIP of the extension's files themselves, not of the directory containing them.</p> +</div> + +<h3 id="Windows">Windows</h3> + +<ol> + <li>Abra a pasta com os seus ficheiros da extensão.</li> + <li>Selecione todos os ficheiros.</li> + <li>Clique direito e escolha "Enviar para" → Pasta Comprimida (zipped).</li> +</ol> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11949/install-windows.png" style="display: block; height: 576px; margin-left: auto; margin-right: auto; width: 800px;"></p> + +<h3 id="Mac_OS_X">Mac OS X</h3> + +<ol> + <li>Open the folder with your extension's files.</li> + <li>Select all of the files.</li> + <li>Right click and choose Compress <em>n</em> Items.</li> +</ol> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11951/install-osx.png" style="display: block; height: 449px; margin-left: auto; margin-right: auto; width: 800px;"></p> + +<div class="pull-aside"> +<div class="moreinfo">See <a href="http://www.info-zip.org/mans/zip.html">http://www.info-zip.org/mans/zip.html</a>.</div> +</div> + +<h3 id="Linux_Mac_OS_X_Terminal">Linux / Mac OS X Terminal</h3> + +<ol> + <li>Open Terminal.</li> + <li>Open the directory containing your extension's files, using the command<br> + <code>cd path/to/<em>my-extension</em>/</code></li> + <li>ZIP the content of the directory, using the command<br> + <code>zip -r -FS ../<em>my-extension</em>.zip *</code></li> +</ol> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/scripts_conteudo/index.html b/files/pt-pt/mozilla/add-ons/webextensions/scripts_conteudo/index.html new file mode 100644 index 0000000000..51356eed85 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/scripts_conteudo/index.html @@ -0,0 +1,446 @@ +--- +title: Scripts de Conteúdo +slug: Mozilla/Add-ons/WebExtensions/Scripts_Conteudo +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Content_scripts +--- +<div>{{AddonSidebar}}</div> + +<p>Um <em>script</em> de conteúdo é uma parte da sua extensão que é executada no contexto de uma determinada página da Web (em oposição aos <em>scripts</em> de segundo plano que são parte da própria extensão, ou <em>scripts</em> que são parte do próprio site da Web, tal como aqueles carregados utilizando o {{HTMLElement("script")}} elemento.</p> + +<p><a href="/en-US/Add-ons/WebExtensions/Background_scripts">Background scripts</a> can access all the <a href="/en-US/Add-ons/WebExtensions/API">WebExtension JavaScript APIs</a>, but they can't directly access the content of web pages. So if your extension needs to do that, you need content scripts.</p> + +<p>Just like the scripts loaded by normal web pages, content scripts can read and modify the content of their pages using the standard DOM APIs.</p> + +<p>Content scripts can only access <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_scripts#WebExtension_APIs">a small subset of the WebExtension APIs</a>, but they can <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">communicate with background scripts</a> using a messaging system, and thereby indirectly access the WebExtension APIs.</p> + +<div class="note"> +<p>Note that content scripts are blocked on the following domains: accounts-static.cdn.mozilla.net, accounts.firefox.com, addons.cdn.mozilla.net, addons.mozilla.org, api.accounts.firefox.com, content.cdn.mozilla.net, content.cdn.mozilla.net, discovery.addons.mozilla.org, input.mozilla.org, install.mozilla.org, oauth.accounts.firefox.com, profile.accounts.firefox.com, support.mozilla.org, sync.services.mozilla.com, and testpilot.firefox.com. If you try to inject a content script into a page in these domains, it will fail and the page will log a <a href="/en-US/docs/Web/HTTP/CSP">CSP</a> error.</p> + +<p>As these restrictions include addons.mozilla.org, users may attempt to use your extension immediately after installation and find it doesn't work. You may want to add an appropriate warning or an <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/onboarding_upboarding_offboarding_best_practices">onboarding page</a> that moves users away from addons.mozilla.org.</p> +</div> + +<div class="note"> +<p>Values added to the global scope of a content script with <code>var foo</code> or <code>window.foo = "bar"</code> may disappear due to bug <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1408996">1408996</a>.</p> +</div> + +<h2 id="Carregar_scripts_de_conteúdo">Carregar <em>scripts</em> de conteúdo</h2> + +<p>You can load a content script into a web page in one of three ways:</p> + +<ol> + <li><strong>at install time, into pages that match URL patterns:</strong> using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> key in your manifest.json, you can ask the browser to load a content script whenever the browser loads a page whose URL <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Match_patterns">matches a given pattern</a>.</li> + <li><strong>at runtime, into pages that match URL patterns:</strong> using the {{WebExtAPIRef("contentScripts")}} API, you can ask the browser to load a content script whenever the browser loads a page whose URL <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Match_patterns">matches a given pattern</a>. This is just like method (1), except you can add and remove content scripts at runtime.</li> + <li><strong>at runtime, into specific tabs:</strong> using the <code><a href="/en-US/Add-ons/WebExtensions/API/Tabs/executeScript">tabs.executeScript()</a></code> API, you can load a content script into a specific tab whenever you want: for example, in response to the user clicking on a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_action">browser action</a>.</li> +</ol> + +<p>There is only one global scope per frame per extension, so variables from one content script can directly be accessed by another content script, regardless of how the content script was loaded.</p> + +<p>Using methods (1) and (2) you can only load scripts into pages whose URLs can be represented using a <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">match pattern</a>. Using method (3), you can also load scripts into pages packaged with your extension, but you can't load scripts into privileged browser pages like "about:debugging" or "about:addons".</p> + +<h2 id="Ambiente_de_script_de_conteúdo">Ambiente de <em>script</em> de conteúdo</h2> + +<h3 id="Acesso_DOM">Acesso DOM</h3> + +<p>Content scripts can access and modify the page's DOM, just like normal page scripts can. They can also see any changes that were made to the DOM by page scripts.</p> + +<p>However, content scripts get a "clean view of the DOM". This means:</p> + +<ul> + <li>content scripts cannot see JavaScript variables defined by page scripts</li> + <li>if a page script redefines a built-in DOM property, the content script will see the original version of the property, not the redefined version.</li> +</ul> + +<p>In Firefox, this behavior is called <a href="/en-US/docs/Xray_vision">Xray vision</a>.</p> + +<p>For example, consider a web page like this:</p> + +<pre class="brush: html"><!DOCTYPE html> +<html> + <head> + <meta http-equiv="content-type" content="text/html; charset=utf-8" /> + </head> + + <body> + <script src="page-scripts/page-script.js"></script> + </body> +</html></pre> + +<p>The script "page-script.js" does this:</p> + +<pre class="brush: js">// page-script.js + +// add a new element to the DOM +var p = document.createElement("p"); +p.textContent = "This paragraph was added by a page script."; +p.setAttribute("id", "page-script-para"); +document.body.appendChild(p); + +// define a new property on the window +window.foo = "This global variable was added by a page script"; + +// redefine the built-in window.confirm() function +window.confirm = function() { + alert("The page script has also redefined 'confirm'"); +}</pre> + +<p>Now an extension injects a content script into the page:</p> + +<pre class="brush: js">// content-script.js + +// can access and modify the DOM +var pageScriptPara = document.getElementById("page-script-para"); +pageScriptPara.style.backgroundColor = "blue"; + +// can't see page-script-added properties +console.log(window.foo); // undefined + +// sees the original form of redefined properties +window.confirm("Are you sure?"); // calls the original window.confirm()</pre> + +<p>The same is true in reverse: page scripts can't see JavaScript properties added by content scripts.</p> + +<p>All this means that the content script can rely on DOM properties behaving predictably, and doesn't have to worry about variables it defines clashing with variables defined in the page script.</p> + +<p>One practical consequence of this behavior is that a content script won't have access to any JavaScript libraries loaded by the page. So for example, if the page includes jQuery, the content script won't be able to see it.</p> + +<p>If a content script does want to use a JavaScript library, then the library itself should be injected as a content script alongside the content script that wants to use it:</p> + +<pre class="brush: json">"content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["jquery.js", "content-script.js"] + } +]</pre> + +<p>Note that Firefox provides some APIs that enable content scripts to access JavaScript objects created by page scripts and to expose their own JavaScript objects to page scripts. See <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts">Sharing objects with page scripts</a> for more details.</p> + +<h3 id="APIs_da_Extensão_da_Web">APIs da Extensão da Web</h3> + +<p>In addition to the standard DOM APIs, content scripts can use the following WebExtension APIs:</p> + +<p>From <code><a href="/en-US/Add-ons/WebExtensions/API/extension">extension</a></code>:</p> + +<ul> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/extension#getURL()">getURL()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/extension#inIncognitoContext">inIncognitoContext</a></code></li> +</ul> + +<p>From <code><a href="/en-US/Add-ons/WebExtensions/API/runtime">runtime</a></code>:</p> + +<ul> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#connect()">connect()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#getManifest()">getManifest()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#getURL()">getURL()</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#onConnect">onConnect</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#onMessage">onMessage</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/API/runtime#sendMessage()">sendMessage()</a></code></li> +</ul> + +<p>From <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a></code>:</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getMessage">getMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getAcceptLanguages">getAcceptLanguages()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/getUILanguage">getUILanguage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/detectLanguage">detectLanguage()</a></code></li> +</ul> + +<p>From <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus">menus</a></code>:</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus/getTargetElement">getTargetElement</a></code></li> +</ul> + +<p>Everything from <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code>.</p> + +<h3 id="XHR_e_Fetch">XHR e <em>Fetch</em></h3> + +<p>Content scripts can make requests using the normal <code><a href="/en-US/docs/Web/API/XMLHttpRequest">window.XMLHttpRequest</a></code> and <code><a href="/en-US/docs/Web/API/Fetch_API">window.fetch()</a></code> APIs.</p> + +<p>Content scripts get the same cross-domain privileges as the rest of the extension: so if the extension has requested cross-domain access for a domain using the <code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> key in manifest.json, then its content scripts get access that domain as well.</p> + +<p>This is accomplished by exposing more privileged XHR and fetch instances in the content script, which has the side-effect of not setting the <code><a href="/en-US/docs/Web/HTTP/Headers/Origin">Origin</a></code> and <code><a href="/en-US/docs/Web/HTTP/Headers/Referer">Referer</a></code> headers like a request from the page itself would, this is often preferable to prevent the request from revealing its cross-orign nature. From version 58 onwards extensions that need to perform requests that behave as if they were sent by the content itself can use <code>content.XMLHttpRequest</code> and <code>content.fetch()</code> instead. For cross-browser extensions their presence must be feature-detected.</p> + +<h2 id="Comunicar_com_scripts_de_segundo_plano">Comunicar com <em>scripts</em> de segundo plano</h2> + +<p>Although content scripts can't directly use most of the WebExtension APIs, they can communicate with the extension's background scripts using the messaging APIs, and can therefore indirectly access all the same APIs that the background scripts can.</p> + +<p>There are two basic patterns for communicating between the background scripts and content scripts: you can send one-off messages, with an optional response, or you can set up a longer-lived connection between the two sides, and use that connection to exchange messages.</p> + +<h3 id="One-off_messages">One-off messages</h3> + +<p>To send one-off messages, with an optional response, you can use the following APIs:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row"></th> + <th scope="col">In content script</th> + <th scope="col">In background script</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Send a message</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime/sendMessage">browser.runtime.sendMessage()</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/Tabs/sendMessage">browser.tabs.sendMessage()</a></code></td> + </tr> + <tr> + <th scope="row">Receive a message</th> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code></td> + <td><code><a href="/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code></td> + </tr> + </tbody> +</table> + +<p>For example, here's a content script which listens for click events in the web page. If the click was on a link, it messages the background page with the target URL:</p> + +<pre class="brush: js">// content-script.js + +window.addEventListener("click", notifyExtension); + +function notifyExtension(e) { + if (e.target.tagName != "A") { + return; + } + browser.runtime.sendMessage({"url": e.target.href}); +}</pre> + +<p>The background script listens for these messages and displays a notification using the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/notifications">notifications</a></code> API:</p> + +<pre class="brush: js">// background-script.js + +browser.runtime.onMessage.addListener(notify); + +function notify(message) { + browser.notifications.create({ + "type": "basic", + "iconUrl": browser.extension.getURL("link.png"), + "title": "You clicked a link!", + "message": message.url + }); +} +</pre> + +<p>This example code is lightly adapted from the <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> example on GitHub.</p> + +<h3 id="Connection-based_messaging">Connection-based messaging</h3> + +<p>Sending one-off messages can get cumbersome if you are exchanging a lot of messages between a background script and a content script. So an alternative pattern is to establish a longer-lived connection between the two contexts, and use this connection to exchange messages.</p> + +<p>Each side has a <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> object, which they can use to exchange messages.</p> + +<p>To create the connection:</p> + +<ul> + <li>one side listens for connections using <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onConnect">runtime.onConnect</a></code></li> + <li>the other side calls either <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/connect">tabs.connect()</a></code> (if connecting to a content script) or <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/connect">runtime.connect()</a></code> (if connecting to a background script). This returns a <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> object.</li> + <li>the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onConnect">runtime.onConnect</a></code> listener gets passed its own <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port">runtime.Port</a></code> object.</li> +</ul> + +<p>Once each side has a port, the two sides can exchange messages using <code>runtime.Port.postMessage()</code> to send a message, and <code>runtime.Port.onMessage</code> to receive messages.</p> + +<p>For example, as soon as it loads, this content script:</p> + +<ul> + <li>connects to the background script, and stores the <code>Port</code> in a variable <code>myPort</code></li> + <li>listens for messages on <code>myPort</code>, and logs them</li> + <li>sends messages to the background script, using <code>myPort</code>, when the user clicks the document</li> +</ul> + +<pre class="brush: js">// content-script.js + +var myPort = browser.runtime.connect({name:"port-from-cs"}); +myPort.postMessage({greeting: "hello from content script"}); + +myPort.onMessage.addListener(function(m) { + console.log("In content script, received message from background script: "); + console.log(m.greeting); +}); + +document.body.addEventListener("click", function() { + myPort.postMessage({greeting: "they clicked the page!"}); +});</pre> + +<p>The corresponding background script:</p> + +<ul> + <li>listens for connection attempts from the content script</li> + <li>when it receives a connection attempt: + <ul> + <li>stores the port in a variable named <code>portFromCS</code></li> + <li>sends the content script a message using the port</li> + <li>starts listening to messages received on the port, and logs them</li> + </ul> + </li> + <li>sends messages to the content script, using <code>portFromCS</code>, when the user clicks the extension's browser action</li> +</ul> + +<pre class="brush: js">// background-script.js + +var portFromCS; + +function connected(p) { + portFromCS = p; + portFromCS.postMessage({greeting: "hi there content script!"}); + portFromCS.onMessage.addListener(function(m) { + console.log("In background script, received message from content script") + console.log(m.greeting); + }); +} + +browser.runtime.onConnect.addListener(connected); + +browser.browserAction.onClicked.addListener(function() { + portFromCS.postMessage({greeting: "they clicked the button!"}); +}); +</pre> + +<h4 id="Multiple_content_scripts">Multiple content scripts</h4> + +<p>If you have multiple content scripts communicating at the same time, you might want to store each connection in an array.</p> + + + +<ul> +</ul> + +<pre class="brush: js">// background-script.js + +var ports = [] + +function connected(p) { + ports[p.sender.tab.id] = p + //... +} + +browser.runtime.onConnect.addListener(connected) + +browser.browserAction.onClicked.addListener(function() { + ports.forEach(p => { + p.postMessage({greeting: "they clicked the button!"}) + }) +});</pre> + + + +<ul> +</ul> + +<h2 id="Comunicar_com_a_página_da_Web">Comunicar com a página da Web</h2> + +<p>Although content scripts don't by default get access to objects created by page scripts, they can communicate with page scripts using the DOM <code><a href="/en-US/docs/Web/API/Window/postMessage">window.postMessage</a></code> and <code><a href="/en-US/docs/Web/API/EventTarget/addEventListener">window.addEventListener</a></code> APIs.</p> + +<p>For example:</p> + +<pre class="brush: js">// page-script.js + +var messenger = document.getElementById("from-page-script"); + +messenger.addEventListener("click", messageContentScript); + +function messageContentScript() { + window.postMessage({ + direction: "from-page-script", + message: "Message from the page" + }, "*");</pre> + +<pre class="brush: js">// content-script.js + +window.addEventListener("message", function(event) { + if (event.source == window && + event.data && + event.data.direction == "from-page-script") { + alert("Content script received message: \"" + event.data.message + "\""); + } +});</pre> + +<p>For a complete working example of this, <a href="https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html">visit the demo page on GitHub</a> and follow the instructions.</p> + +<div class="warning"> +<p>Note that any time you interact with untrusted web content on this way, you need to be very careful. Extensions are privileged code which can have powerful capabilities, and hostile web pages can easily trick them into accessing those capabilities.</p> + +<p>To make a trivial example, suppose the content script code that receives the message does something like this:</p> + +<pre class="brush: js">// content-script.js + +window.addEventListener("message", function(event) { + if (event.source == window && + event.data.direction && + event.data.direction == "from-page-script") { + eval(event.data.message); + } +});</pre> + +<p>Now the page script can run any code with all the privileges of the content script.</p> +</div> + +<h2 id="Using_eval()_in_content_scripts">Using eval() in content scripts</h2> + +<p>In Chrome, <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code> always runs code in the context of the content script, not in the context of the page.</p> + +<p>In Firefox:</p> + +<ul> + <li>if you call <code>eval()</code>, it runs code in the context of the content script</li> + <li>if you call <code>window.eval()</code>, it runs code in the context of the page.</li> +</ul> + +<p>For example, consider a content script like this:</p> + +<pre class="brush: js">// content-script.js + +window.eval('window.x = 1;'); +eval('window.y = 2'); + +console.log(`In content script, window.x: ${window.x}`); +console.log(`In content script, window.y: ${window.y}`); + +window.postMessage({ + message: "check" +}, "*");</pre> + +<p>This code just creates some variables x and y using <code>window.eval()</code> and <code>eval()</code>, then logs their values, then messages the page.</p> + +<p>On receiving the message, the page script logs the same variables:</p> + +<pre class="brush: js">window.addEventListener("message", function(event) { + if (event.source === window && event.data && event.data.message === "check") { + console.log(`In page script, window.x: ${window.x}`); + console.log(`In page script, window.y: ${window.y}`); + } +});</pre> + +<p>In Chrome, this will produce output like this:</p> + +<pre>In content script, window.x: 1 +In content script, window.y: 2 +In page script, window.x: undefined +In page script, window.y: undefined</pre> + +<p>In Firefox the following output is produced:</p> + +<pre>In content script, window.x: undefined +In content script, window.y: 2 +In page script, window.x: 1 +In page script, window.y: undefined</pre> + +<p>The same applies to <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">setTimeout()</a></code>, <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval">setInterval()</a></code>, and <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function">Function()</a></code>.</p> + +<p>When running code in the context of the page, be very careful. The page's environment is controlled by potentially malicious web pages, which can redefine objects you interact with to behave in unexpected ways:</p> + +<pre class="brush: js">// page.js redefines console.log + +var original = console.log; + +console.log = function() { + original(true); +} +</pre> + +<pre class="brush: js">// content-script.js calls the redefined version + +window.eval('console.log(false)'); +</pre> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/suporte_navegador_apis_javascript/index.html b/files/pt-pt/mozilla/add-ons/webextensions/suporte_navegador_apis_javascript/index.html new file mode 100644 index 0000000000..e34a4013d3 --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/suporte_navegador_apis_javascript/index.html @@ -0,0 +1,19 @@ +--- +title: Suporte de navegador para as APIs de JavaScript +slug: Mozilla/Add-ons/WebExtensions/Suporte_navegador_APIs_JavaScript +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs +--- +<p>{{AddonSidebar}}</p> + +<div>{{WebExtAllCompatTables}}</div> + +<div>A tabela de compatibilidade nesta página é gerada a partir de dados estruturados. Se quiser contribuir para os dados, verifique por favor, consulte https://github.com/mdn/browser-compat-data e envie-nos um pedido de submissão.</div> + +<div> </div> + +<div class="note"><strong>Agradecimentos</strong> + +<p>Os dados de compatibilidade do Microsoft Edge são fornecidos pela Corporação Microsoft e estão incluídos aqui sob a Licença de Creative Commons Attribution 3.0 - Estado Unidos.</p> +</div> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/tips/index.html b/files/pt-pt/mozilla/add-ons/webextensions/tips/index.html new file mode 100644 index 0000000000..dd02a81c1d --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/tips/index.html @@ -0,0 +1,50 @@ +--- +title: Tips and Tricks +slug: Mozilla/Add-ons/WebExtensions/Tips +translation_of: Mozilla/Add-ons/WebExtensions/Tips +--- +<p>{{AddonSidebar}}</p> + +<p>Esta paginas contêm varias dicas e truques que deve ser útil para muitas pessoas devenvolvendo extensões usando WebExtension APIs.</p> + +<h2 id="Usando_recursos_avancados_do_ECMAScript_2015_e_2016.">Usando recursos avancados do ECMAScript 2015 e 2016.</h2> + +<p>Firefox <a href="/Web/JavaScript/New_in_JavaScript/ECMAScript_6_support_in_Mozilla">suporta muitos recursos do ECMAScript 2015</a> fora da box. Diversas novidades e recursos experimental, contanto entretanto, não estão disponiveis por padrão para a Web ou WebExtensions. Se você quer usar esses recursos, é melhor transpilar seu codigo usando uma ferramenta como o <a href="https://babeljs.io/">Babel</a>.</p> + +<p>Cuidado que qualquer coisa abalixo desta linha é informação desatualizada e tem sido removida do Babel 6.</p> + +<p>Babel fornece transformações para a grande maioria dos recursos do ES2015, e os habilita por padrão. Uma vez que o Firefox já suporta totalmente a maiorias dessas, é melhor configurar Babel para ignorar-lá. Nós sugerimos criando um arquivo <code>.babelrc</code>, ou uma seção <code>babel</code> em seu arquivo de projeto <code>package.json</code> contendo o seguinte:</p> + +<pre class="brush: js">{ + "env": { + "firefox": { + "sourceMaps": "inline", + "blacklist": [ + "es5.properties.mutators", + "es6.arrowFunctions", + "es6.destructuring", + "es6.forOf", + "es6.parameters", + "es6.properties.computed", + "es6.properties.shorthand", + "es6.spec.symbols", + "es6.spread", + "es6.tailCall", + "es6.templateLiterals", + "es6.regex.sticky", + "es6.regex.unicode" + ] + } + } +} +</pre> + +<p>Então, para compilar um script individual simplesmente, execute:</p> + +<pre class="brush: sh">BABEL_ENV=firefox babel <filename> +</pre> + +<p>Ou, para compilar cada arquivo JavaScript dentro do diretório <code>src</code> e colocar os arquivos compilados em <code>compiled</code>, copiando arquivos não-JavaScript no processo, executadno:</p> + +<pre class="brush: sh">BABEL_ENV=firefox babel -Dd compiled src +</pre> diff --git a/files/pt-pt/mozilla/add-ons/webextensions/trasnsferir_extensao_google_chrome/index.html b/files/pt-pt/mozilla/add-ons/webextensions/trasnsferir_extensao_google_chrome/index.html new file mode 100644 index 0000000000..006ecce85c --- /dev/null +++ b/files/pt-pt/mozilla/add-ons/webextensions/trasnsferir_extensao_google_chrome/index.html @@ -0,0 +1,22 @@ +--- +title: Conversão de uma extensão do Google Chrome +slug: Mozilla/Add-ons/WebExtensions/Trasnsferir_extensao_Google_Chrome +tags: + - Extensões da Web +translation_of: Mozilla/Add-ons/WebExtensions/Porting_a_Google_Chrome_extension +--- +<div>{{AddonSidebar}}</div> + +<p>As extensões desenvolvidas com as APIs de Extensão da Web são preparadas para compatibilidade entre navegadores: em grande medida, a tecnologia é diretamente compatível com a <a class="external-icon external" href="https://developer.chrome.com/extensions">API de extensão</a> suportada pelo Google Chrome e Opera. As extensões escritas para estes navegadores irão, na maioria do casos, ser executadas no Firefox com apenas algumas alterações. Quase todas das <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API">APIs de extensão </a>são suportadas, utilizando as funções de chamada sob o espaço de nome <code>chrome</code>, o mesmo que Chrome. As únicas APIs que não são suportadas no nome de espaço <code>chrome</code> são aquelas que são intentionalmente incompatíveis com o Chrome. Nesses casos, a página da documentação de API irá declarar explicitamente que só é suportado no espaço do nome <code>browser</code> . O processo de transferir uma extensão do Chrome para Opera é como isto:</p> + +<ol> + <li>Reveja a sua utilização das funcionaldiades de manifest.json e APIs da Extensão da Web contra a <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">referência de incompatibilidade do Chrome</a>. Se estiver a utilizar as funcionalidades ou APIs que ainda não são suportadas no Firefox, poderá não conseguir converter ainda a sua extensão. A Mozilla fornece um serviço que pode ajudar a automatizar este passo: <a href="https://www.extensiontest.com">Teste de Compatibilidade de Extensão para Firefox</a> (inglês).</li> + <li><a href="https://developer.mozilla.org/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Instalacao_temporaria_no_Firefox">Instale a sua extensão no Firefox</a> e teste-a.</li> + <li>Se tiver quaisquer problemas, contacte-nos em <a href="https://mail.mozilla.org/listinfo/dev-addons">lista de endereços</a> ou <a href="irc://irc.mozilla.org/webextensions">#webextensions</a> no <a class="external external-icon" href="https://wiki.mozilla.org/IRC">IRC</a>.</li> + <li>Submeta o seu extra em <a href="https://developer.mozilla.org/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Publicar_a_sua_extensao">AMO para assinar e distribuir</a>. </li> +</ol> + +<p>Se estava dependente da opção da linha de comando do Chrome para carregar uma extensão descompactada, consulte a ferramenta <a href="https://developer.mozilla.org/pt-PT/docs/Mozilla/Add-ons/WebExtensions/Primeiros_passos_com_web-ext">web-ext</a> que automatiza a instalação temporária no Firefox para desenvolvimento.</p> + +<ul> +</ul> |