diff options
Diffstat (limited to 'files/es/mozilla/add-ons/webextensions')
31 files changed, 4106 insertions, 0 deletions
diff --git a/files/es/mozilla/add-ons/webextensions/add_a_button_to_the_toolbar/index.html b/files/es/mozilla/add-ons/webextensions/add_a_button_to_the_toolbar/index.html new file mode 100644 index 0000000000..1bccc9d703 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/add_a_button_to_the_toolbar/index.html @@ -0,0 +1,220 @@ +--- +title: Agregar botón a la barra de herramientas +slug: Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar +translation_of: Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar +--- +<div>{{AddonSidebar}}</div> + +<p>La barra de herramientas es una de las principales componentes UI disponibles para las extensiones. Toolbar buttons live in the main browser toolbar y contienen un icono. Cuando el usuario da click en el icono, dos cosas pueden suceder:</p> + +<ul> + <li>Si tu tienes especificado un popup para el icono, se va a mostrar. Popups son transitorios cuadros de diálogos creados usando HTML, CSS, y JavaScript.</li> + <li>Si no tu tienes especificado un popup, un evento del click es generado,el cual puede ser detectado en tu codigo para realizar alguna acción y responderla.</li> +</ul> + +<p>Con las APIs de WebExtension, este tipo de botón es se llaman "browser actions", y son configurados de la siguiente manera:</p> + +<ul> + <li>La clave <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> en manifest.json es usada para definir el botón.</li> + <li>La API de JavaScript <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> es usada para escuchar los clicks y cambiar el botón o realizar alguna acción en el codigo.</li> +</ul> + +<h2 id="Un_simple_botón">Un simple botón</h2> + +<p>En esta sección vamos a crear una extension que agrega un botón a la barra de herramientas. Cuando el usuario de click en el botón, vamos abrir <a href="https://developer.mozilla.org">https://developer.mozilla.org </a>en una nueva pestaña.</p> + +<p>Primero, crear una nueva carpeta "botón", y crea un archivo con el nombre de "manifest.json" con el siguiente contenido:</p> + +<pre class="brush: json">{ + + "description": "Demostrando botones de la barra de herramientas", + "manifest_version": 2, + "name": "botón-demo", + "version": "1.0", + + "background": { + "scripts": ["background.js"] + }, + + "browser_action": { + "default_icon": { + "16": "icons/page-16.png", + "32": "icons/page-32.png" + } + } + +}</pre> + +<p>Esto especifica que tenemos un <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background script</a> llamado "background.js", y un <strong>browser action</strong> (butón) cuyo icono va a estar en la carpeta "icons".</p> + +<div class="pull-aside"> +<div class="moreinfo">Estos iconos son de <a href="https://www.iconfinder.com/iconsets/bitsies">bitsies!</a> conjunto de iconos creados por Recep Kütük.</div> +</div> + +<p>Despues, dentro del folder "botón" crea la carpeta "icons" y dentro de el guarda estos dos iconos:</p> + +<ul> + <li>"page-16.png" (<img alt="" src="https://mdn.mozillademos.org/files/13476/page-16.png" style="height: 16px; width: 16px;">)</li> + <li>"page-32.png" (<img alt="" src="https://mdn.mozillademos.org/files/13478/page-32.png" style="height: 32px; width: 32px;">).</li> +</ul> + +<div style=""> </div> + +<p>Tenemos dos iconos entonces podemos usar el mas grande para las <span id="result_box" lang="es"><span>pantallas de alta densidad</span></span>. El navegador se va encargar de seleccionar el correcto para cada pantalla.</p> + +<p>Despues, crea "background.js" en la raiz del folder de la extension, y agrega el siguiente contenido:</p> + +<pre class="brush: js">function openPage() { + browser.tabs.create({ + url: "https://developer.mozilla.org" + }); +} + +browser.browserAction.onClicked.addListener(openPage);</pre> + +<p>Esto esta a la espera de de el navegador se de click; cuando el evento se dispara, la funcion <code>openPage()</code> comienza a ejecutarse, el cual abre la página especificada usando la API de <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs">tabs</a></code>.</p> + +<p>En este momento la extension debe de mirarse asi:</p> + +<pre class="line-numbers language-html"><code class="language-html">button/ + icons/ + page-16.png + page-32.png + background.js + manifest.json</code></pre> + +<p>Ahora <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">instala la extensión</a> y da click en el botón:</p> + +<p>{{EmbedYouTube("kwwTowgT-Ys")}}</p> + +<h2 id="Agregando_un_popup">Agregando un popup</h2> + +<p>Vamos a intentar agregar un popup al botón. Remplaza el manifest.json con este contenido:</p> + +<pre class="brush: json">{ + + "description": "Demostrando botones de la barra de herramientas", + "manifest_version": 2, + "name": "botón-demo", + "version": "1.0", + + "browser_action": { + "browser_style": true, + "default_popup": "popup/choose_page.html", + "default_icon": { + "16": "icons/page-16.png", + "32": "icons/page-32.png" + } + } + +}</pre> + +<p>Realizamos tres cambios:</p> + +<ul> + <li>Ya no hacemos referencia a "background.js", porque ahora nosotros vamos a controlar la lógica de la extensión en el script del popup (También es posible background.js como un popup, es solo qu no lo necesitamos en este caso).</li> + <li>Agregamos <code>"browser_style": true</code>, cual nos ayuda a dar estiloa nuestro popup y luzca mas integrado al navegador.</li> + <li>Finalmente, agregamos <code>"default_popup": "popup/choose_page.html"</code>, cual le dice al navegador que esta acción ahora va a mostar un popup cuando se haga click , usando el documento que se encuentra en "popup/choose_page.html".</li> +</ul> + +<p>Entonces ahora necesitamos crear el popup. Crea un folder llamado "popup" y crea adentro el archivo "choose_page.html" . agregale el siguiente contenido:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + <link rel="stylesheet" href="choose_page.css"/> + </head> + +<body> + <div class="page-choice">developer.mozilla.org</div> + <div class="page-choice">support.mozilla.org</div> + <div class="page-choice">addons.mozilla.org</div> + <script src="choose_page.js"></script> +</body> + +</html></pre> + +<p>Puedes notar que es un nomal archivo HTML que contiene tres elementos {{htmlelement("div")}}, con direcciones de Mozilla. También incluye archivos de CSS y JavaScript, en los cuales vamos agregar lo siguiente.</p> + +<p>Crea el archivo "choose_page.css" adentro de la carpeta "popup" , con el siguiente contenido:</p> + +<pre class="brush: css">html, body { + width: 300px; +} + +.page-choice { + width: 100%; + padding: 4px; + font-size: 1.5em; + text-align: center; + cursor: pointer; +} + +.page-choice:hover { + background-color: #CFF2F2; +}</pre> + +<p>Es solo un poco de estilo a nuestro popup.</p> + +<p>Ahora, crea un archivo "choose_page.js" dentro del folder "popup" con el siguiente contenido:</p> + +<pre class="brush: js">document.addEventListener("click", function(e) { + if (!e.target.classList.contains("page-choice")) { + return; + } + + var chosenPage = "https://" + e.target.textContent; + browser.tabs.create({ + url: chosenPage + }); + +});</pre> + +<p>En nuestro JavaScript, esta a la espera de clicks en las opciones de nuestro popup. Primero revisa si el click fue en una de nuestras elecciones, si no, no realizamos nada mas. Se seleccion una carga una página elegida, en una nueva pestaña con la correspondiente página. Nota que podemos usar las APIs WebExtension en el script del popup, como también scripts de fondo.</p> + +<p>La estructura de la extensión final debe ser como esta:</p> + +<pre>button/ + icons/ + page-16.png + page-32.png + popup/ + choose_page.css + choose_page.html + choose_page.js + manifest.json</pre> + +<p>Ahora vamos a recargar la extensión, click en el botón otra vez e intenta dar click en las opciones del popup:</p> + +<p>{{EmbedYouTube("QPEh1L1xq0Y")}}</p> + +<h2 id="Acciones_de_página">Acciones de página</h2> + +<p><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Page_actions">Acciones de página</a> son como las acciones del navegador, excepto que son acciones relevantes solo para algunas página en particular.</p> + +<p>Mientras de las acciones del navegaro siembre son mostradas, las acciones de página son solo mostradas en pestañas donde son relevantes. Los botones de las acciones de página son mostradas en la barra URL , en vez de la barra de herramientas del navegador.</p> + +<h2 id="Aprende_más">Aprende más</h2> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> manifest key</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> API</li> + <li>Ejemplos de acciones del navegador: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/bookmark-it">Bookmark it!</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">favourite-colour</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/inpage-toolbar-ui">inpage-toolbar-ui</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/open-my-page-button">open-my-page-button</a></li> + </ul> + </li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code> manifest key</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">pageAction</a></code> API</li> + <li>Ejemplos de Acciones de página: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/chill-out">chill-out</a></li> + </ul> + </li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/anatomia_de_una_webextension/index.html b/files/es/mozilla/add-ons/webextensions/anatomia_de_una_webextension/index.html new file mode 100644 index 0000000000..685e282bf9 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/anatomia_de_una_webextension/index.html @@ -0,0 +1,120 @@ +--- +title: Anatomía de una extension +slug: Mozilla/Add-ons/WebExtensions/Anatomia_de_una_WebExtension +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>Una extensión se compone de una colección de archivos, empaquetados para su distribución e instalación. En este artículo vamos a repasar rápidamente los archivos que deben estar presentes en una extensión.</p> + +<p>Toda extensión debe contener un archivo llamado <a href="/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#manifest.json">"manifest.json"</a>. Este puede tener enlaces a otros tipos de archivos:</p> + +<ul> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#Scripts_en_segundo_plano">Páginas en segundo plano</a>: implementan la lógica de larga ejecución.</li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#Scripts_de_contenido">Scripts de contenido</a>: interactúan con las páginas web (note que esto no es lo mismo que JavaScript en un elemento {{HTMLElement("script")}} dentro de una página).</li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#Acciones_del_navegador_2">Archivos de acción del navegador</a>: implementan los botones de la barra de herramientas.</li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#Acciones_de_las_páginas">Archivos de acción de la página: </a>Implementan botones en la barra de direcciones.</li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#Opciones_de_las_páginas">Páginas de opciones</a>: Definen una IU para que los usuarios vean y cambien las configuraciones de la extensión.</li> + <li> + <div id="gt-res-content"> + <div class="trans-verified-button-small" dir="ltr" id="gt-res-dir-ctr"><span id="result_box" lang="es"><span><a href="/es/Add-ons/WebExtensions/user_interface/Sidebars">archivos de la barra lateral</a>: agregue una barra lateral al navegador.</span></span></div> + </div> + </li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#Recursos_web_accesibles">Recursos Web accesibles</a>: Hace posible que el contenido empaquetado acceda a páginas web y scripts.</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> + +<h2 id="manifest.json">manifest.json</h2> + +<p>Este es el único archivo que debe estar presente en toda WebExtension. Este contiene los metadatos básicos acerca de la extensión, como su nombre, versión, y los permisos que esta requiere. También provee los enlaces a otros archivos de la extensión.</p> + +<p>Mira la página de referencia <a href="/es/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> para ver todos los detalles.</p> + +<h2 id="Scripts_en_segundo_plano">Scripts en segundo plano</h2> + +<p>Las extensiones a menudo necesitan mantener estados de larga duración, o ejecutar operaciones a largo plazo, independientemente del tiempo de vida de una página web en particular o las ventanas del navegador. Para eso son los scripts en segundo plano.</p> + +<p>Los scripts en segundo plano son cargados cuando la extensión es cargada y se mantienen cargados hasta que la extensión es deshabilitada o desinstalada. Tu puedes usar cualquier <a href="/es/Add-ons/WebExtensions/API">API de WebExtensions</a> en el script, siempre y cuando hayas solicitado el <a href="/es/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permiso</a> necesario.</p> + +<h3 id="Especificando_los_scripts_en_segundo_plano">Especificando los scripts en segundo plano</h3> + +<p>Puedes incluir un script en segundo plano usando la propiedad <code>background</code> en "manifest.json":</p> + +<pre class="brush: json">// manifest.json + +"background": { + "scripts": ["background-script.js"] +}</pre> + +<p>Puedes especificar múltiples scripts en segundo plano: si lo haces, ellos se ejecutarán en el mismo contexto, justo como son cargados múltiples scripts en una página web.</p> + +<h3 id="Entorno_del_script_en_segundo_plano">Entorno del script en segundo plano</h3> + +<h4 id="APIs_del_DOM">APIs del DOM</h4> + +<p>Los scripts en segundo plano se ejecuta en el contexto de páginas especiales llamadas páginas en segundo plano. Esto le da un variable global <code><a href="/es/docs/Web/API/Window">window</a></code>, junto con todas las APIs estándar del DOM que proporciona.</p> + +<p>No necesitas proveer tu propia página en segundo plano. Si incluyes un script en segundo plano, una página en segundo plano vacía se creará para ti.</p> + +<p>Sin embargo, puedes escoger y proveer tu página en segundo plano como un archivo HTML separado:</p> + +<pre class="brush: json">// manifest.json + +"background": { + "page": "background-page.html" +}</pre> + +<h4 id="APIs_de_WebExtension">APIs de WebExtension</h4> + +<p>Los scripts en segundo plano pueden usar cualquier <a href="/es/Add-ons/WebExtensions/API">API de WebExtension</a> en el script, siempre que tu extensión tenga los <a href="/es/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permisos</a> necesarios.</p> + +<h4 id="Acceso_de_origen_cruzado">Acceso de origen cruzado</h4> + +<p>Los scripts en segundo plano pueden hacer peticiones XHR a cualquier host para los cuales tienen <a href="/es/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permisos del host</a>.</p> + +<h4 id="Acciones_del_navegador">Acciones del navegador</h4> + +<p>Si tu extensión define una acción del navegador, y esa acción del navegador no tiene ventanas emergentes, entonces puedes escuchar los eventos "clic" del botón en el navegador empleando el objeto <code><a href="/es/Add-ons/WebExtensions/API/browserAction#onClicked">onClicked</a></code> de las acciones del navegador:</p> + +<pre class="brush: js">browser.browserAction.onClicked.addListener(handleClick);</pre> + +<h4 id="Contenido_web">Contenido web</h4> + +<p>Los scripts en segundo plano no tienen acceso directo a las páginas web. Sin embargo, pueden cargar <a href="/es/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">scripts de contenido</a> en páginas web, y <a href="/en-US/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">comunicarse con esos scripts empleando la API de paso de mensajes</a>.</p> + +<h4 id="Políticas_de_segurdiad_para_el_contendio">Políticas de segurdiad para el contendio</h4> + +<p>Los scripts de segundo plano están restringidos de algunas operaciones dañinas, como el uso de <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>, a través de la Política de Seguridad del Contenido. Vea la <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Política de Segurdiad del Contenido </a>para más detalles sobre esto.</p> + +<h2 id="Scripts_de_contenido">Scripts de contenido</h2> + +<p>Usa los scripts de contenido para acceder y manipular páginas web. Los scripts de contenido son cargados dentro de las páginas web y ejecutados en el contexto particular de esa página.</p> + +<p>Los scripts de contenido son scripts provistos por la extensión los cuales se ejecutan en el contexto de la página web; estos difieren de los scripts que son cargados por la página misma, incluye aquellos que son proporcionados en los elementos {{HTMLElement("script")}} dentro de la página.</p> + +<p>Los scripts de contenido pueden ver y manipular el DOM de las páginas, igual que los scripts cargados normalmente por la página.</p> + +<p>A diferencia de los scripts normales, ellos pueden:</p> + +<ul> + <li>Realizar peticiones XHR de dominio cruzado</li> + <li>Usar un pequeño subconjunto de las <a href="/es/docs/Mozilla/Add-ons/WebExtensions/API">APIs de WebExtension</a></li> + <li>Intercambiar mensajes con sus scripts en segundo plano, y por esta vía, tener acceso indirecto a todas las APIs de WebExtension.</li> +</ul> + +<p>Los scripts de contenido no pueden acceder directamente a los scripts normales de una página web, pero pueden intercambiar mensajes con ellos usando la API estándar <code><a href="/es/docs/Web/API/Window/postMessage">window.postMessage()</a></code>.</p> + +<p>Generalmente, cuando hablamos acerca de scripts de contenido, nos referimos a JavaScript, pero tu puedes inyectar CSS dentro de las páginas web empleando el mismo mecanismo.</p> + +<p>Mira el artículo <a href="/es/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">scripts de contenido</a> para aprender más.</p> + +<h2 id="Recursos_web_accesibles">Recursos web accesibles</h2> + +<p>Los recursos web accesibles son recursos como imágenes, HTML, CSS y JavaScript que tu puedes incluir en la extensión y los quieres hacer accesible a los scripts en segundo plano y los scripts de las páginas. Los recursos que son hechos accesibles desde la web pueden ser referenciados desde scripts de páginas web y scripts de contenido mediante un esquema especial de URI.</p> + +<p>Por ejemplo, si un script de contenido quiere insertar algunas imágenes dentro de páginas web, tu puedes incluirlos en la extensión y hacerlos accesibles desde la web. El script de contenido creará y añadirá las etiquetas <code><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img">img</a></code> que referencia a las imágenes mediante el atributo <code>src</code>.</p> + +<p>Para aprender más, vea la documentación para la el parámetro <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resource</a> del manifest.json.</p> diff --git a/files/es/mozilla/add-ons/webextensions/api/i18n/index.html b/files/es/mozilla/add-ons/webextensions/api/i18n/index.html new file mode 100644 index 0000000000..15f990ac92 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/api/i18n/index.html @@ -0,0 +1,94 @@ +--- +title: i18n +slug: Mozilla/Add-ons/WebExtensions/API/i18n +tags: + - API + - Complementos + - Interfaz + - No estandar + - Reference + - WebExtensions + - extensiones + - i18n +translation_of: Mozilla/Add-ons/WebExtensions/API/i18n +--- +<div>{{AddonSidebar}}</div> + +<p>Funciones para internacionalizar su extensión. Es posible utilizar estas API para obtener cadenas de texto traducidas a partir de archivos de configuración regional incluidos en la extensión, conocer el idioma actual del navegador y recuperar el valor de su <a href="/en-US/docs/Web/HTTP/Content_negotiation#The_Accept-Language_header">cabecera Accept-Language</a>.</p> + +<p id="See_also">Para obtener más información sobre el uso de i18n en su extensión, consulte:</p> + +<ul> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization">Internacionalización</a>: una guía para utilizar el sistema de l18n de WebExtensions.</li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference">Referencia de mensajes específicos de la configuración regional</a>: las extensiones proporcionan cadenas específicas de la configuración regional en archivos denominados <code>messages.json</code>. Esta página describe el formato de <code>messages.json</code>.</li> +</ul> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt>{{WebExtAPIRef("i18n.LanguageCode")}}</dt> + <dd>Una <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.10">etiqueta de idioma</a> como «<code>en-US</code>» o «<code>fr</code>».</dd> +</dl> + +<h2 id="Funciones">Funciones</h2> + +<dl> + <dt>{{WebExtAPIRef("i18n.getAcceptLanguages()")}}</dt> + <dd>Recupera los valores de <a href="/en-US/docs/Web/HTTP/Content_negotiation#The_Accept-Language_header">accept-language</a> del navegador. Esto es distinto de la configuración regional utilizada por el navegador. Para obtener la configuración regional, utilice {{WebExtAPIRef('i18n.getUILanguage')}}.</dd> + <dt>{{WebExtAPIRef("i18n.getMessage()")}}</dt> + <dd>Obtiene la cadena de texto traducida correspondiente al mensaje especificado.</dd> + <dt>{{WebExtAPIRef("i18n.getUILanguage()")}}</dt> + <dd>Obtiene el idioma de la IU del navegador. Esto es distinto de {{WebExtAPIRef('i18n.getAcceptLanguages')}}, que devuelve los idiomas preferidos del usuario.</dd> + <dt>{{WebExtAPIRef("i18n.detectLanguage()")}}</dt> + <dd>Detecta el idioma del texto proporcionado a través de <a href="https://github.com/CLD2Owners/cld2">Compact Language Detector</a>.</dd> +</dl> + +<dl> +</dl> + +<h2 id="Compatibilidad_entre_navegadores">Compatibilidad entre navegadores</h2> + +<p>{{Compat("webextensions.api.i18n")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<dl> +</dl> + +<div class="note"><strong>Reconocimientos</strong> + +<p>Esta API se basa en la API <a href="https://developer.chrome.com/extensions/i18n"><code>chrome.i18n</code></a> de Chromium. Esta documentación deriva del archivo <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/i18n.json"><code>i18n.json</code></a> en el código fuente de Chromium.</p> + +<p>Los datos de compatibilidad de Microsoft Edge son suministrados por Microsoft Corporation y se incluyen aquí según los términos de la licencia Creative Commons Atribución 3.0, versión estadounidense.</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/es/mozilla/add-ons/webextensions/api/index.html b/files/es/mozilla/add-ons/webextensions/api/index.html new file mode 100644 index 0000000000..9a1a727d52 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/api/index.html @@ -0,0 +1,59 @@ +--- +title: API +slug: Mozilla/Add-ons/WebExtensions/API +tags: + - Extenciones Web +translation_of: Mozilla/Add-ons/WebExtensions/API +--- +<p>Las API de JavaScript para las Extensiones Web se pueden usar dentro de los <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">scripts en segundo plano</a> de la extensión y en cualquier otro documento contenido en la extensión, incluyendo las ventanas emergentes de <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Page_actions">acción de página</a> o <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_action">acción del navegador</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Sidebars">barras laterales</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Options_pages">páginas de opciones</a> o <a href="/en-US/Add-ons/WebExtensions/manifest.json/chrome_url_overrides">páginas de pestañas nuevas</a>. A algunas de estas API también se puede acceder mediante los <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">scripts de contenido</a> de una extensión ( consulte la <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_scripts#WebExtension_APIs">lista en la guía de script de contenido</a>).</p> + +<p>Para usar API más poderosas debes <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions">solicitar permiso</a> en manifest.json en tu extensión.</p> + +<p>Puedes acceder a las API utilizando el namespace <code>browser</code>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">logTabs</span><span class="punctuation token">(</span>tabs<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>tabs<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">query</span><span class="punctuation token">(</span><span class="punctuation token">{</span>currentWindow<span class="punctuation token">:</span> <span class="keyword token">true</span><span class="punctuation token">}</span><span class="punctuation token">,</span> logTabs<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<div> +<p>Muchas de las APIs son asíncronas, devolviendo un <code>Promise</code>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">logCookie</span><span class="punctuation token">(</span>c<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>c<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">function</span> <span class="function token">logError</span><span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">error</span><span class="punctuation token">(</span>e<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">var</span> setCookie <span class="operator token">=</span> browser<span class="punctuation token">.</span>cookies<span class="punctuation token">.</span><span class="keyword token">set</span><span class="punctuation token">(</span> + <span class="punctuation token">{</span>url<span class="punctuation token">:</span> <span class="string token">"https://developer.mozilla.org/"</span><span class="punctuation token">}</span> +<span class="punctuation token">)</span><span class="punctuation token">;</span> +setCookie<span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>logCookie<span class="punctuation token">,</span> logError<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> +</div> + +<div> +<p>Tenga en cuenta que esto es diferente del sistema de extensiones de Google Chrome, que utiliza el nombre <code>chrome</code> en lugar de <code>browser</code>, y que utiliza <code>callbacks</code> en lugar de <code>promise</code> para funciones asíncronas. Como ayuda para portar, la implementación de Firefox de la API WebExtensions admite <code>chrome</code> y <code>callbacks</code>, así como <code>browser</code> y <code>promise</code>. Mozilla también ha escrito un <em>polyfill</em> que habilita el código que usa <code>browser</code> y <code>promise</code> para trabajar sin cambios en Chrome.: <a class="external external-icon" href="https://github.com/mozilla/webextension-polyfill">https://github.com/mozilla/webextension-polyfill</a>.</p> + +<p>Firefox también implementa estas APIs bajo el nombre <code>chrome</code> usando <code>callbacks</code>. Esto permite que el código escrito para Chrome se ejecute sin cambios en Firefox para las APIs documentadas aquí.</p> + +<p>Microsoft Edge usa el namespace <code>browser</code>, pero aún no admite APIs asíncronas basadas en <code>promise</code>. En Edge, por el momento, las APIs asíncronas deben utilizar <code>callbacks</code>.</p> + +<p>No todos los navegadores son compatibles con todas las APIs: para obtener más información, consulte <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">Soporte del navegador para las API de JavaScript</a>.</p> + +<h2 id="Listado_de_API_de_JavaScript">Listado de API de JavaScript</h2> + +<p>Vea a continuación una lista completa de las API de JavaScript:</p> + +<p>Esta página lista todas las APIs JavaScript de WebExtension que actualmente son soportadas.</p> +</div> + +<div>{{SubpagesWithSummaries}}</div> + +<h2 id="Incompatibilidades_con_Chrome">Incompatibilidades con Chrome</h2> + +<p>Nosotros no soportamos ninguna API que no es listada arriba.</p> + +<p>Incluso, para las APIs que están listadas arriba, no siempre soportamos todas las propiedades que Chrome soporta. Por favor, chequea la página de la API para cualquier incompatibilidad con Chrome.</p> diff --git a/files/es/mozilla/add-ons/webextensions/api/storage/index.html b/files/es/mozilla/add-ons/webextensions/api/storage/index.html new file mode 100644 index 0000000000..a98fb1e17f --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/api/storage/index.html @@ -0,0 +1,115 @@ +--- +title: storage +slug: Mozilla/Add-ons/WebExtensions/API/storage +tags: + - API + - Add-ons + - Complentos + - Extensions + - Interface + - NeedsTranslation + - Non-standard + - Reference + - Storage + - TopicStub + - WebExtensions + - extensiones +translation_of: Mozilla/Add-ons/WebExtensions/API/storage +--- +<div>{{AddonSidebar}}</div> + +<p>Permite que las extensiones almacenen y recuperen datos, y escuchen los cambios realizados en los elementos almacenados.</p> + +<p>El sistema de almacenamiento se basa en <a href="/en-US/docs/Web/API/Web_Storage_API">Web Storage API</a>, con algunas diferencias. Entre otras diferencias, éstas incluyen:</p> + +<ul> + <li>Es asíncrono.</li> + <li>Los valores se aplican a la extensión, no a un dominio específico (es decir, el mismo conjunto de pares clave / valor está disponible para todos los scripts de tipo background y los scripts de contenido o content).</li> + <li>Los valores almacenados pueden ser cualquier valor JSON, no solo <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>. Entre otras cosas, esto incluye: <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> y <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>, pero solo cuando sus contenidos se pueden representar como JSON, que no incluye nodos DOM. No es necesario convertir sus valores en cadenas JSON antes de almacenarlos, pero se representan como JSON internamente, por lo tanto, el requisito de que sean responsables de JSON.</li> + <li>Se pueden establecer o recuperar múltiples pares de clave / valor en la misma llamada a la API.</li> +</ul> + +<p>Para usar esta API, debe incluir el <a href="/es/docs/">permiso</a> de "storage" en su archivo <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a>.</p> + +<p>Cada extensión tiene su propia área de almacenamiento, que se puede dividir en diferentes tipos de almacenamiento.</p> + +<p>Aunque esta API es similar a {{domxref ("Window.localStorage")}}, se recomienda que no use Window.localStorage en el código de extensión para almacenar datos relacionados con la extensión. Firefox borrará los datos almacenados por las extensiones utilizando la API localStorage en varios escenarios donde los usuarios borran su historial de navegación y los datos por razones de privacidad, mientras que los datos guardados utilizando la API <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/local">storage.local</a></code> se conservarán correctamente en estos escenarios.</p> + +<div class="note">El área de almacenamiento no está encriptada y no debe utilizarse para almacenar información confidencial del usuario, como claves.</div> + +<h2 id="Tipos">Tipos</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea")}}</dt> + <dd>Un objeto que representa un área de almacenamiento.</dd> + <dt>{{WebExtAPIRef("storage.StorageChange")}}</dt> + <dd>Un objeto que representa un cambio en un área de almacenamiento.</dd> +</dl> + +<h2 id="Propiedades">Propiedades</h2> + +<p>El almacenamiento tiene tres propiedades, que representan los diferentes tipos de área de almacenamiento disponible.</p> + +<dl> + <dt>{{WebExtAPIRef("storage.sync")}}</dt> + <dd>Representa el área de almacenamiento de sincronización. Los elementos en el almacenamiento de sincronización están sincronizados por el navegador y están disponibles en todas las instancias de ese navegador en el que el usuario ha iniciado sesión, en diferentes dispositivos.</dd> + <dt>{{WebExtAPIRef("storage.local")}}</dt> + <dd>Representa el área de almacenamiento local. Los elementos en el almacenamiento local son locales a la máquina en la que se instaló la extensión.</dd> + <dt>{{WebExtAPIRef("storage.managed")}}</dt> + <dd>Representa el área de almacenamiento gestionado. Los elementos en el almacenamiento gestionado los establece el administrador del dominio y son de sólo lectura para la extensión. Intentar modificar este espacio de nombres da como resultado un error.</dd> +</dl> + +<h2 id="Eventos">Eventos</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.onChanged")}}</dt> + <dd>Se dispara cuando uno o más elementos cambian en un área de almacenamiento.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.storage")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Agradecimientos</strong> + +<p> </p> + +<p>Esta API se basa en la API <a href="https://developer.chrome.com/extensions/storage"><code>chrome.storage</code></a> de Chromium. Esta documentación se deriva de <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> en el código de Chromium.</p> + +<p>Los datos de compatibilidad de Microsoft Edge son proporcionados por Microsoft Corporation y se incluyen aquí bajo la Licencia de Estados Unidos Creative Commons Attribution 3.0.</p> + +<p> </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/es/mozilla/add-ons/webextensions/api/storage/local/index.html b/files/es/mozilla/add-ons/webextensions/api/storage/local/index.html new file mode 100644 index 0000000000..8c2a288aaf --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/api/storage/local/index.html @@ -0,0 +1,95 @@ +--- +title: storage.local +slug: Mozilla/Add-ons/WebExtensions/API/storage/local +tags: + - API + - Complentos + - Storage + - WebExtension + - extensiones + - local +translation_of: Mozilla/Add-ons/WebExtensions/API/storage/local +--- +<div>{{AddonSidebar()}}</div> + +<div> +<p>Representa el área de almacenamiento local. Los elementos en el almacenamiento local son locales a la máquina en la que se instaló la extensión.</p> + +<p>El navegador puede restringir la cantidad de datos que una extensión puede almacenar en el área de almacenamiento local:</p> + +<p> Chrome limita la extensión a 5MB de datos usando esta API a menos que tenga el permiso <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions#Unlimited_storage">"unlimitedStorage" </a>.<br> + Firefox le permite solicitar el permiso "Almacenamiento ilimitado" de la versión 56 en adelante. Aún no restringe la cantidad de datos que su extensión puede almacenar, pero comenzará a hacerlo en una versión futura: por lo tanto, es una buena idea solicitar el permiso de "Almacenamiento ilimitado" ahora, si tiene la intención de almacenar una gran cantidad de datos.</p> + +<p>Cuando se desinstala la extensión, se borra su almacenamiento local asociado.</p> + +<p>También en Firefox, puede evitar que el navegador borre el almacenamiento local al desinstalar "about: config" y configurar las siguientes dos preferencias de navegador como verdaderas: "keepUuidOnUninstall" y "keepStorageOnUninstall". Esta característica se proporciona para ayudar a los desarrolladores a probar sus extensiones. Las extensiones en sí mismas no pueden cambiar estas preferencias.</p> + +<p>Aunque esta API es similar a Window.localStorage, se recomienda que no use Window.localStorage en el código de extensión. Firefox borrará los datos almacenados por las extensiones utilizando la API localStorage en varios escenarios donde los usuarios borran su historial de navegación y los datos por razones de privacidad, mientras que los datos guardados utilizando la API storage.local se conservarán correctamente en estos escenarios.</p> +</div> + +<h2 id="Metodos">Metodos</h2> + +<p>El objeto local implementa los métodos definidos en el{{WebExtAPIRef("storage.StorageArea")}} tipo:</p> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea.get()")}}</dt> + <dd>Recupera uno o más elementos del área de almacenamiento.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.getBytesInUse()")}}</dt> + <dd>Obtiene la cantidad de espacio de almacenamiento (en bytes) utilizado por uno o más elementos que se almacenan en el área de almacenamiento.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.set()")}}</dt> + <dd>Almacena uno o más artículos en el área de almacenamiento. Si el artículo ya existe, su valor será actualizado. Cuando establezca un valor, se activará el evento {{WebExtAPIRef ("storage.onChanged")}}.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.remove()")}}</dt> + <dd>Elimina uno o más elementos del área de almacenamiento.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.clear()")}}</dt> + <dd>Elimina todos los elementos del área de almacenamiento.</dd> +</dl> + +<h2 id="Compatibilidad_del_navegador">Compatibilidad del 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.storage.local")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Agradecimientos</strong> + +<p> </p> + +<p>Esta API se basa en la API <a href="https://developer.chrome.com/extensions/storage#property-local"><code>chrome.storage</code></a> de Chromium. Esta documentación se deriva de <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> en el código de Chromium.</p> + +<p>Los datos de compatibilidad de Microsoft Edge son proporcionados por Microsoft Corporation y se incluyen aquí bajo la Licencia de Estados Unidos Creative Commons Attribution 3.0.</p> + +<p> </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/es/mozilla/add-ons/webextensions/api/storage/sync/index.html b/files/es/mozilla/add-ons/webextensions/api/storage/sync/index.html new file mode 100644 index 0000000000..74fc334dbc --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/api/storage/sync/index.html @@ -0,0 +1,79 @@ +--- +title: storage.sync +slug: Mozilla/Add-ons/WebExtensions/API/storage/sync +tags: + - Complementos Extensiones +translation_of: Mozilla/Add-ons/WebExtensions/API/storage/sync +--- +<div>{{AddonSidebar()}}</div> + +<p>Representa el área de almacenamiento de sincronización. Los elementos en el almacenamiento de sincronización están sincronizados por el navegador y están disponibles en todas las instancias de ese navegador en el que el usuario está conectado (por ejemplo, a través de Firefox Sync o una cuenta de Google), en diferentes dispositivos.</p> + +<p>Para Firefox, un usuario debe tener complementos seleccionados en las opciones de "about:preferences".</p> + +<p>Tenga en cuenta que la implementación de storage.sync en Firefox se basa en la ID del complemento. Si usa storage.sync, debe establecer una ID para su extensión usando la clave <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> manifest.json.</p> + +<p>El principal caso de uso de esta API es almacenar las preferencias sobre su extensión y permitir que el usuario las sincronice con diferentes perfiles. Puede almacenar hasta 100 KB de datos utilizando esta API. Si intenta almacenar más que esto, la llamada fallará con un mensaje de error. La API se proporciona sin ninguna garantía sobre el tiempo de actividad o el rendimiento.</p> + +<p>Metodos</p> + +<p>El objeto de sincronización implementa los métodos definidos en el {{WebExtAPIRef("storage.StorageArea")}} ponga:</p> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea.get()")}}</dt> + <dd>Recupera uno o más elementos del área de almacenamiento.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.getBytesInUse()")}}</dt> + <dd>Obtiene la cantidad de espacio de almacenamiento (en bytes) utilizado por uno o más elementos que se almacenan en el área de almacenamiento.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.set()")}}</dt> + <dd>Almacena uno o más artículos en el área de almacenamiento. Si el artículo ya existe, su valor será actualizado.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.remove()")}}</dt> + <dd>Elimina uno o más elementos del área de almacenamiento.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.clear()")}}</dt> + <dd>Elimina todos los elementos del área de almacenamiento.</dd> +</dl> + +<h2 id="Compatibilidad_del_navegador">Compatibilidad del 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.storage.sync")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Agradecimientos</strong> + +<p>Esta API está basada en la API de Chromium's <a href="https://developer.chrome.com/extensions/storage#property-sync"><code>chrome.storage</code></a> API. Esta documentación se deriva de <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> en el código de Chromium.</p> + +<p>Los datos de compatibilidad de Microsoft Edge son proporcionados por Microsoft Corporation y se incluyen aquí bajo la Licencia de Estados Unidos Creative Commons Attribution 3.0.</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/es/mozilla/add-ons/webextensions/api/webnavigation/index.html b/files/es/mozilla/add-ons/webextensions/api/webnavigation/index.html new file mode 100644 index 0000000000..d561c6d796 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/api/webnavigation/index.html @@ -0,0 +1,144 @@ +--- +title: webNavigation +slug: Mozilla/Add-ons/WebExtensions/API/webNavigation +translation_of: Mozilla/Add-ons/WebExtensions/API/webNavigation +--- +<div>{{AddonSidebar}}</div> + +<p>Add event listeners for the various stages of a navigation. A navigation consists of a frame in the browser transitioning from one URL to another, usually (but not always) in response to a user action like clicking a link or entering a URL in the location bar.</p> + +<p>Compared with the {{WebExtAPIRef("webRequest")}} API: navigations usually result in the browser making web requests, but the webRequest API is concerned with the lower-level view from the HTTP layer, while the webNavigation API is more concerned with the view from the browser UI itself.</p> + +<p>Each event corresponds to a particular stage in the navigation. The sequence of events is like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13374/we-flow.png" style="display: block; height: 562px; margin-left: auto; margin-right: auto; width: 745px;"></p> + +<ul> + <li>The primary flow is: + <ul> + <li><code>{{WebExtAPIRef("webNavigation.onBeforeNavigate", "onBeforeNavigate")}}</code></li> + <li><code>{{WebExtAPIRef("webNavigation.onCommitted", "onCommitted")}}</code></li> + <li><code>{{WebExtAPIRef("webNavigation.onDOMContentLoaded", "onDOMContentLoaded")}}</code></li> + <li><code>{{WebExtAPIRef("webNavigation.onCompleted", "onCompleted")}}</code>.</li> + </ul> + </li> + <li>Additionally: + <ul> + <li><code>{{WebExtAPIRef("webNavigation.onCreatedNavigationTarget", "onCreatedNavigationTarget")}}</code> is fired before <code>onBeforeNavigate</code> if the browser needed to create a new tab or window for the navigation (for example, because the user opened a link in a new tab).</li> + <li>{{WebExtAPIRef("webNavigation.onHistoryStateUpdated", "onHistoryStateUpdated")}} is fired if a page uses the <a href="http://diveintohtml5.info/history.html">history API</a> to update the URL displayed in the browser's location bar.</li> + <li>{{WebExtAPIRef("webNavigation.onReferenceFragmentUpdated", "onReferenceFragmentUpdated")}} is fired if the <a href="https://en.wikipedia.org/wiki/Fragment_identifier">fragment identifier</a> for a page is changed.</li> + <li>{{WebExtAPIRef("webNavigation.onErrorOccurred", "onErrorOccurred")}} can be fired at any point.</li> + </ul> + </li> +</ul> + +<p>Each navigation is a URL transition in a particular browser frame. The browser frame is identified by a tab ID and a frame ID. The frame may be the top-level browsing context in the tab, or may be a nested browsing context implemented as an <a href="/en-US/docs/Web/HTML/Element/iframe">iframe</a>.</p> + +<p>Each event's <code>addListener()</code> call accepts an optional filter parameter. The filter will specify one or more URL patterns, and the event will then only be fired for navigations in which the target URL matches one of the patterns.</p> + +<p>The <code>onCommitted</code> event listener is passed two additional properties: a {{WebExtAPIRef("webNavigation.TransitionType","TransitionType")}} indicating the cause of the navigation (for example, because the user clicked a link, or because the user selected a bookmark), and a {{WebExtAPIRef("webNavigation.TransitionQualifier","TransitionQualifier")}} providing further information about the navigation.</p> + +<p>To use this API you need to have the "webNavigation" <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permission</a>.</p> + +<h2 id="Types">Types</h2> + +<dl> + <dt>{{WebExtAPIRef("webNavigation.TransitionType")}}</dt> + <dd>Cause of the navigation: for example, the user clicked a link, or typed an address, or clicked a bookmark.</dd> + <dt>{{WebExtAPIRef("webNavigation.TransitionQualifier")}}</dt> + <dd> + <div>Extra information about a transition.</div> + </dd> +</dl> + +<h2 id="Functions">Functions</h2> + +<dl> + <dt>{{WebExtAPIRef("webNavigation.getFrame()")}}</dt> + <dd>Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe">iframe</a>, and is uniquely identified by a tab ID and a frame ID.</dd> + <dt>{{WebExtAPIRef("webNavigation.getAllFrames()")}}</dt> + <dd> + <p>Given a tab ID, retrieves information about all the frames it contains.</p> + </dd> +</dl> + +<h2 id="Events">Events</h2> + +<dl> + <dt>{{WebExtAPIRef("webNavigation.onBeforeNavigate")}}</dt> + <dd> + <p>Fired when the browser is about to start a navigation event.</p> + </dd> + <dt>{{WebExtAPIRef("webNavigation.onCommitted")}}</dt> + <dd>Fired when a navigation is committed. At least part of the new document has been received from the server and the browser has decided to switch to the new document.</dd> + <dt>{{WebExtAPIRef("webNavigation.onDOMContentLoaded")}}</dt> + <dd>Fired when the <a href="https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded">DOMContentLoaded</a> event is fired in the page.</dd> + <dt>{{WebExtAPIRef("webNavigation.onCompleted")}}</dt> + <dd>Fired when a document, including the resources it refers to, is completely loaded and initialized. This is equivalent to the DOM <code><a href="https://developer.mozilla.org/en-US/docs/Web/Events/load">load</a></code> event.</dd> + <dt>{{WebExtAPIRef("webNavigation.onErrorOccurred")}}</dt> + <dd>Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation.</dd> + <dt>{{WebExtAPIRef("webNavigation.onCreatedNavigationTarget")}}</dt> + <dd>Fired when a new window, or a new tab in an existing window, is created to host a navigation: for example, if the user opens a link in a new tab.</dd> + <dt>{{WebExtAPIRef("webNavigation.onReferenceFragmentUpdated")}}</dt> + <dd>Fired if the <a class="external-icon external" href="https://en.wikipedia.org/wiki/Fragment_identifier">fragment identifier</a> for a page is changed.</dd> + <dt>{{WebExtAPIRef("webNavigation.onTabReplaced")}}</dt> + <dd> + <p>Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.</p> + </dd> + <dt>{{WebExtAPIRef("webNavigation.onHistoryStateUpdated")}}</dt> + <dd>Fired when the page used the <a class="external external-icon" href="http://diveintohtml5.info/history.html">history API</a> to update the URL displayed in the browser's location bar.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p>{{Compat("webextensions.api.webNavigation")}}</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> + +<h3 id="Edge_incompatibilities">Edge incompatibilities</h3> + +<p>Promises are not supported in Edge. Use callbacks instead.</p> + +<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/webNavigation"><code>chrome.webNavigation</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/web_navigation.json"><code>web_navigation.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/es/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.html b/files/es/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.html new file mode 100644 index 0000000000..1dffe19399 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/browser_support_for_javascript_apis/index.html @@ -0,0 +1,15 @@ +--- +title: Browser support for JavaScript APIs +slug: Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs +translation_of: Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs +--- +<div>{{AddonSidebar}}</div> + +<div>{{WebExtAllCompatTables}}</div> + +<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> + +<div class="note"><strong>Acknowledgements</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/es/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html b/files/es/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html new file mode 100644 index 0000000000..34668d6ba1 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/chrome_incompatibilities/index.html @@ -0,0 +1,291 @@ +--- +title: Incompatibilidades con Chrome +slug: Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities +--- +<p><span style="background-color: #ffffff; color: #333333; display: inline !important; float: none; font-family: arial,x-locale-body,sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-decoration-style: initial; text-indent: 0px; text-transform: none; white-space: normal;">WebExtensions está diseñado para ser compatible con las extensiones de Chrome y Opera: en la medida de lo posible, las extensiones escritas para esos navegadores deberían ejecutarse en Firefox con cambios mínimos.</span></p> + +<p style="margin: 0px 0px 24px; padding: 0px; border: 0px; color: rgb(51, 51, 51); font-family: arial, x-locale-body, sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-style: initial;"><font><font>Sin embargo, Firefox cuenta actualmente con soporte para sólo un conjunto limitado de funciones y API compatibles con Chrome y Opera.<span> </span></font><font>Estamos trabajando en agregar más soporte, pero muchas características aún no son compatibles, y es posible que nunca admitamos algunas.</font></font></p> + +<p style="margin: 0px 0px 24px; padding: 0px; border: 0px; color: rgb(51, 51, 51); font-family: arial, x-locale-body, sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-style: initial;"><font><font>En este artículo se enumeran todas las características y API que se admiten total o parcialmente en Firefox.<span> </span></font><font>Cuando una característica está parcialmente soportada, hemos indicado cuáles son las lagunas.</font></font></p> + +<p style="margin: 0px 0px 24px; padding: 0px; border: 0px; color: rgb(51, 51, 51); font-family: arial, x-locale-body, sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-style: initial;"><font><font>Es seguro asumir que las funciones y las API que no se enumeran aquí en absoluto aún no son compatibles.</font></font></p> + +<h2 id="Funciones_de_manifest.json">Funciones de manifest.json</h2> + +<h3 id="Claves_completamente_compatibles">Claves completamente compatibles</h3> + +<ul> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">applications</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/default_locale">default_locale</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/description">description</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/name">name</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/version">version</a></code></li> + <li><code><a href="/en-US/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code></li> +</ul> + +<h3 id="Claves_parcialmente_admitidas">Claves parcialmente admitidas</h3> + +<h4 id="Datos_de_fondo">Datos de fondo</h4> + +<p>Firefox no admite la propiedad <code>"persistent"</code>. Los scripts de fondo permanecen cargados todo el tiempo.</p> + +<h4 id="Scripts_de_contenido">Scripts de contenido</h4> + +<p>Firefox no admite actualmente:</p> + +<ul> + <li><code>include_globs</code></li> + <li><code>exclude_globs</code></li> + <li><code>match_about_blank</code></li> +</ul> + +<h4 id="Permisos">Permisos</h4> + +<p><span style="background-color: #ffffff; color: #333333; display: inline !important; float: none; font-family: arial,x-locale-body,sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-decoration-style: initial; text-indent: 0px; text-transform: none; white-space: normal;">Firefox aún no admite los siguientes permisos</span>:</p> + +<ul> + <li><code>activeTab</code></li> + <li><code>background</code></li> + <li><code>clipboardRead</code></li> + <li><code>clipboardWrite</code></li> + <li><code>geolocation</code></li> + <li><code>nativeMessaging</code></li> + <li><code>unlimitedStorage</code></li> +</ul> + +<p><span style="background-color: #ffffff; color: #333333; display: inline !important; float: none; font-family: arial,x-locale-body,sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-decoration-style: initial; text-indent: 0px; text-transform: none; white-space: normal;">Obviamente, también no admite permisos para las</span> <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API#Chrome_incompatibilities">APIs que no son compatibles</a>.</p> + +<h2 id="APIs_JavaScript">APIs JavaScript</h2> + +<h3 id="APIs_completamente_soportadas">APIs completamente soportadas</h3> + +<ul> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/API/alarms">alarmas</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/API/contextMenus">Menú contextual</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">pageAction</a> + <ul> + <li><font><font>Las URL relativas pasadas a<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: normal; font-weight: normal; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word; font-size: medium; letter-spacing: normal; text-align: left; text-indent: 0px; text-transform: none; white-space: normal; text-decoration-style: initial;'>setPopup()</code><font><font>se resuelven en relación con el documento de la persona que llama, en lugar de con la raíz de la extensión</font></font> .</li> + </ul> + </li> +</ul> + +<h3 id="APIs_parcialmente_soportadas">APIs parcialmente soportadas</h3> + +<h4 id="marcadores">marcadores</h4> + +<ul> + <li>Firefox no admite: + <ul> + <li><code>getRecent()</code></li> + <li><code>search()</code></li> + <li><code>removeTree()</code> (<code>remove</code> también elimina carpetas no vacías)</li> + <li><code>onCreated</code></li> + <li><code>onRemoved</code></li> + <li><code>onChanged</code></li> + <li><code>onMoved</code></li> + <li><code>onChildrenReordered</code></li> + <li><code>onImportBegan</code></li> + <li><code>onImportEnded</code></li> + <li>BookmarkTreeNodeUnmodifiable</li> + </ul> + </li> + <li>Firefox tiene marcadores especiales como "Marcado recientemente" o "Visitado recientemente"</li> +</ul> + +<h4 id="browserAction">browserAction</h4> + +<ul> + <li>Firefox no admite: + <ul> + <li><code>enable()</code> o <code>disable()</code>.</li> + </ul> + </li> + <li><font><font>Las URL relativas pasadas a<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: normal; font-weight: normal; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word; font-size: medium; letter-spacing: normal; text-align: left; text-indent: 0px; text-transform: none; white-space: normal; text-decoration-style: initial;'>setPopup()</code><font><font>se resuelven en relación con el documento de la persona que llama, en lugar de con la raíz de la extensión</font></font> .</li> +</ul> + +<h4 id="cookies">cookies</h4> + +<ul> + <li style="margin: 0px 0px 6px; padding: 0px; border: 0px;"><font><font>eventos onChanged pueden ser subtely diferentes</font></font></li> + <li style="margin: 0px 0px 6px; padding: 0px; border: 0px;"><font><font>Creación de cookies de sesión<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: inherit; font-weight: inherit; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word;'>set</code><font><font>podría fallar</font></font></li> + <li><code class="prettyprint">getAllCookieStores</code> siempre<font><font> devuelve un almacén predeterminado y sin pestañas</font></font></li> + <li style="margin: 0px 0px 6px; padding: 0px; border: 0px;"><font><font>el acceso a las cookies desde pestañas privadas es imposible</font></font></li> +</ul> + +<h4 id="extension">extension</h4> + +<ul> + <li>Firefox sólo soporta : + <ul> + <li><code>getBackgroundPage()</code></li> + <li><code>getURL()</code></li> + <li><code>inIncognitoContext</code> en los scripts de contenido</li> + </ul> + </li> +</ul> + +<h4 id="i18n">i18n</h4> + +<ul> + <li><span style="background-color: #ffffff; color: #333333; display: inline !important; float: none; font-family: arial,x-locale-body,sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: left; text-decoration-style: initial; text-indent: 0px; text-transform: none; white-space: normal;">En la API JavaScript API, Firefox solo soporta</span> <code>getMessage()</code>.</li> + <li>Firefox solo soporta los mensajes predefinidos <code>@@extension_id</code> y <code>@@ui_locale</code>.</li> + <li>Firefox no localiza archivos CSS.</li> + <li>Las cadenas para ser localizadas deben consistir enteramente de <code>__MSG_foo__</code> con el fin de realizar una sustitución al crearlas.</li> +</ul> + +<h4 id="notifications">notifications</h4> + +<ul> + <li><span style="background-color: #ffffff; color: #333333; display: inline !important; float: none; font-family: arial,x-locale-body,sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: left; text-decoration-style: initial; text-indent: 0px; text-transform: none; white-space: normal;">Las únicas opciones de notificación admitidas son</span> : + + <ul> + <li><code>iconUrl</code></li> + <li><code>title</code></li> + <li><code>message</code>.</li> + </ul> + </li> + <li><span style="background-color: #ffffff; color: #333333; display: inline !important; float: none; font-family: arial,x-locale-body,sans-serif; font-size: medium; font-style: normal; font-weight: normal; letter-spacing: normal; text-align: left; text-decoration-style: initial; text-indent: 0px; text-transform: none; white-space: normal;">Los únicos métodos soportados son</span> : + <ul> + <li><code>create()</code></li> + <li><code>clear()</code></li> + <li><code>getAll()</code>.</li> + </ul> + </li> + <li style="margin: 0px 0px 6px; padding: 0px; border: 0px;"><font><font>El único evento soportado es<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: inherit; font-weight: inherit; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word;'>onClosed</code><font><font>.</font></font></li> + <li style="margin: 0px 0px 6px; padding: 0px; border: 0px;"><font><font>Firefox no proporciona<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: inherit; font-weight: inherit; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word;'>byUser</code><font><font>datos.</font></font></li> +</ul> + +<h4 id="Tiempo_de_ejecución">Tiempo de ejecución</h4> + +<ul> + <li>Firefox sólo admite: + <ul> + <li><code>onStartup()</code></li> + <li><code>getManifest()</code></li> + <li><code>getURL()</code></li> + <li><code>id</code></li> + <li><code>sendMessage()</code></li> + <li><code>onMessage</code></li> + <li><code>onConnect</code></li> + </ul> + </li> +</ul> + +<h4 id="Almacenamiento">Almacenamiento</h4> + +<ul> + <li style="margin: 0px 0px 6px; padding: 0px; border: 0px;"><font><font>El único área de almacenamiento que soporta Firefox es<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: inherit; font-weight: inherit; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word;'>local</code><font><font>.</font></font></li> + <li style="margin: 0px 0px 6px; padding: 0px; border: 0px;"><font><font>Firefox no soporta<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: inherit; font-weight: inherit; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word;'>getBytesInUse()</code><font><font>o<span> </span></font></font><code style='background-color: rgb(238, 238, 238); color: rgb(51, 51, 51); margin: 0px; padding: 2px 5px; border: 0px; font-style: inherit; font-weight: inherit; border-radius: 2px; font-family: consolas, "Liberation Mono", courier, monospace; word-wrap: break-word;'>clear))</code><font><font>.</font></font></li> +</ul> + +<h4 id="tabs">tabs</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>getCurrent()</code></li> + <li><code>sendRequest()</code></li> + <li><code>getSelected()</code></li> + <li><code>duplicate()</code></li> + <li><code>highlight()</code></li> + <li><code>move()</code></li> + <li><code>detectLanguage()</code></li> + <li><code>captureVisibleTab()</code></li> + <li><code>getZoom()</code></li> + <li><code>setZoom()</code></li> + <li><code>getZoomSettings()</code></li> + <li><code>setZoomSettings()</code></li> + </ul> + </li> +</ul> + +<p>Firefox treats <code>highlighted</code> and <code>active</code> as the same since Firefox cannot select multiple tabs.</p> + +<p>Firefox doesn't yet support the <code>callback</code> argument to <code>executeScript()</code>.</p> + +<h4 id="webNavigation">webNavigation</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>getFrame()</code></li> + <li><code>getAllFrames()</code></li> + <li><code>onCreatedNavigationTarget</code></li> + <li><code>onHistoryStateUpdated</code></li> + <li>transition types and qualifiers</li> + <li>Filtering</li> + </ul> + </li> +</ul> + +<p><code>onReferenceFragmentUpdated</code> also triggers for <code>pushState</code>.</p> + +<h4 id="webRequest">webRequest</h4> + +<ul> + <li>Firefox does not support: + <ul> + <li><code>handlerBehaviorChanged()</code></li> + <li><code>onAuthRequired</code></li> + <li><code>onBeforeRedirect</code></li> + <li><code>onErrorOccurred</code></li> + </ul> + </li> + <li>Requests can be: + <ul> + <li>canceled only in <code>onBeforeRequest</code></li> + <li>modified/redirected only in <code>onBeforeSendHeaders</code></li> + </ul> + </li> + <li>Responses can be modified only in <code>onHeadersReceived</code>.</li> + <li>Filtering by <code>windowId</code> and <code>tabId</code> is not supported.</li> + <li>The <code>"requestBody"</code> instruction in <code>opt_extraInfoSpec</code> is not supported.</li> + <li>Redirection is not allowed in <code>onBeforeRequest</code> or <code>onHeadersReceived</code>, but is allowed in <code>onBeforeSendHeaders</code>.</li> + <li><code>requestId</code> is not included in the argument passed to the listener.</li> +</ul> + +<h4 id="windows">windows</h4> + +<ul> + <li><code>onFocusChanged</code> will trigger multiple times for a given focus change.</li> + <li><code>create()</code> does not support the <code>focused</code>, <code>type</code>, or <code>state</code> options.</li> + <li><code>update()</code> only supports the <code>focused</code> option.</li> +</ul> + +<h3 id="Planned_APIs">Planned APIs</h3> + +<p>We don't yet support the following APIs, but plan to, soon:</p> + +<ul> + <li><a class="external text" href="https://developer.chrome.com/extensions/commands" rel="nofollow">commands</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/devtools" rel="nofollow">Devtools (mostly panels)</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/downloads" rel="nofollow">downloads</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/history" rel="nofollow">history</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/idle" rel="nofollow">idle</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/omnibox" rel="nofollow">omnibox</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/permissions" rel="nofollow">permissions</a></li> + <li><a class="external text" href="https://developer.chrome.com/extensions/runtime#method-connectNative" rel="nofollow">Native messaging (runtime.connectNative)</a></li> +</ul> + +<h3 id="CSS">CSS</h3> + +<h4 id="Localized_String_Interpolation">Localized String Interpolation</h4> + +<p>We currently do not support interpolation of localized strings <code>__MSG_</code> tokens in extension CSS files: {{bug(1209184)}}.</p> + +<h4 id="Relative_URLs">Relative URLs</h4> + +<p>We resolve URLs in injected CSS files relative to the CSS file itself, rather than to the page it's injected into.</p> + +<h3 id="Miscellaneous_incompatibilities">Miscellaneous incompatibilities</h3> + +<ul> + <li>Chrome allows any optional arguments to be omitted, even if followed by other arguments. Firefox currently supports this only under specific circumetances. We recommend only omitting optional arguments at the end of the arguments list, and using <code>null</code> for all other cases.</li> + <li>Firefox currently <a href="https://bugzil.la/932513">does not allow</a> the <code>{{jsxref("Statements/let", "let")}}</code> or <code>{{jsxref("Statements/const", "const")}}</code> statement in ordinary web pages or Web Extensions. While it is possible to enable support for Firefox's variant of the statement using a special <code><script></code> tag, this is not recommended. Instead, if your extension code uses <code>let</code> or <code>const</code> statements, we recommend that you <a href="/en-US/Add-ons/WebExtensions/Tips#Using_advanced_JavaScript_features_from_ECMAScript_6_and_7">transpile them using Babel</a> until support is turned on globally.</li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/depuración/index.html b/files/es/mozilla/add-ons/webextensions/depuración/index.html new file mode 100644 index 0000000000..c24f9d07f5 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/depuración/index.html @@ -0,0 +1,189 @@ +--- +title: Depuración +slug: Mozilla/Add-ons/WebExtensions/Depuración +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Debugging +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>Las técnicas descritas aquí funcionan en Firefox 50 y versiones sucesivas. Si necesitas usar una versión anterior de Firefox, por favor ve al artículo <a href="/en-US/Add-ons/WebExtensions/Debugging_(before_Firefox_50)">debugging extensions using WebExtension APIs before Firefox 50</a>.</p> +</div> + +<p>Este artículo explica cómo se pueden usar las herramientas de desarrollo de Firefox para depurar extensiones creadas con las WebExtension APIs.</p> + +<p>Una WebExtension puede consistir en varias partes distintas — scripts en segundo plano, popups, options pages, content scripts — y se tendrá que usar un proceso ligeramente distinto para depurar cada parte. Así, cada parte tendrá una sección principal en este artículo, y el objetivo es que esas secciones se puedan leer de forma independiente. Empezaremos presentando el Depurador de Add-on, que será usado para depurar la mayoría de las partes de un complemento.</p> + +<ul> +</ul> + +<h2 class="western" id="El_Depurador_de_Add-on">El Depurador de Add-on</h2> + +<p>Para la mayor parte de este artículo utilizaremos el Depurador de Add-on. Para abrir el Depurador de Add-on:</p> + +<ul> + <li> + <p style="margin-bottom: 0cm;">abrir Firefox</p> + </li> + <li> + <p style="margin-bottom: 0cm;">escribir "about:debugging" en la barra de direcciones</p> + </li> + <li> + <p style="margin-bottom: 0cm;">marcar la casilla en la que pone "Activar depuración de complementos"</p> + </li> + <li> + <p style="margin-bottom: 0cm;">hacer click en el botón "Depurar" al lado del complemento</p> + </li> + <li> + <p>hacer click en "Aceptar" en el cuadro de alerta</p> + </li> +</ul> + +<p>Se abrirá entonces una nueva ventana. La ventana principal de Firefox se pondrá en primer plano, así que se tendrá que hacer click en la nueva ventana para que aparezca en primer plano.</p> + +<p>{{EmbedYouTube("HMozipAjrYA")}}</p> + +<p>Esta nueva ventana se llama "Herramientas de desarrollo" y contiene las herramientas de depuración que se usarán. La interfaz tiene varias pestañas en la parte de arriba que permiten moverse por las herramientas disponibles:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13861/toolbox-tabs.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<p>En este artículo usaremos tres herramientas de depuración:</p> + +<ul> + <li> + <p style="margin-bottom: 0cm;"><a href="https://developer.mozilla.org/es/docs/Tools/Web_Console">La Consola</a>: muestra mensajes registrados por la extensión así como mensajes de error registrados por el navegador mientras ejecuta la extensión. También proporciona una línea de comandos, habilitando la ejecución de JavaScript en el contexto de la extensión.</p> + </li> + <li> + <p style="margin-bottom: 0cm;"><a href="https://developer.mozilla.org/es/docs/Tools/Debugger">El Depurador</a>: habilita el uso de breakpoints y watchpoints en el código JavaScript de la extensión, y examina y modifica su estado interno.</p> + </li> + <li> + <p><a href="https://developer.mozilla.org/es/docs/Tools/Page_Inspector">El Inspector</a>: habilita la revisión y modificación del HTML y CSS usado para construir las páginas de la extensión.</p> + </li> +</ul> + +<h2 class="western" id="Depurando_scripts_en_segundo_plano">Depurando scripts en segundo plano</h2> + +<div class="note"> +<p>Los ejemplos de esta sección usan la extensión de ejemplo "notify-link-clicks-l10n". Para explorar las opciones, se puede encontrar este ejemplo en el repositorio <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a>.</p> +</div> + +<p>Los <a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#Scripts_en_segundo_plano">scripts en segundo plano</a> permanecen cargados durante el tiempo de vida de la extensión. Se cargan dentro de una “página en segundo plano” invisible: por defecto, es un documento HTML vacío, pero se puede especificar contenido HTML propio usando la palabra clave <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/background">"background"</a> en “manifest.json”.</p> + +<p>Se pueden depurar scripts en segundo plano usando el <a href="/en-US/Add-ons/WebExtensions/Debugging_(Firefox_50_onwards)#The_Add-on_Debugger">Depurador de Add-ons</a>.</p> + +<p>En la Consola del Depurador de Add-ons se puede ver un registro de las salidas, incluidas las llamadas a <code><a href="/en-US/docs/Web/API/Console/log">console.log()</a></code> desde los propios scripts en segundo plano y cualquier error que el navegador encuentre al ejecutarlos. Es importante mencionar que la consola muestra todos los errores detectados por el navegador, no sólo los errores relacionados con el código de la extensión.</p> + +<p>Por ejemplo, la extensión de ejemplo <a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> registra un mensaje de su script en segundo plano cuando recibe un mensaje de uno de sus otros scripts:</p> + +<p>{{EmbedYouTube("WDQsBU-rpN0")}}</p> + +<p>Usando la línea de comandos de la Consola, se pueden acceder y modificar los objetos creados por los scripts en segundo plano.</p> + +<p>Por ejemplo, aquí se hace un allamada a la función <code>notify()</code> definida en el script en segundo plano de la extensión:</p> + +<p>{{EmbedYouTube("g-Qgf8Mc2wg")}}</p> + +<p>Si se mira la ventana del Depurador, se pueden ver todos los scripts en segundo plano de la extensión. Se pueden definir breakpoints, ver el código paso a paso y hacer <a href="https://developer.mozilla.org/es/docs/Tools/Debugger">todo lo que es posible hacer en un depurador</a>.</p> + +<p>{{EmbedYouTube("MNeaz2jdmzY")}}</p> + +<p>Si se pulsa la tecla de Escape mientras se está en el Depurador, la ventana de Herramientas de desarrollo se dividirá en dos, con la parte de abajo ocupada ahora por la Consola. Ahora, mientras se esté en un breakpoint, se puede modificar el estado del programa usando la consola. Ver <a href="/en-US/docs/Tools/Web_Console/Split_console">Dividir la Consola</a> para más información.</p> + +<h2 class="western" id="Depurando_páginas_de_opciones">Depurando páginas de opciones</h2> + +<p>Las <font color="#000080"><span lang="zxx"><u><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension#P%C3%A1gina_de_opciones">páginas de opciones</a></u></span></font> son páginas HTML que pueden ser proporcionadas por la persona que desarrolle la extensión y contienen opciones para la misma. Se muestran normalmente en un iframe en el Add-ons Manager (para ver el Add-ons Manager, visita la página "about:addons").</p> + +<p>Para depurar páginas de opciones:</p> + +<ul> + <li> + <p style="margin-bottom: 0cm;">abrir el <font color="#000080"><span lang="zxx"><u><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Debugging#The_Add-on_Debugger">Depurador de Add-on</a></u></span></font> para la add-on en cuestión</p> + </li> + <li> + <p>abrir la página de opciones de la add-on.</p> + </li> +</ul> + +<p>Cualquier archivo fuente en JavaScript que incluya será listado en el Depurador:</p> + +<p>{{EmbedYouTube("BUMG-M8tFF4")}}</p> + +<div class="note"> +<p>Este vídeo usa el ejemplo de WebExtension <font color="#000080"><span lang="zxx"><u><a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colourbeastify">favourite-colour</a></u></span></font>.</p> +</div> + +<p>También se verá cualquier mensaje registrado por el código en la Consola del Depurador de Add-on.</p> + +<p>También se puede usar el Depurador de Add-on para depurar el código HTML y CSS de la página. Pero primero se necesita dirigir las herramientas al iframe que alberga la página de opciones. Para hacer esto: abre la página de opciones, haz clic en el icono indicado en la captura de pantalla mostrada a continuación y selecciona la página de opciones del menú desplegable:</p> + +<p class="western" style="margin-bottom: 0cm; line-height: 100%;"><img alt="" src="https://mdn.mozillademos.org/files/13863/toolbox-iframe.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;">Ahora al cambiar a la pestaña Inspector se podrá examinar y editar el HTML y CSS para la página:</p> + +<p class="western" style="margin-bottom: 0cm; line-height: 100%;"> </p> + +<p>{{EmbedYouTube("-2m3ubFAU94")}}</p> + +<h2 class="western" id="Depurando_ventanas_emergentes">Depurando ventanas emergentes</h2> + +<p><font color="#000080"><span lang="zxx"><u><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Popups">Las ventanas emergentes</a></u></span></font> son cuadros de diálogo unidos a acciones del navegador o de la página. Se especifican usando un documento HTML que puede incluir fuentes CSS y JavaScript para determinar el estilo y el funcionamiento. Cuando la ventana emergente es visible, se puede usar el <a href="/en-US/Add-ons/WebExtensions/Debugging_(Firefox_50_onwards)#The_Add-on_Debugger">Depurador de Add-on</a> para depurar su código.</p> + +<p>Un problema con las ventanas emergentes es que si una ventana emergente está abierta y se hace clic fuera de ella, esta se cierra y su código se descarga. Obviamente, esto hace que sea imposible depurarlas. Para eliminar este comportamiento, se debe hacer clic en el botón del Depurador de Add-on destacado en la captura de pantalla mostrada a continuación:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13877/toolbox-popup.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<p class="western" style="margin-bottom: 0cm; line-height: 100%;">Ahora, al abrir una ventana emergente esta continuará abierta hasta que se pulse Escape.</p> + +<p class="western" style="margin-bottom: 0cm; line-height: 100%;"> </p> + +<div class="note"> +<p>Es importante señalar que esta opción está disponible para ventanas emergentes desarrolladas para el navegador, como el menú de hamburguesa (<img style="height: 20px; width: 22px;"> ), así como a ventanas emergentes propias de la add-on.</p> + +<p>También es importante notar que el cambio es persistente, incluso aunque el navegador se reinicie. Estamos trabajando en solucionar esto en el <font color="#000080"><span lang="zxx"><u><a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1251658">bug 1251658</a></u></span></font>, pero hasta entonces puede ser mejor permitir de nuevo la ocultación automática<strong> </strong>volviendo a hacer clic en el botón antes de cerrar la Caja de Herramientas del Navegador.</p> + +<p>Internamente, este botón simplemente cambia la preferencia <code class="western">ui.popup.disable_autohide</code>, lo que se puede hacer manualmente usando about:config.</p> +</div> + +<p>Cuando la ventana emergente está abierta, sus fuentes de JavaScript se listarán en el Depurador. Se pueden colocar breakpoints y modificar el estado interno del programa:</p> + +<p>{{EmbedYouTube("hzwnR8qoz2I")}}</p> + +<div class="note"> +<p>Este vídeo usa la extensión de ejemplo <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a>.</p> +</div> + +<p>También se puede usar el Depurador de Add-on para depurar el código HTML y CSS de la ventana emergente. Pero primero se necesita dirigir las herramientas al documento de la ventana emergente. Para hacer esto: abre la ventana emergente, haz clic en el icono indicado en la captura de pantalla mostrada a continuación y selecciona la página de la ventana emergente del menú desplegable:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13863/toolbox-iframe.png" style="display: block; height: 417px; margin-left: auto; margin-right: auto; width: 876px;"></p> + +<p>Ahora al cambiar a Inspector se podrán examinar y editar el HTML y el CSS de la ventana emergente:</p> + +<p>{{EmbedYouTube("6lvdm7jaq7Y")}}</p> + +<h2 class="western" id="Depurando_scripts_de_contenido">Depurando scripts de contenido</h2> + +<p>Se puede usar el Depurador de Add-on para depurar páginas en segundo plano, páginas de opciones y ventanas emergentes. Sin embargo, no se puede usar para depurar scripts de contenido. Esto es debido a que, en <font color="#000080"><span lang="zxx"><u><a href="https://developer.mozilla.org/es/Firefox/Multiprocess_Firefox">Firefox multiproceso</a></u></span></font>, los scripts de contenido se ejecutan en un proceso distinto del de otras partes de la add-on.</p> + +<p>Para depurar scripts de contenido adjuntos a una página web, se deben usar las herramientas de desarrollo web normales para esa página:</p> + +<ul> + <li> + <p style="margin-bottom: 0cm;">selecciona “Alternar herramientas” del submenú Desarrollador Web en el menú Firefox (o el menú de herramientas si se muestra la barra de menú o se está utilizando Mac OS X)</p> + </li> + <li> + <p>o presiona el método abreviado del teclado <kbd>CtrlShiftI</kbd> (<kbd>CommandOptionI</kbd> en OS X).</p> + </li> +</ul> + +<p>{{EmbedYouTube("f46hMLELyaI")}}</p> + +<p>Por defecto, las herramientas se muestran al pie de la pestaña de desarrollo, para reflejar que están relacionadas con esa pestaña. Cualquier salida de las instrucciones <code class="western"><a>console.log()</a></code> de los scripts de contenido será mostrada allí. También se verán los scripts de contenido listados en el Depurador, donde se podrán colocar breakpoints, avanzar en el código, etc.</p> + +<p>{{EmbedYouTube("Hx3GU_fEPeo")}}</p> + +<div class="note"> +<p>Este video usa el ejemplo <font color="#000080"><span lang="zxx"><u><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a></u></span></font> de WebExtension.</p> +</div> + +<div class="note"> +<p style="line-height: 120%;">Si la pestaña de Herramientas de Desarrollo no estaba abierta cuando el scripts de contenido se introdujo, puede ocurrir que el scripts de contenido no aparezca en el panel de depuración. Si esto ocurre, recargar la página que contiene la pestaña de Herramientas de Desarrollo debería solucionar el problema.</p> +</div> diff --git a/files/es/mozilla/add-ons/webextensions/examples/index.html b/files/es/mozilla/add-ons/webextensions/examples/index.html new file mode 100644 index 0000000000..40900fa368 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/examples/index.html @@ -0,0 +1,24 @@ +--- +title: Ejemplos de extensiones +slug: Mozilla/Add-ons/WebExtensions/Examples +tags: + - WebExgtensions +translation_of: Mozilla/Add-ons/WebExtensions/Examples +--- +<div>{{AddonSidebar}}</div> + +<p>Para ayudar en la ilustración de cómo desarrollar las extension, se mantiene un repositorio de ejemplos simples de extensions en <a href="https://github.com/mdn/webextensions-examples">https://github.com/mdn/webextensions-examples</a>. Este artículo describe las extensiones en ese repositorio.</p> + +<p>Estos ejemplo funcionan en Firefox Nightly: la mayoría funcionan en versiones más recientes de Firefox, pero revise la clave <a href="/en-US/Add-ons/WebExtensions/manifest.json/applications">strict_min_version</a> en el manifest.json del complemento para estar seguro.</p> + +<p>Si quiere probar estos ejemplo, tiene tres opciones principales:</p> + +<ol> + <li>Clone el repositorio, entonces, carge el complemento directo desde su directorio, utilizando la función <a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">"Cargar complemento temporalmente"</a>. El complemento estará cargado hasta que se reinicie Firefox.</li> + <li>Clone el repositorio, luego utilice la herrmienta <a href="/es/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a> en la línea de comando para ejecutar Firefox con el complemento instalado.</li> + <li>Clone el repositorio, luego diríjase al directorio <a href="https://github.com/mdn/webextensions-examples/tree/master/build">build</a>. Este contiene todos los ejemplos firmados y compilados, así que usted puede abrilos en Firefox (utilizando Archivo/Abrir archivo) e instalarlos permanentemente, justamente como cuando se instala un complemento desde <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a>.</li> +</ol> + +<p>Si quiere contribuir al repositorio, <a href="https://github.com/mdn/webextensions-examples/blob/master/CONTRIBUTING.md">¡envíe una petición de pull!</a></p> + +<p>{{WebExtAllExamples}}</p> diff --git a/files/es/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html b/files/es/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html new file mode 100644 index 0000000000..426aeae50f --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/extending_the_developer_tools/index.html @@ -0,0 +1,159 @@ +--- +title: Extending the developer tools +slug: Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools +translation_of: Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>This page describes devtools APIs as they exist in Firefox 55. Although the APIs are based on the <a href="https://developer.chrome.com/extensions/devtools">Chrome devtools APIs</a>, there are still many features that are not yet implemented in Firefox, and therefore are not documented here. To see which features are currently missing please see <a href="/en-US/Add-ons/WebExtensions/Using_the_devtools_APIs#Limitations_of_the_devtools_APIs">Limitations of the devtools APIs</a>.</p> +</div> + +<p><span class="seoSummary">You can use WebExtensions APIs to extend the browser's built-in developer tools.</span> To create a devtools extension, include the "<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page">devtools_page</a>" key in <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a>:</p> + +<pre class="brush: json notranslate">"devtools_page": "devtools/devtools-page.html"</pre> + +<p>The value of this key is a URL pointing to an HTML file that's been bundled with your extension. The URL should be relative to the manifest.json file itself.</p> + +<p>The HTML file defines a special page in the extension, called the devtools page.</p> + +<h2 id="The_devtools_page">The devtools page</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. Here's an example:</p> + +<pre class="brush: html notranslate"><!DOCTYPE html> +<html> + <head> + <meta charset="utf-8"> + </head> + <body> + <script src="devtools.js"></script> + </body> +</html></pre> + +<p>The devtools.js file will hold the actual code creating your dev tools extensions.</p> + +<h2 id="Creating_panels">Creating panels</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 notranslate">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="Interacting_with_the_target_window">Interacting with the target window</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="Running_code_in_the_target_window">Running code in the target window</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="Working_with_content_scripts">Working with content scripts</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 notranslate">// 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 notranslate">// 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="Limitations_of_the_devtools_APIs">Limitations of the devtools APIs</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 all the Console's command-line helper functions, but <code>$0</code> and <code>inspect(...)</code> are both supported (starting from Firefox 55).</p> + +<h3 id="devtools.panels">devtools.panels</h3> + +<p>The following are not supported:</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="Examples">Examples</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> use devtools panels:</p> + </li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/implement_a_settings_page/index.html b/files/es/mozilla/add-ons/webextensions/implement_a_settings_page/index.html new file mode 100644 index 0000000000..1d48eec011 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/implement_a_settings_page/index.html @@ -0,0 +1,199 @@ +--- +title: Implementar una página de configuración +slug: Mozilla/Add-ons/WebExtensions/Implement_a_settings_page +tags: + - JavaScript +translation_of: Mozilla/Add-ons/WebExtensions/Implement_a_settings_page +--- +<div>{{AddonSidebar}}</div> + +<p>Una página de configuración ofrece a los usuarios una manera de ver y cambiar los ajustes (algunas veces también llamados "preferencias" u "opciones") para el complemento.</p> + +<p>Con WebExtensions, los ajustes generalmente se almacenan utilizando la API <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code> . La implementación de una página de configuración se realiza en un proceso de tres pasos:</p> + +<ul> + <li>Escribir un archivo HTML que muestre los ajustes y permita al usuario cambiarlos.</li> + <li>Escribir un script, incluido desde el archivo HTML , que establece la página de configuración desde su almacenamiento y actualiza los ajustes seleccionados cuando el usuario los modifica.</li> + <li>Establecer la ruta al archivo HTML como la clave <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui </a></code> en manifest.json. Haciendo esto, el documento HTML se mostrará en el administrador de complementos del navegador, junto al nombre del complemento y su descripción.</li> +</ul> + +<div class="note"> +<p>También puedes abrir esta página mediante programación utilizando la función <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/openOptionsPage">runtime.openOptionsPage()</a></code> .</p> +</div> + +<h2 id="Una_sencilla_ExtensionWeb">Una sencilla ExtensionWeb</h2> + +<p>En primer lugar, vamos a escribir una extensión que añada un borde azul a todas las páginas que el usuario visita.</p> + +<p>Crea un nuevo directorio llamado "configuración", a continuación crea un archivo llamado"manifest.json" en su interior ,con el siguiente contenido:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Settings example", + "version": "1.0", + + "content_scripts": [ + { + "matches": ["<all_urls>"], + "js": ["borderify.js"] + } + ], + + "applications": { + "gecko": { + "id": "settings-example@mozilla.org" + } + } + +}</pre> + +<p>Este complemento da instrucciones al navegador para cargar un script de contenido llamado "borderify.js" en todas las páginas web que el usuario visita.</p> + +<p>Ten en cuenta que también hemos incluido la clave <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> . Necesitaremos esto (solamente en Firefox ) porque si hay un error, debemos establecer explícitamente (la identidad del complemento) <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">add-on ID</a> , y también incluimos la clave de manifiesto <code>options_ui</code>. Aunque no utilicemos la clave <code>options_ui</code> en ese momento, lo haremos en la siguiente sección. Ver el <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1269454">bug 1269545</a>.</p> + +<p>A continuación, crea un archivo llamado "borderify.js" en el directorio "configuración" , y añade el siguiente contenido :</p> + +<pre class="brush: js">document.body.style.border = "10px solid blue";</pre> + +<p>Esto solo añade un borde azul a la página.</p> + +<p>Ahora <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">instala WebExtension</a> y comprueba — abre cualquier página web que te guste:</p> + +<p>{{EmbedYouTube("E-WUhihF8fw")}}</p> + +<h2 id="Añadir_ajustes">Añadir ajustes</h2> + +<p>Ahora vamos a crear una página de configuración que permita al usuario establecer el color del borde.</p> + +<p>En primer lugar, actualiza "manifest.json" para que tenga este contenido:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Settings example", + "version": "1.0", + + "content_scripts": [ + { + "matches": ["<all_urls>"], + "js": ["borderify.js"] + } + ], + + "applications": { + "gecko": { + "id": "settings-example@mozilla.org" + } + }, + + "options_ui": { + "page": "options.html" + }, + + "permissions": ["storage"] + +} +</pre> + +<p>Hemos añadido dos nuevas claves de manifiesto:</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code>: Esta establece un documento HTML que es la página de configuración (tambien llamada página de opciones) para este complemento.</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code>: utilizaremos la API <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage</a></code> para almacenar los ajustes, y necesitaremos pedir permiso para utilizar esta API.</li> +</ul> + +<p>A continuacion, como hemos prometido crear "options.html", vamos a realizarlo. Crea un archivo con ese nombre en el directorio "configuración" , y añade el siguiente contenido:</p> + +<pre class="brush: html"><!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8"> + </head> + + <body> + + <form> + <label>Border color<input type="text" id="color" ></label> + <button type="submit">Save</button> + </form> + + <script src="options.js"></script> + + </body> + +</html> +</pre> + +<p>Esto define un elemento HTML {{htmlelement("form")}} con un texto etiquetado {{htmlelement("input")}} y un botón de envio {{htmlelement("button")}}. también incluye un script llamado "options.js".</p> + +<p>Crea "options.js", de nuevo en el directorio "configuración" , y añade el siguiente contenido:</p> + +<pre class="brush: js">function saveOptions(e) { + chrome.storage.local.set({ + color: document.querySelector("#color").value + }); +} + +function restoreOptions() { + chrome.storage.local.get("color", (res) => { + document.querySelector("#color").value = res.color || "blue"; + }); +} + +document.addEventListener("DOMContentLoaded", restoreOptions); +document.querySelector("form").addEventListener("submit", saveOptions);</pre> + +<p>Esto hace dos cosas:</p> + +<ul> + <li>Cuando el documento ha sido cargado, se obtiene el valor "color" desde el almacenamiento utilizando <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get">storage.local.get()</a></code>. Si el valor no se ha establecido, utiliza por defecto "azul".</li> + <li>Cuando el usuario envía el formulario haciendo click en "guardar", se almacena el valor del cuadro de texto utilizando <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/set">storage.local.set()</a></code>.</li> +</ul> + +<p>Finalmente, actualiza "borderify.js" para leer el color del borde del almacenamiento:</p> + +<pre class="brush: js">chrome.storage.local.get(null, (res) => { + var color = "blue"; + if (res.color) { + color = res.color; + } + document.body.style.border = "10px solid " + color; +});</pre> + +<p>En este punto, el complemento completo debe tener este aspecto:</p> + +<pre>settings/ + borderify.js + manifest.json + options.html + options.js</pre> + +<p>Ahora:</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox#Reloading_a_temporary_add-on">recarga WebExtension.</a></li> + <li>carga una página web.</li> + <li>abre la página de configuración y cambia el color del borde.</li> + <li>recarga la página web para ver la diferencia.</li> +</ul> + +<p>En Firefox se puede accededer a la página de configuración visitando : complementos y haciendo click en el botón "Preferencias" junto a la entrada del complemento.</p> + +<p>{{EmbedYouTube("ECt9cbWh1qs")}}</p> + +<h2 id="Aprende_más">Aprende más</h2> + +<ul> + <li>Documentación de referencia de la clave de manifiesto.<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui.</a></li> + <li>Documentación de referencia de la API <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage">storage.</a></li> + <li>Abrir la página de configuración directamente desde el complemento utilizando la API <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/openOptionsPage">runtime.openOptionsPage().</a></code></li> + <li>Página de ejemplo de configuraciones: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">color-favorito.</a></li> + </ul> + </li> +</ul> + +<p> </p> diff --git a/files/es/mozilla/add-ons/webextensions/index.html b/files/es/mozilla/add-ons/webextensions/index.html new file mode 100644 index 0000000000..ec02f9c6df --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/index.html @@ -0,0 +1,155 @@ +--- +title: Extensiones del navegador +slug: Mozilla/Add-ons/WebExtensions +tags: + - Complementos + - Dónde empezar + - Manifiesto + - WebExtensions + - extensiones +translation_of: Mozilla/Add-ons/WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<p>Las extensiones pueden extender y modificar la capacidad de un navegador. Las extensiones para Firefox son construidas utilizando las APIs de WebExtension, un sistema para el desarrollo de extensiones multi-navegador. En gran medida, el sistema es compatible con la <a class="external-icon external" href="https://developer.chrome.com/extensions">API de extensión</a> soportada por Google Chrome, Opera y el <a href="https://browserext.github.io/browserext/">borrador del grupo de la comunidad del W3C</a>.</p> + +<p>Las extensiones escritas para estos navegadores se ejecutarán en la mayoría de los casos en Firefox o <a href="https://developer.microsoft.com/en-us/microsoft-edge/platform/documentation/extensions/">Microsoft Edge</a> con sólo <a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Porting_from_Google_Chrome">unos pocos cambios</a>. La API también es totalmente compatible con <a href="https://developer.mozilla.org/es/Firefox/Multiprocess_Firefox">multiprocesos de Firefox</a>.</p> + +<p>Si tiene alguna idea, pregunta, o necesita ayuda en el proceso de migración de un complemento heredado al uso de las APIs de WebExtension, puede ponerse en contacto con nosotros a través de la <a href="https://mail.mozilla.org/listinfo/dev-addons">lista de correo dev-addons</a> o en el canal <a href="irc://irc.mozilla.org/webextensions">#webextensions</a> de <a href="https://wiki.mozilla.org/IRC">IRC</a>.</p> + +<div class="row topicpage-table"> +<div class="section"> +<h2 id="Primeros_pasos">Primeros pasos</h2> + +<ul> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Que_son_las_WebExtensions">¿Qué son las extensiones?</a></li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Tu_primera_WebExtension">Tu primera extensión</a></li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Tutorial">Tu segunda extensión</a></li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Anatomia_de_una_WebExtension">Anatomía de una extensión</a></li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Examples">Ejemplos de extensiones</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/What_next_">¿Qué sigue?</a></li> +</ul> + +<p> </p> + +<h2 id="Conceptos">Conceptos</h2> + +<ul> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/API">Descripción general de la API JavaScript</a></li> + <li><a href="/es/Add-ons/WebExtensions/Content_scripts">Scripts de contenido</a></li> + <li><a href="/es/Add-ons/WebExtensions/Match_patterns">Patrones de coincidencia</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_files">Trabajando con archivos</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Internationalization">Internacionalización</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Security_best_practices">Las mejores prácticas de seguridad</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Política de seguridad de contenido</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Native_messaging">Mensajería nativa</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Extending_the_developer_tools">Utilización de las APIs de devtools</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/User_experience_best_practices">Buenas prácticas para la experiencia de usuario</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_manifests">Manifestaciones nativas</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions">Acciones de los usuarios</a></li> +</ul> + +<p> </p> + +<h2 id="Interfaz_de_usuario">Interfaz de usuario</h2> + +<ul> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/user_interface">Introducción</a></li> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/user_interface/Accion_navegador">Botón en la barra de herramientas del navegador</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Popups">Botón en barra de herramientas del navegador con una ventana emergente</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Page_actions">Botón en la barra de direcciones</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Popups">Botón en barra de direcciones con una ventana emergente</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Context_menu_items">Elementos en el menú contextual</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Sidebars">Barras laterales</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Options_pages">Página de opciones</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Extension_pages">Páginas de extensiones</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Notifications">Notificaciones</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Omnibox">Sugerencias en la barra de direcciones</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/devtools_panels">Paneles de herramientas para desarrolladores</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles">Estilos del navegador</a></li> +</ul> + +<h2 id="Cómo">Cómo</h2> + +<ul> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests">Interceptar solicitudes HTTP</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Modify_a_web_page">Modificar una página web</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">Agregar un botón a la barra de herramientas</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page">Implementar una página de configuración</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard">Interactuar con el portapapapeles</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Working_with_the_Tabs_API">Trabajar con el API de las pestañas</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Work_with_the_Bookmarks_API">Trabajar con el API de los marcadores</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Work_with_the_Cookies_API">Trabajar con el API de las cookies</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Work_with_contextual_identities">Trabjar con identidades contextuales</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Safely_inserting_external_content_into_a_page">Insertar contenido externo</a></li> +</ul> + +<h2 id="Portado">Portado</h2> + +<ul> + <li><a href="/es/Add-ons/WebExtensions/Porting_from_Google_Chrome">Portar una extensión de Google Chrome</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Porting_a_legacy_Firefox_add-on">Portar un complemento heredado de Firefox</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Developing_WebExtensions_for_Firefox_for_Android">Desarrollo para Firefox para Android</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Embedded_WebExtensions">WebExtensions integradas</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK">Comparación con el complemento SDK</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Comparison_with_XUL_XPCOM_extensions">Comparación con las extensiones XUL/XPCOM</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities">Incompatibilidades con Chrome</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Differences_between_desktop_and_Android">Diferencias entre el escritorio y Android</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Differences_between_API_implementations">Diferencias entre implementaciones de API</a></li> +</ul> + +<h2 id="Flujo_de_trabajo_de_Firefox">Flujo de trabajo de Firefox</h2> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/User_experience_best_practices">Experiencia de usuario</a></li> + <li><a href="/es/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">Instalación</a></li> + <li><a href="/es/Add-ons/WebExtensions/Debugging">Depuración</a></li> + <li> + <div id="gt-res-content"> + <div class="trans-verified-button-large" dir="ltr" id="gt-res-dir-ctr"> + <div id="tts_button"><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Testing_persistent_and_restart_features">Prueba de funciones persistentes y de reinicio</a></div> + </div> + </div> + </li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">Primeros pasos con web-ext</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/web-ext_command_reference">Referencia del comando web-ext</a></li> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID">Extensiones y el ID del complemento</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Alternative_distribution_options">Opciones alternativas de distribución</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Sharing_objects_with_page_scripts">Solicite los permisos correctos</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Sharing_objects_with_page_scripts">Compartir objetos con guiones de página</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/Distribution/Retiring_your_extension">Retirando su extensión</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Tips">Consejos y trucos</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Development_Tools">Herramientas de desarrollo para las extensiones del navegador</a></li> +</ul> +</div> + +<div class="section"> +<h2 id="Reference">Reference</h2> + +<h3 id="JavaScript_APIs">JavaScript APIs</h3> + +<ul> + <li><a href="/es/docs/Mozilla/Add-ons/WebExtensions/API">Descripción general de la API JavaScript</a></li> + <li><a href="/es/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">Tablas de compatibilidad del navegador para las API de JavaScript</a></li> +</ul> + +<h4 id="APIs_de_JavaScript">APIs de JavaScript</h4> + +<div class="twocolumns">{{ListSubpages("/en-US/Add-ons/WebExtensions/API")}}</div> + +<h3 id="Manifest_keys">Manifest keys</h3> + +<ul> + <li><a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/manifest.json">Resumen del manifest.json</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json">Compatibilidad del navegador para el manifest.json</a></li> +</ul> + +<div class="twocolumns">{{ListSubpages("/en-US/Add-ons/WebExtensions/manifest.json")}}</div> +</div> +</div> + +<div class="SnapLinksContainer" style="margin-left: 0px; margin-top: 0px; display: none;"> +<div class="SL_SelectionRect"> +<div class="SL_SelectionLabel"> </div> +</div> +</div> diff --git a/files/es/mozilla/add-ons/webextensions/intercept_http_requests/index.html b/files/es/mozilla/add-ons/webextensions/intercept_http_requests/index.html new file mode 100644 index 0000000000..a87d079ecd --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/intercept_http_requests/index.html @@ -0,0 +1,156 @@ +--- +title: Interceptar peticiones HTTP +slug: Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests +tags: + - Complementos + - Cómos + - WebExtensions + - extensiones +translation_of: Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests +--- +<div>{{AddonSidebar}}</div> + +<p>Para interceptar peticiones HTTP, utilice la API {{WebExtAPIRef("webRequest")}}. Esta API le permite agregar escuchadores de evento para varias etapas en la realización de las solicitudes HTTP. En los escuchadores, tu puedes:</p> + +<ul> + <li>Obtener acceso a la solicitud y respuesta de las cabeceras y cuerpos</li> + <li>Cancelar y redireccionar las solicitudes</li> + <li>Modificar las solicitudes y respuestas de las cabeceras</li> +</ul> + +<p>En este artículo se verán los tres diferentes usos del módulo <code>webRequest</code>:</p> + +<ul> + <li>Registro de solicitudes de URLs a medida que se realizan.</li> + <li>Redireccionar las solicitudes.</li> + <li>Modificar las cabeceras de las solicitud.</li> +</ul> + +<h2 id="Registrar_solicitudes_de_URLs">Registrar solicitudes de URLs</h2> + +<p>Crea un nuevo directorio llamado "requests". En ese directorio, crea un archivo llamado "manifest.json" el cual debe poseer el siguiente contenido:</p> + +<pre class="brush: json">{ + "description": "Demostrar webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest" + ], + + "background": { + "scripts": ["background.js"] + } +}</pre> + +<p>Luego, crea un archivo llamado "background.js" con el siguiente contenido:</p> + +<pre class="brush: js">function logURL(requestDetails) { + console.log("Cargando: " + requestDetails.url); +} + +browser.webRequest.onBeforeRequest.addListener( + logURL, + {urls: ["<all_urls>"]} +); + +</pre> + +<p>En este punto se utiliza {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} para llamar la función <code>logURL()</code> junstamente después de realizar la solicitud. La función <code>logURL()</code> se apropia de la solicitud URL del objeto de eventos y lo registra en la consola del navegador. <code>El </code><a href="/es/Add-ons/WebExtensions/Match_patterns">patrón</a><code> {urls: ["<all_urls>"]}</code> signinifica que se pueden interceptar todas las solicitudes HTTP de todas las URLs.</p> + +<p>Para probarlo, <a href="/esAdd-ons/WebExtensions/Temporary_Installation_in_Firefox">instala la WebExtension</a>, <a href="/es/docs/Tools/Browser_Console">abre la consola del navegador</a>, y abre algunas páginas Web. En la consola del navegador, deberías ver las URLs de cualquier recurso que el navegador solicita:</p> + +<p>{{EmbedYouTube("X3rMgkRkB1Q")}}</p> + +<h2 id="Redireccionar_solicitudes">Redireccionar solicitudes</h2> + +<p>Ahora utilice <code>webRequest</code> para redireccionar todas las solicitudes HTTP. Primero, reemplace manifest.json con lo siguiente:</p> + +<pre class="brush: json">{ + + "description": "Demostrar webRequests", + "manifest_version": 2, + "name": "webRequest-demo", + "version": "1.0", + + "permissions": [ + "webRequest", "webRequestBlocking" + ], + + "background": { + "scripts": ["background.js"] + } + +}</pre> + +<p>El único cambio fue la adición de los <code><a href="/es/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permisos</a></code> <code>"webRequestBlocking"</code>. Se necesita preguntar por este extra-permiso todas las veces que se está activamente modificando una solicitud.</p> + +<p>Luego, reemplace "background.js" con esto:</p> + +<pre class="brush: js">var pattern = "https://mdn.mozillademos.org/*"; + +function redirect(requestDetails) { + console.log("Redireccionando: " + 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>De nuevo, se utiliza el escuchador de evento {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} para ejecutar una función justamente antes de que cada solicitud sea realizada. Esta función reemplazará el objetivo URL con <code>redirectUrl</code> que está definido en la función.</p> + +<p>Esta vez no se está interceptando cada solicitud: la opción <code>{urls:[pattern], types:["image"]}</code> especifica que solo se debería interceptar solicitudes (1) de URLs que residen bajo "https://mdn.mozillademos.org/" (2) para recursos de imágenes. Vea {{WebExtAPIRef("webRequest.RequestFilter")}} para más información sobre esto.</p> + +<p>Dése cuenta también, que se esta pasando la opción llamada <code>"blocking"</code>: se necesita pasar cada vez que se requiera modificar la solicitud. Esto hace que la función del escuchador bloquee la solicitud de la red, así que el navegador espera que el escuchador retorne antes de continuar. Vea la documentación {{WebExtAPIRef("webRequest.onBeforeRequest")}} para conocer más sobre <code>"blocking"</code>.</p> + +<p>Para probarlo, abra una página de MDN que contenga bastantes imágenes (por ejemplo <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">recargue la WebExtension</a>, y luego recargue la página de MDN:</p> + +<p>{{EmbedYouTube("ix5RrXGr0wA")}}</p> + +<h2 id="Modificar_las_cabeceras_de_la_solicitud">Modificar las cabeceras de la solicitud</h2> + +<p>Finalmente se utilizará <code>webRequest</code> para modificar las cabeceras de las solicitudes. En este ejempo se modificará la cabecera "User-Agent" así que el navegador se identificará por sí mismo como Opera 12.16, pero solamente cuando se visitan páginas de "http://useragentstring.com/".</p> + +<p>El "manifest.json" puede permanecer igual que el ejemplo anterior.</p> + +<p>Reemplace "background.js" con el siguiente código:</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 == "User-Agent") { + header.value = ua; + } + } + return {requestHeaders: e.requestHeaders}; +} + +browser.webRequest.onBeforeSendHeaders.addListener( + rewriteUserAgentHeader, + {urls: [targetPage]}, + ["blocking", "requestHeaders"] +);</pre> + +<p>Aquí se utiliza el escuchador de eventos {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}} para ejecutar una función juntamente antes de que la solicitud de las cabeceras sean enviadas.</p> + +<p>La función escuchadora será llamada solamente por solicitudes de URLs que coincidan con el <a href="/es/Add-ons/WebExtensions/Match_patterns">patrón </a><code>targetPage</code>. Dése cuenta de nuevo que <code>"blocking"</code> se ha pasado como una opción. También se pasó <code>"requestHeaders"</code>, lo cual significa que al escuchador pasará un array conteniendo las cabeceras de la solicitud que se espera enviar. Vea {{WebExtAPIRef("webRequest.onBeforeSendHeaders")}} para más información en estas opciones.</p> + +<p>La función escuchadora busca la cabecera "User-Agent" en el array de la solicitud de cabeceras, reemplaza el valor con el valor de la variable <code>ua</code>, y regresa el array modificado. Este array modificado será el enviado al servidor.</p> + +<p>Para comprobarlo, abra <a href="http://useragentstring.com/">useragentstring.com</a> y verifique que identifica al navegador como Firefox. Luego recargue el complemento, recargue <a href="http://useragentstring.com/">useragentstring.com</a>, y compruebe que Firefox es identificado ahora como Opera:</p> + +<p>{{EmbedYouTube("SrSNS1-FIx0")}}</p> + +<h2 id="Aprenda_más">Aprenda más</h2> + +<p>Para aprender más sobre todas las cosas que puede hacer con la API <code>webRequest</code>, vea su propia <a href="/en-US/Add-ons/WebExtensions/API/WebRequest">documentación de referencia</a>.</p> diff --git a/files/es/mozilla/add-ons/webextensions/internationalization/index.html b/files/es/mozilla/add-ons/webextensions/internationalization/index.html new file mode 100644 index 0000000000..89c542a2e7 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/internationalization/index.html @@ -0,0 +1,405 @@ +--- +title: Internationalization +slug: Mozilla/Add-ons/WebExtensions/Internationalization +translation_of: Mozilla/Add-ons/WebExtensions/Internationalization +--- +<pre class="brush: html notranslate"><span class="seoSummary"><kbd>H</kbd></span></pre> + +<p>The <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions">WebExtensions</a> API has a rather handy module available for internationalizing extensions — <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n">i18n</a>. In this article we'll explore its features and provide a practical example of how it works. The i18n system for extensions built using WebExtension APIs is similar to common JavaScript libraries for i18n such as <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="Anatomy_of_an_internationalized_extension">Anatomy of an internationalized extension</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="Providing_localized_strings_in__locales">Providing localized strings in _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 notranslate">{ + "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="Internationalizing_manifest.json">Internationalizing manifest.json</h2> + +<p>There are a couple of different tasks to carry out to internationalize your manifest.json.</p> + +<h3 id="Retrieving_localized_strings_in_manifests">Retrieving localized strings in manifests</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 notranslate">"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 class="notranslate"><strong>__MSG_</strong> + <em>messageName</em> + <strong>__</strong></pre> + +<h3 id="Specifying_a_default_locale">Specifying a default locale</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 notranslate">"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 notranslate">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="Retrieving_message_strings_from_JavaScript">Retrieving message strings from 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 notranslate">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 notranslate">"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 class="notranslate">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 class="notranslate">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 notranslate">"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 notranslate">"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="Localized_string_selection">Localized string selection</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="Predefined_messages">Predefined messages</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 class="notranslate">__MSG_extensionName__</pre> + +<p>Predefined messages use exactly the same syntax, except with <code>@@</code> before the message name, for example</p> + +<pre class="notranslate">__MSG_@@ui_locale__</pre> + +<p>The following table shows the different available predefined messages:</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Message name</th> + <th scope="col">Description</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 notranslate">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 notranslate">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 notranslate">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 notranslate">direction: rtl; +padding-right: 0; +padding-left: 1.5em;</pre> + +<h2 id="Testing_out_your_extension">Testing out your extension</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>Note</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>Note:</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/es/mozilla/add-ons/webextensions/manifest.json/icons/index.html b/files/es/mozilla/add-ons/webextensions/manifest.json/icons/index.html new file mode 100644 index 0000000000..0f8550f027 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/manifest.json/icons/index.html @@ -0,0 +1,74 @@ +--- +title: icons +slug: Mozilla/Add-ons/WebExtensions/manifest.json/icons +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>Object</code></td> + </tr> + <tr> + <th scope="row">Obligatorio</th> + <td>No</td> + </tr> + <tr> + <th scope="row">Ejemplo</th> + <td> + <pre class="brush: json no-line-numbers"> +"icons": { + "48": "icon.png", + "96": "icon@2x.png" +}</pre> + </td> + </tr> + </tbody> +</table> + +<p>La propiedad <code>icons</code> especifica los iconos de tu extensión. Esos iconos se usarán para representar la extensión en componentes como el Administrador de complementos.</p> + +<p>Consiste en pares clave-valor del tamaño de la imagen en px y la ruta de la imagen relativa al directorio raíz de la extensión.</p> + +<p>Si <code>icons</code> no esta definido, se utilizará un icono de extensión estándar por defecto.</p> + +<p>Debería suministrar al menos un icono de extensión principal, idealmente de 48x48 px de tamaño. Este es el icono por defecto que se utilizará en el Administrador de complementos. Sin embargo, puedes suministrar iconos de cualquier tamaño y Firefox intentará encontrar el mejor icono para mostrar en los diferentes componentes.</p> + +<p>Firefox tendrá en cuenta la resolución de la pantalla al elegir un icono. Para ofrecer la mejor experiencia visual a los usuarios con pantallas de alta resolución, como las pantallas Retina, proporciona versiones de doble tamaño de todos sus iconos.</p> + +<h2 id="Ejemplo">Ejemplo</h2> + +<p>Las propiedades del objeto <code>icons</code> especifican el tamaño del icono en px, los valores especifican la ruta relativa del icono. Este ejemplo contiene un icono de extensión de 48px y una versión más grande para pantallas de alta resolución.</p> + +<pre class="brush: json no-line-numbers">"icons": { + "48": "icon.png", + "96": "icon@2x.png" +}</pre> + +<h2 id="SVG">SVG</h2> + +<p>Puede usar SVG y el navegador escalará su icono adecuadamente. Sin embargo, hay dos advertencias:</p> + +<ol> + <li>Necesitas especificar un viewBox en la imagen. E.g.: + <pre class="brush: html"><svg viewBox="0 0 48 48" width="48" height="48" ...</pre> + </li> + <li>Aunque puedes usar un archivo, todavía necesitas especificar varios tamaños del icono en tu manifiesto. E.g.: + <pre class="brush: json">"icons": { + "48": "icon.svg", + "96": "icon.svg" +}</pre> + </li> +</ol> + +<div class="note"> +<p>Si está usando un programa como Inkscape para crear SVG, puede que quiera guardarlo como un "SVG simple". Firefox podría confundirse con varios espacios de nombres especiales y no mostrar su icono.</p> +</div> + +<h2 id="Compatibilidad">Compatibilidad</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/es/mozilla/add-ons/webextensions/manifest.json/index.html b/files/es/mozilla/add-ons/webextensions/manifest.json/index.html new file mode 100644 index 0000000000..f85e30b4cf --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/manifest.json/index.html @@ -0,0 +1,51 @@ +--- +title: manifest.json +slug: Mozilla/Add-ons/WebExtensions/manifest.json +translation_of: Mozilla/Add-ons/WebExtensions/manifest.json +--- +<p>{{AddonSidebar}}</p> + +<div class="blockIndicator note"> +<p>Este artículo describe manifest.json para extensiones web. Si estás buscando información acerca de manifest.json en PWAs, revisa el artículo sobre <a href="/en-US/docs/Web/Manifest">Web App Manifest</a>.</p> +</div> + +<p>El archivo <code>manifest.json</code> es el único archivo que toda extensión usando la API WebExtension debe contener necesariamente.</p> + +<p>Usando <code>manifest.json</code>, puedes especificar los metadatos básicos de tu extensión como nombre y versión, así como aspectos funcionales de tu extensión (tales como scripts en segundo plano, scripts de contenido y acciones del navegador).</p> + +<p>Es un archivo con formato <a href="/en-US/docs/Glossary/JSON">JSON</a>, con una excepción: permite comentarios con "<code>//</code>".</p> + + +<h2 id="Lista_de_claves_de_manifest.json">Lista de claves de <code>manifest.json</code></h2> + +<p>Las claves de manifest.json son:</p> + +<div class="index">{{ListSubpages("/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json")}}</div> + + +<h3 class="index" id="Notas_acerca_de_las_claves_de_manifest.json">Notas acerca de las claves de manifest.json</h3> + +<ul> + <li><code>"manifest_version"</code>, <code>"version"</code>, and <code>"name"</code> son las únicas llaves obligatorias.</li> + <li><code>"default_locale"</code> Debe estar presente <strong>solo</strong> si la carpeta "<code>_locales</code>" existe.</li> + <li><code>"browser_specific_settings"</code> no tiene soporte en Google Chrome.</li> +</ul> + +<h3 id="Acceder_a_las_claves_de_manifest.json_en_tiempo_de_ejecución">Acceder a las claves de manifest.json en tiempo de ejecución</h3> + +<p>Puedes acceder a el manifest desde el código JavaScript de tu extensión utilizando la función {{WebExtAPIRef("runtime.getManifest()")}}:</p> + +<pre class="brush: js; no-line-numbers notranslate">browser.runtime.getManifest().version;</pre> + + +<h2 id="Compatibilidad_de_Navegadores">Compatibilidad de Navegadores</h2> + +<p>Para un resumen extendido de las llaves y sub-llaves ver la <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_compatibility_for_manifest.json"> tabla completa de compatibilidad de <code>manifest.json</code> en navegadores</a>.</p> + +<div class="hidden">La tabla de compatibilidad está generada desde datos estructurados. Si quieres colaborar visita <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> y solicita un <em>pull request</em>.</div> + +<p>{{Compat("webextensions.manifest")}}</p> + +<h2 id="Ver_También">Ver También</h2> + +<p>API JavaScript de {{WebExtAPIRef("permissions")}}</p> diff --git a/files/es/mozilla/add-ons/webextensions/modify_a_web_page/index.html b/files/es/mozilla/add-ons/webextensions/modify_a_web_page/index.html new file mode 100644 index 0000000000..eb7493b62b --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/modify_a_web_page/index.html @@ -0,0 +1,253 @@ +--- +title: Modify a web page +slug: Mozilla/Add-ons/WebExtensions/Modify_a_web_page +translation_of: Mozilla/Add-ons/WebExtensions/Modify_a_web_page +--- +<div>{{AddonSidebar}}</div> + +<div>Uno de los usos más comunes para las extensiones es modificar páginas web. Por ejemplo, una extension puede querer cambiar el estilo de la página, esconder determinados nodos DOM o incluir otros nuevos.</div> + +<div> </div> + +<div>Existen dos maneras de hacer esto con extensiones Web y APIs:</div> + +<div> </div> + +<ul> + <li><strong>Declarativamente</strong>: Define un patrón que encaja con un conjunto de URLs y carga un conjunto de scripts a las páginas cuyos URL encajen con ese patrón.</li> + <li><strong>Programaticamente</strong>: Usando una Javascript API, carga una script en la página alojada en una lengüeta específica.</li> +</ul> + +<p>De ambas formas, estos scripts se llaman scripts de contenido y son distintos del resto de scripts que constituyen una extensión. </p> + +<ul> + <li>Solamente tienen acceso a un grupo pequeño de extensiones web y APIs.</li> + <li>Obtienen acceso directo a la página web en la que han sido cargadas.</li> + <li>Se comunican con el resto de la extensión usando una API de mensajería.</li> +</ul> + +<p>En este artículo hablaremos de los dos métodos para cargar una script..</p> + +<h2 id="Modificando_páginas_que_encajen_con_un_patrón_URL">Modificando páginas que encajen con un patrón URL</h2> + +<p>Para empezar, crea un nuevo directorio llamado "modify-page". En este directorio, crea un archivo llamado "manifest.json", con el siguiente contenido:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "modify-page", + "version": "1.0", + + "content_scripts": [ + { + "matches": ["https://developer.mozilla.org/*"], + "js": ["page-eater.js"] + } + ] + +}</pre> + +<p>La llave <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> es el método de carga de scripts a páginas cuya URL encaje con los patrones. En este caso, <code>content_scripts</code> le dice al navegador que cargue una script llamada "page-eater.js" en todas las páginas con <a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a>.</p> + +<div class="note"> +<p>Debido a que el atributo <code>"js"</code> de <code>content_scripts</code> es una array, puedes usarla para inyectar más de una script a las páginas que encajen con el patrón. Si haces esto las páginas compartiran el mismo campo de aplicación, igual que múltiples scripts cargadas por una página, y son cargadas en el mismo orden en las que están dispuestas en la array.</p> +</div> + +<div class="note"> +<p>La llave <code>content_scripts</code> tambien tiene un atributo de <code>"css"</code> que puedes usar para inyectar código CSS. </p> +</div> + +<p>Después, crea un archivo llamado "page-eater.js" dentro del directorio "modify-page" e introduce el contenido de a continuación:</p> + +<pre class="brush: js">document.body.textContent = ""; + +var header = document.createElement('h1'); +header.textContent = "This page has been eaten"; +document.body.appendChild(header);</pre> + +<p> Ahora, <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">instala la extensión</a> y visita <a href="https://developer.mozilla.org/">https://developer.mozilla.org/</a>:</p> + +<p>{{EmbedYouTube("lxf2Tkg6U1M")}}</p> + +<div class="note"> +<p>Ten en cuenta que aunque este video muestra el contenido de la script operando en <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a>, las scripts de contenido están bloqueadas en esta página por el momento.</p> +</div> + +<h2 id="Modificando_las_páginas_programaticamente">Modificando las páginas programaticamente</h2> + +<p>Y si quieres comer páginas, pero solo cuando el usuario te lo pida? Actualicemos este ejemplo para que podamos enyectar el contenido de la script cuando el usuario haga click en un item del menu de contexto.</p> + +<p>Primero actualiza "manifest.json" para que incluya el contenido a continuación:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "modify-page", + "version": "1.0", + + "permissions": [ + "activeTab", + "contextMenus" + ], + + "background": { + "scripts": ["background.js"] + } + +}</pre> + +<p>Aquí, hemos eliminado la llave <code>content_scripts</code> y hemos añadido dos nuevas llaves:</p> + +<ul> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code>: Para inyectar scripts a las páginas necesitamos los permisos para la página que estamos modificando. El permiso <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission"><code>activeTab</code> </a>es una manera de obtener el permiso temporalmente para la lengüeta que esté actualmente abierta. También necesitamos el permiso <code>contextMenus</code> para poder añadir items al menu de contexto.</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/background">background</a></code>: Usamos esto para cargar un <a href="/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">"background script"</a> persistente llamado "background.js", en el cual montamos el menu de contexto e inyectamos el script de contenido.</li> +</ul> + +<p>Ahora generaremos este archivo. Crea un archivo llamado "background.js" en el directorio "modify-page" e introduce el siguiente contenido: </p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "eat-page", + title: "Eat this page" +}); + +browser.contextMenus.onClicked.addListener(function(info, tab) { + if (info.menuItemId == "eat-page") { + browser.tabs.executeScript({ + file: "page-eater.js" + }); + } +}); +</pre> + +<p>En esta script estamos creando un <a href="/en-US/Add-ons/WebExtensions/API/ContextMenus/create">item del menu de contexto</a> y dándole una ID y un título específico (el texto que se estará expuesto en el menu de contexto). Después configuramos un evento de escucha para que cuando el usuario haga click en uno de los items del menu podamos comprobar si se trata de nuestro item <code>eat-page</code> . En caso afirmativo, inyectaremos "page-eater.js" a la lengüeta actual usando la API <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript()</a></code>. Alternativamente, esta API puede tomar como argumento una ID. En este caso la hemos omitido lo cual quiere decir que la script es inyectada en la lengüeta que está actualmente abierta.</p> + +<p>Ahora mismo la extensión debería ser algo como esto:</p> + +<pre class="line-numbers language-html"><code class="language-html">modify-page/ + background.js + manifest.json + page-eater.js</code></pre> + +<p>Ahora <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox#Reloading_a_temporary_add-on">recarga la extensión</a>, abre la página (cualquier página en esta ocasión), activa el menu de contexto y selecciona "Eat this page" (Comer esta página):</p> + +<p>{{EmbedYouTube("zX4Bcv8VctA")}}</p> + +<div class="note"> +<p>Ten en cuenta que aunque este video muestra el contenido de la script operando en <a href="https://addons.mozilla.org/en-US/firefox/">addons.mozilla.org</a>, las scripts de contenido están bloqueadas en esta página por el momento.</p> +</div> + +<h2 id="Mensajería">Mensajería</h2> + +<p>Scripts de contenido y scripts de fondo no pueden acceder directamente al estado del otro. Sin embargo, pueden comunicarse mediante el uso de mensajes. Una terminal configura un escuchador de mensajes y la otra terminal puede mandarle un mensaje. La siguente tabla resume las APIs involucradas en cada parte:</p> + +<table class=" fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row"> </th> + <th scope="col">En el script de contenido</th> + <th scope="col">En el script de fondo</th> + </tr> + <tr> + <th scope="row">Mandar un mensaje</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">Recibir un mensaje</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> + </thead> +</table> + +<p>Actualicemos nuestro ejemplo para ilustrar como mandar un mensaje desde una script de fondo.</p> + +<p>Primero, hemos de editar "background.js" para que tenga el siguiente contenido:</p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "eat-page", + title: "Eat this page" +}); + +function messageTab(tabs) { + browser.tabs.sendMessage(tabs[0].id, { + replacement: "Message from the extension!" + }); +} + +function onExecuted(result) { + var querying = browser.tabs.query({ + active: true, + currentWindow: true + }); + querying.then(messageTab); +} + +browser.contextMenus.onClicked.addListener(function(info, tab) { + if (info.menuItemId == "eat-page") { + let executing = browser.tabs.executeScript({ + file: "page-eater.js" + }); + executing.then(onExecuted); + } +}); +</pre> + +<p>Ahora, después de inyectar "page-eater.js", hemos de usar <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/query">tabs.query()</a></code> para obtener la lengüeta actualmente activa y entonces usar <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">tabs.sendMessage()</a></code> para mandar un mensaje a las scripts de contenido cargadas en la lengüeta. El mensaje tiene el contenido <code>{replacement: "Message from the extension!"}</code>.</p> + +<p>Después, actualiza "page-eater.js" de esta forma:</p> + +<pre class="brush: js">function eatPageReceiver(request, sender, sendResponse) { + document.body.textContent = ""; + var header = document.createElement('h1'); + header.textContent = request.replacement; + document.body.appendChild(header); +} +browser.runtime.onMessage.addListener(eatPageReceiver); +</pre> + +<p>Ahora, en vez de simplemente comer la página, el contenido espera a un mensaje usando <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">runtime.onMessage</a></code>. Cuando el mensaje llega, el script de contenido ejecuta el mismo código de antes, exceptuando que el texto de reemplazo se obtenido de <code>request.replacement</code>.</p> + +<p>Debido a que <code><a href="/en-US/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript()</a></code> es una función asincrónica y para asegurarnos de que mandamos el mensaje solo cuando el escuchador ha sido añadido en "page-eater.js", usamos <code>onExecuted</code> que sera llamado después de que "page-eater.js" se ejecute.</p> + +<div class="note"> +<p>Pulsa Ctrl+Shift+J (o Cmd+Shift+J en el Mac) o <code>web-ext run --bc</code> para abrir la consola de navegación para ver <code>console.log</code> en la script de fondo. Alternativamente puedes usar el <a href="/en-US/Add-ons/Add-on_Debugger">Add-on Debugger</a>, el cual te permite poner un breakpoint. De momento no hay forma de iniciar un <a href="https://github.com/mozilla/web-ext/issues/759">Add-on Debugger directamente de una extensión web</a>.</p> +</div> + +<p>Si queremos enviar mensajes directamente desde el contenido script de vuelta a la página de fondo, podríamos usar<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage">runtime.sendMessage()</a></code> en vez de <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">tabs.sendMessage()</a></code>. Por ejemplo:</p> + +<pre class="brush: js">browser.runtime.sendMessage({ + title: "from page-eater.js" +});</pre> + +<div class="note"> +<p>Todos estos ejemplos inyectan Javascript; también puedes inyectar CSS programaticamente usando la función<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS">tabs.insertCSS()</a></code>.</p> +</div> + +<h2 id="Aprende_más">Aprende más</h2> + +<ul> + <li>La guía de <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">scripts de contenido</a></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> llave de manifiesto</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> llave de manifiesto</li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">tabs.executeScript()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS">tabs.insertCSS()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">tabs.sendMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendMessage">runtime.sendMessage()</a></code></li> + <li><code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessage">runtime.onMessage</a></code></li> + <li>Ejemplos con<code>content_scripts</code>: + <ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">borderify</a></li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a></li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/page-to-extension-messaging">page-to-extension-messaging</a></li> + </ul> + </li> + <li>Ejemplos con<code>tabs.executeScript()</code>: + <ul> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a></li> + <li><a class="external external-icon" href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-demo">context-menu-demo</a></li> + </ul> + </li> +</ul> + +<p> </p> diff --git a/files/es/mozilla/add-ons/webextensions/packaging_and_installation/index.html b/files/es/mozilla/add-ons/webextensions/packaging_and_installation/index.html new file mode 100644 index 0000000000..e032fc354b --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/packaging_and_installation/index.html @@ -0,0 +1,90 @@ +--- +title: Empaquetado e Instalación +slug: Mozilla/Add-ons/WebExtensions/Packaging_and_installation +translation_of: Mozilla/Add-ons/WebExtensions/Temporary_Installation_in_Firefox +--- +<h2 id="Empaquetando_tu_extensión">Empaquetando tu extensión</h2> + +<div class="note"> +<p>Mozilla actualmente esta considerando implementar una aplicación con interfaz visual para empaquetar y cargar extensiones. Mira el <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1185460">Bug 1185460</a> para más información. Hasta entonces, sigue los pasos que aparecen a continuación.</p> +</div> + +<p>Las extensiones para Firefox son empaquetadas como archivos XPI, los cuales son solamente archivos ZIP, con extensión "xpi".</p> + +<p>Un truco es que el archivo ZIP debe ser un archivo que contenga los archivos de la extensión y no la carpeta que los contiene.</p> + +<h3 id="Windows">Windows</h3> + +<ol> + <li>Abre la carpeta que contiene los archivos de tu extensión.</li> + <li>Selecciona todos los archivos.</li> + <li>Con clic derecho elige Enviar a → Carpeta comprimida (zip).</li> + <li>Cambia el nombre del archivo resultante de <code>something.zip</code> a <code>something.xpi</code>.</li> +</ol> + +<p><img alt="Screenshot of the Windows Explorer context menu showing Send to compressed (zipped) folder" src="https://mdn.mozillademos.org/files/11717/pUF1vnr.png" style="height: 641px; width: 904px;"></p> + +<h3 id="Mac_OS_X">Mac OS X</h3> + +<ol> + <li>Abre la carpeta que contiene los archivos de tu extensión.</li> + <li>Selecciona todos los archivos.</li> + <li>Con clic derecho elige Comprimir <em>n</em> elementos.</li> + <li>Cambia el nombre del archivo resultante de <code>something.zip</code> a <code>something.xpi</code>.</li> +</ol> + +<p><img alt="Screenshot of the Finder context menu showing the Compress 15 Items option" src="https://mdn.mozillademos.org/files/11715/Screen%20Shot%202015-10-08%20at%2016.19.02.png" style="height: 460px; width: 850px;"></p> + +<h3 id="Linux_Mac_OS_X_Terminal">Linux / Mac OS X Terminal</h3> + +<ol> + <li><code>cd path/to/my-extension/</code></li> + <li><code>zip -r ../my-extension.xpi *</code></li> +</ol> + +<h2 id="Instalando_tu_extensión">Instalando tu extensión</h2> + +<ol> + <li>Navega a <code>about:addons</code></li> + <li>Arrastra y suelta el XPI dentro de la página, o abre el menú de opciones y escoge "Instalar complemento desde archivo..."</li> + <li>Da clic en "Instalar" en el diálogo que aparecerá</li> +</ol> + +<h2 id="Instalando_tu_extensión_en_Firefox_OS">Instalando tu extensión en Firefox OS</h2> + +<p>Tu puedes instalar tu extensión desde WebIDE en un escritorio conectado vía USB o Wifi. Abre <code>path/to/my-extension/ como una Aplicación empaquetada en WebIDE.</code></p> + +<p><code>Cuando la validación de manifest.json es correcta podrás instalar y ejecutar tu extensión en el dispositivo con Firefox OS conectado.</code></p> + +<p><code>Para instalar extensiones debe tener habilitada la opción en Configuración->Complementos del dispositivo con Firefox OS.</code></p> + +<h2 id="Resolución_de_problemas">Resolución de problemas</h2> + +<p>Aquí están algunos de los problemas más comunes que podrías encontrarte:</p> + +<h3 id="Este_complemento_no_puede_ser_instalado_porque_no_ha_sido_verificado.">"Este complemento no puede ser instalado porque no ha sido verificado."</h3> + +<ul> + <li>Asegúrate que estás usando <a href="https://nightly.mozilla.org/">Nightly</a> y la preferencia <code>xpinstall.signatures.required</code> está en <code>false</code> en <code>about:config</code>.</li> + <li>Aprende más acerca de <a href="/en-US/docs/Mozilla/Add-ons/Distribution">la firma de complementos y su distribución</a>.</li> +</ul> + +<h3 id="Este_complemento_no_puede_ser_instalado_porque_para_estar_corrupto.">"Este complemento no puede ser instalado porque para estar corrupto."</h3> + +<ul> + <li>Asegúrate que has comprimido los archivos directamente, <em>no la carpeta que contiene</em> los archivos de tu extensión. Tu archivo manifest.json debe estar en la carpeta raíz del archivo ZIP.</li> + <li>Asegúrate que estás usando la versión <a href="https://nightly.mozilla.org/">Nightly</a> de Firefox.</li> +</ul> + +<h3 id="No_pasa_nada">No pasa nada</h3> + +<ul> + <li>Asegúrate que tu archivo actualmente termina en <code>.xpi</code>, existen algunos <em>sistemas operativos que le gusta ocultar</em> las extensiones de los archivos. + + <ul> + <li>En Windows, comprueba con Vista → Mostrar / Ocultar: Extensiones de los archivos.</li> + <li>En Mac OS X, comprueba con Archivo → Obtener información → Nombre y Extensión.</li> + </ul> + </li> + <li>Es posible que te hayas perdido u ocultado el diálogo de instalación. Mira si un icono parecido a una pieza de rompecabezas está al lado del botón Atrás en Nightly. Has clic sobre él para trae nuevamente el diálogo de instalación.</li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/porting_from_google_chrome/index.html b/files/es/mozilla/add-ons/webextensions/porting_from_google_chrome/index.html new file mode 100644 index 0000000000..58959678f4 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/porting_from_google_chrome/index.html @@ -0,0 +1,22 @@ +--- +title: Conversión de extensiones de Google Chrome +slug: Mozilla/Add-ons/WebExtensions/Porting_from_Google_Chrome +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Porting_a_Google_Chrome_extension +--- +<div>{{AddonSidebar}}</div> + +<p>Las extensiones programadas con API de WebExtensions están diseñadas para ser compatibles entre navegadores diferentes: en buena medida, esta tecnología es compatible directamente con la <a class="external external-icon" href="https://developer.chrome.com/extensions">API de extensiones</a> admitida por Google Chrome y Opera. En la mayoría de los casos, las extensiones creadas para estos navegadores se ejecutarán en Firefox con solo unas pocas modificaciones. Casi todas las <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API">API de extensiones</a> se admiten a través de funciones de devolución de llamada bajo el espacio de nombres <code>chrome</code>, al igual que Chrome. Las únicas API que no se admiten bajo el espacio de nombres <code>chrome</code> son aquellas que son deliberadamente incompatibles con Chrome. En esos casos contados, la página de documentación de la API manifestará expresamente que se admite solo en el espacio de nombres <code>browser</code>. El proceso de conversión de extensiones de Chrome u Opera es el siguiente:</p> + +<ol> + <li>Revise su utilización de funciones de manifest.json y API de WebExtensions con respecto a la <a href="/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">referencia de incompatibilidades con Chrome</a>. Si está empleando funciones o API que aún no se admiten en Firefox, es posible que no pueda convertir su extensión por el momento. Mozilla ofrece un servicio que puede ayudar a automatizar este paso: <a href="https://www.extensiontest.com/">https://www.extensiontest.com/</a>.</li> + <li><a href="/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">Instale su extensión en Firefox</a> y póngala a prueba.</li> + <li>Si experimenta problemas, póngase en contacto con nosotros a través de la <a class="external external-icon" href="https://mail.mozilla.org/listinfo/dev-addons">lista de correo «dev-addons»</a> o el <a href="irc://irc.mozilla.org/webextensions">canal #webextensions</a> en <a class="external external-icon" href="https://wiki.mozilla.org/IRC">IRC</a>.</li> + <li><a href="/en-US/Add-ons/WebExtensions/Publishing_your_WebExtension">Envíe su complemento a AMO para su firma y distribución</a>.</li> +</ol> + +<p>Si dependía de la opción de consola de Chrome para cargar extensiones no empaquetadas, eche un vistazo a la herramienta <a href="/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a>, la cual automatiza la instalación temporal en Firefox para permitir el desarrollo.</p> + +<ul> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/prerequisitos/index.html b/files/es/mozilla/add-ons/webextensions/prerequisitos/index.html new file mode 100644 index 0000000000..d022940dab --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/prerequisitos/index.html @@ -0,0 +1,17 @@ +--- +title: Prerequisitos +slug: Mozilla/Add-ons/WebExtensions/Prerequisitos +translation_of: Mozilla/Add-ons/WebExtensions/Prerequisites +--- +<p>Para desarrollar usando las APIs de WebExtension, debes seguir algunos pasos antes de comenzar.</p> + +<ul> + <li>Descarga, instala, y ejecuta <a href="https://www.mozilla.org/es-ES/firefox/developer/">Firefox para Desarrolladores</a> o <a class="external text" href="https://nightly.mozilla.org/" rel="nofollow">Firefox Nightly</a>. Usa Nightly si quieres tener los últimos cambios.</li> + <li>Ve a la preferencia que controla la instalación de complementos no firmados. Nota que esta preferencia solo está disponible en Firefox para Desarrolladores y Firefox Nightly. + <ul> + <li>Escribe <code>about:config</code> dentro de la barra de direcciones de Firefox</li> + <li>En el campo de búsqueda escribe <code>xpinstall.signatures.required</code></li> + <li>Has doble clic sobre la preferencia, o clic derecho y escoge Modificar, para cambiarla a <code>false</code>.</li> + </ul> + </li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/publishing_your_webextension/index.html b/files/es/mozilla/add-ons/webextensions/publishing_your_webextension/index.html new file mode 100644 index 0000000000..ef81cd0468 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/publishing_your_webextension/index.html @@ -0,0 +1,105 @@ +--- +title: Publicando tu extensión +slug: Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension +tags: + - AMO + - Addons + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Package_your_extension_ +--- +<div>{{AddonSidebar}}</div> + +<p>Una vez que hayas acabado de modificar y testear tu extensión, es probable que quieras compartirla con el resto del mundo. Mozilla tiene una web: <a class="external external-icon" href="https://addons.mozilla.org">addons.mozilla.org</a> (comunmente abreviada como AMO), en la que los desarrolladores pueden publicar sus complementos y los usuarios pueden encontrarlos. Publicando tu extension en AMO, puedes participar en nuestra comunidad de usuarios y creadores, y encontrar una audiencia para tu extension.</p> + +<p>No tienes por que publicar tu extension en AMO. De todas maneras, aunque no quieras publicarla, tendrás que enviarla a AMO para que pueda ser revisada y firmada. Las versiones oficiales de Firefox no aceptan complementos que no estén firmados por AMO.</p> + +<p>En resumen, este es el proceso para publicar una extensión:</p> + +<ol> + <li><a href="#1._Zip_up_your_extension's_files">Comprime los archivos de tu extension en un zip</a></li> + <li><a href="#2._Create_an_account_on_addons.mozilla.org">Crea una cuenta en AMO</a></li> + <li><a href="#3._Upload_your_zip">Sube tu zip a AMO para firmarlo y revisarlo y selecciona una opción</a></li> + <li><a href="#4._Fix_review_problems">Soluciona los problemas encontrados en la revisión</a></li> + <li><a href="#5._Publish_your_extension">Si seleccionas no publicar la extension en AMO, puedes obtener la extension firmada y publicala por tu cuenta</a></li> +</ol> + +<p>Cuando estés listo para lanzar una nueva versión de tu extensión, puedes actualizarla visitando la página de la extensión en <a class="external external-icon" href="https://addons.mozilla.org">addons.mozilla.org</a>, y subiendo ahí la nueva versión. Ten en cuenta que tendrás que actualizar la página de la extensión para que AMO reconozca que es una actualización de la extensión, y no una extensión completamente nueva.</p> + +<p>Si seleccionas publicar tu extensión en AMO, Firefox buscará las actualizaciones automaticamente. Si seleccionas publicarla por tu cuenta, tendrás que incluir la clave <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> en tu manifest.json, con el atributo <code>update_url</code> apuntando a un <a href="/en-US/Add-ons/Updates">update manifest file</a>.</p> + +<div class="pull-aside"> +<div class="moreinfo"> +<p>Las extensiones empaquetadas de Firefox son "archivos XPI", que son simplemente un .ZIP con otra extensión</p> + +<p>No tienes que usar la extensión .XPI para subirla a AMO.</p> +</div> +</div> + +<h2 id="1._Comprime_los_archivos_en_un_zip">1. Comprime los archivos en un zip</h2> + +<p>En este punto tu extensión consistirá en una carpeta que contiene un manifest.json y otros archivos que necesite (scripts, iconos, documentos HTML, etc.). Necesitarás comprimir todos en un sólo .zip para poder subirlos a AMO.</p> + +<p>Es importante saber que el .zip deber crearse seleccionando<strong> todos los archivos de la extensión, no su carpeta contenedora</strong>.</p> + +<h3 id="Windows">Windows</h3> + +<ol> + <li>Abre la carpeta que contenga los archivos de tu extensión.</li> + <li>Selecciona todos los archivos (CTRL+E o CTRL+A, depende del idioma).</li> + <li>Click derecho en Enviar a → Carpeta comprimida (en zip).</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>Abre la carpeta que contenga los archivos de tu extensión.</li> + <li>Selecciona todos los archivos.</li> + <li>Click derecho y selecciona Comprimir <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">Ver <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><code>cd path/to/my-extension/</code></li> + <li><code>zip -r -FS ../my-extension.zip *</code></li> +</ol> + +<div style=""> </div> + +<h2 id="2._Crea_una_cuenta_en_addons.mozilla.org">2. Crea una cuenta en addons.mozilla.org</h2> + +<p>Visita <a href="https://addons.mozilla.org/">https://addons.mozilla.org/</a>. Si ya tienes una <a href="https://support.mozilla.org/en-US/kb/access-mozilla-services-firefox-accounts">Cuenta Firefox</a>, puedes utilizarla para iniciar sesión. Si no, haz click en "Registrar" y se te exigirá crear una cuenta.</p> + +<h2 id="3._Sube_tu_zip">3. Sube tu zip</h2> + +<p>A continuación, sube la extensión comprimida a AMO para poder revisarla y firmarla, y selecciona si quieres publicarla en AMO o no. Hay un <a href="https://developer.mozilla.org/en-US/Add-ons/Distribution/Submitting_an_add-on">tutorial</a> disponible para guiarte durante el proceso de envío. Sería conveniente que también veas <a href="https://developer.mozilla.org/es/Add-ons/Distribution#Enviando_a_AMO">Enviando a AMO</a> para más detalles sobre el proceso.</p> + +<div class="note"> +<p>Ten en cuenta que una vez que hayas subido la extensión a AMO no podrás actualizarla para usar el Add-on SDK o técnicas XUL/XPCOM. Si decides cambiar a una de estas plataformas, tendrás que enviar la extensión de nuevo como si de una nueva extensión se tratase.</p> + +<p>En otras palabras: portar a partir de sistemas de extensiones heredadas para usar APIs WebExtension es un camino de ida.</p> + +<p>Antes de subirla, asegurate de que el ZIP contiene sólo los archivos necesarios para la extensión.</p> +</div> + +<h2 id="4._Soluciona_los_problemas_detectados_en_la_revisión">4. Soluciona los problemas detectados en la revisión</h2> + +<p>En cuanto subas la aplicación, el servidor AMO realizará varios tests básicos y te notificará inmediatamente de cualquier problema. Los problemas se dividen en dos categorías: "errors" y "warnings". Si tienes errores, tienes que arreglarlos y reenviar la extensión. Si sólo tienes avisos, conviene solucionarlos, pero no es obligatorio. Puedes continuar.</p> + +<p>Si el comprobador automático no detecta ningún error, la extensión pasará por una revisión más exhaustiva. Serás contactado con los resultados de la revisión. En caso de tener errores tendrás que solucionarlos e intentarlo de nuevo.</p> + +<p>Si has selccionado que la extensión esté hosteada en AMO, este es el final del proceso de publicación. AMO firmará la extensión y la publicará, tras esto los usuarios ya podrán descargarla e instalarla.</p> + +<h2 id="5._Publica_tu_extensión">5. Publica tu extensión</h2> + +<p>Si seleccionas no publicarla en AMO, obten la extensión firmada y públicala por tu cuenta.</p> + +<p> </p> diff --git a/files/es/mozilla/add-ons/webextensions/que_son_las_webextensions/index.html b/files/es/mozilla/add-ons/webextensions/que_son_las_webextensions/index.html new file mode 100644 index 0000000000..eca9f0ff30 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/que_son_las_webextensions/index.html @@ -0,0 +1,59 @@ +--- +title: ¿Qué son las extensiones? +slug: Mozilla/Add-ons/WebExtensions/Que_son_las_WebExtensions +tags: + - WebExtensions + - extensiones +translation_of: Mozilla/Add-ons/WebExtensions/What_are_WebExtensions +--- +<div>{{AddonSidebar}}</div> + +<p>Una extensión agrega características y funciones a un explorador. Se ha creado utilizando tecnologías basadas en Web conocidas: HTML, CSS y JavaScript. Puede aprovechar las mismas API Web que JavaScript en una página web, pero una extensión también tiene acceso a su propio conjunto de APIs de JavaScript. Esto significa que puede hacer mucho más en una extensión de lo que puede con el código en una página web. Estos son sólo algunos ejemplos de las cosas que puedes hacer:</p> + +<p><strong>Mejore o complemente un sitio</strong>: Use un Add-on para ofrecer funciones adicionales en el navegador o información de su sitio Web. Permita a los usuarios recopilar detalles de las páginas que visitan para mejorar el servicio que ofrecen.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15808/Amazon_add_on.png"></p> + +<p><strong>Ejemplos:</strong> <a href="https://addons.mozilla.org/en-US/firefox/addon/amazon-browser-bar/">El asistente de Amazon para Firefox</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/onenote-clipper/">OneNote Web Clipper</a> y <a href="https://addons.mozilla.org/en-US/firefox/addon/grammarly-1/">Grammarly para Firefox</a></p> + +<p><strong>Permita que los usuarios demuestren su personalidad</strong>: Las extensiones del navegador pueden manipular el contenido de las páginas; por ejemplo, permite a los usuarios agregar su logo favorito o imágen como un fondo de pantalla acada página que visitan. Las extensiones permiten también al usuario actualizar el aspecto de la IU de Firefox, de la misma manera que lo hacen los <a href="https://developer.mozilla.org/es/docs/Temas/Theme_concepts">complementos de temas</a>.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15809/MyWeb_New_Tab_add_on.png" style="height: 398px; width: 540px;"></p> + +<p><strong>Ejemplos:</strong> <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> y <a href="https://addons.mozilla.org/en-US/firefox/addon/vivaldifox/">VivaldiFox</a></p> + +<p><strong>Agregar o quitar contenido de las páginas web</strong>: es posible que desee ayudar a los usuarios a bloquear los anuncios intrusivos de las páginas web, proporcionar acceso a una guía de viajes siempre que un país o ciudad se menciona en una página web, o reformatear el contenido de la página para ofrecer una experiencia de lectura consistente. Con la capacidad de acceder y actualizar tanto HTML como CSS de una página, las extensiones pueden ayudar a los usuarios a ver la Web de la manera que quieren.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15807/ublock_origin_add_on.png" style="height: 480px; width: 640px;"></p> + +<p><strong>Ejemplos:</strong> <a href="https://addons.mozilla.org/en-US/firefox/addon/ublock-origin/">Origen uBlock</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/reader/">Lector</a> y <a href="https://addons.mozilla.org/en-US/firefox/addon/toolbox-google-play-store/">Caja de Herramientas para Google Play Store™</a></p> + +<p><strong>Agregar herramientas y nuevas funciones de navegación</strong>: añada nuevas funciones a un taskboard o genere imágenes de código QR a partir de URLs, hipervínculos o texto de página. Con opciones de interfaz de usuario flexibles y la potencia de las <a href="https://developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions">APIs de WebExtensions</a>, puede añadir fácilmente nuevas funcionalidades a un navegador. Usted puede realzar casi cualquier característica o funcionalidad de sitios web, no tiene que ser su web.</p> + +<p><strong><img alt="" src="https://mdn.mozillademos.org/files/15806/QR_Code_Image_Generator_add_on.png"></strong></p> + +<p><strong>Ejemplos: <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>, y <a href="https://addons.mozilla.org/en-US/firefox/addon/tomato-clock/">Tomato Clock</a></strong></p> + +<p><strong>Juegos</strong>: ofrecer juegos de ordenador tradicionales, con características de juego fuera de línea, pero también explorar nuevas posibilidades de juego, por ejemplo, mediante la incorporación de gameplay en la navegación cotidiana.</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>Ejemplos: <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>Agregar herramientas de desarrollo</strong>: puede proporcionar herramientas de desarrollo web como su negocio o ha desarrollado una técnica útil o un enfoque para el desarrollo web que desea compartir. De cualquier manera, puede mejorar las herramientas de desarrollo de Firefox incorporadas añadiendo una nueva ficha a la barra de herramientas del desarrollador.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15804/aXe_Developer_Tools_add_on.png" style="height: 261px; width: 700px;"></p> + +<p><strong>Ejemplos:</strong> <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>Las extensiones para Firefox se construyen utilizando las <a href="https://developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions">APIs de WebExtensions</a>, un sistema multi-navegador para desarrollar extensiones. En gran medida, la API es compatible con la <a class="external external-icon" href="https://developer.chrome.com/extensions">extension API</a> soportada por Google Chrome y Opera. Extensiones escritas para estos navegadores en la mayoría de los casos se ejecutan en Firefox o Microsoft Edge con sólo unos pocos <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Porting_a_Google_Chrome_extension">cambios</a>. La API es también totalmente compatible con los <a href="https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox">multiprocesos de Firefox</a>.</p> + +<p>Si tiene ideas o preguntas, o necesita ayuda para migrar un Add-on heredado a las APIs de WebExtensions, puede comunicarse con nosotros en el<a class="external external-icon" href="https://mail.mozilla.org/listinfo/dev-addons">dev-addons mailing list</a> o en <a href="irc://irc.mozilla.org/extdev">#extdev</a> en <a class="external external-icon" href="https://wiki.mozilla.org/IRC">IRC</a>.</p> + +<h2 id="¿Qué_sigue">¿Qué sigue?</h2> + +<ul> + <li>Para recorrer el desarrollo de una simple extensión, vea <a href="https://developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions/Tu_primera_WebExtension">Tu primera extensión</a>.</li> + <li>Aprende sobre la estructura de una extensión en <a href="https://developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions/Anatomia_de_una_WebExtension">anatomía de una extensión</a>.</li> + <li>Pruebe algunos ejemplos de extensiones en <a href="https://developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions/Examples">Extensiones de ejemplo</a>.</li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/tu_primera_webextension/index.html b/files/es/mozilla/add-ons/webextensions/tu_primera_webextension/index.html new file mode 100644 index 0000000000..d444b69f88 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/tu_primera_webextension/index.html @@ -0,0 +1,160 @@ +--- +title: Tu primera extensión +slug: Mozilla/Add-ons/WebExtensions/Tu_primera_WebExtension +tags: + - Guía + - WebExtension +translation_of: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<div class="blockIndicator note"> +<p>Si estás familiarizado/a con los conceptos básicos de las extensiones de navegador, omite esta sección y ve a <a href="https://wiki.developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">cómo se ponen juntos los archivos</a>. Entonces, usa la <a href="https://wiki.developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions#Reference">documentación de referencia</a> para empezar a construir tu extensión. Visita el <a href="https://extensionworkshop.com/?utm_source=developer.mozilla.org&utm_medium=documentation&utm_campaign=your-first-extension">Firefox Extension Workshop</a> para aprender más sobre el flujo de trabajo para probar y publicar extensiones para Firefox.</p> +</div> + +<p>En este artículo abordaremos la creación de una extensión para Firefox, desde el comienzo hasta el final. La extensión solo agrega un borde rojo a cualquiera de las páginas cargadas desde "mozilla.org" o cualquiera de sus subdominios.</p> + +<p>El código fuente de este ejemplo se encuentra en GitHub: <a href="https://github.com/mdn/webextensions-examples/tree/master/borderify">https://github.com/mdn/webextensions-examples/tree/master/borderify</a>.</p> + +<p>Primero, necesitas tener instalado Firefox versión 45 o superior.</p> + +<h2 id="Escribiendo_la_extensión">Escribiendo la extensión</h2> + +<p>Crea una nuevo directorio y navega a él. Por ejemplo, en tu línea de comandos/terminal se hace de esta manera:</p> + +<pre class="brush: bash notranslate">mkdir borderify +cd borderify</pre> + +<h3 id="manifest.json">manifest.json</h3> + +<p>Ahora crearemos un archivo nuevo llamado "manifest.json" directamente en la carpeta "borderify". Añádale el siguiente contenido:</p> + +<pre class="brush: json notranslate">{ + + "manifest_version": 2, + "name": "Borderify", + "version": "1.0", + + "description": "Agrega un borde rojo a todas las páginas web de mozilla.org.", + + "icons": { + "48": "icons/border-48.png" + }, + + "content_scripts": [ + { + "matches": ["*://*.mozilla.org/*"], + "js": ["borderify.js"] + } + ] + +}</pre> + +<ul> + <li>Los primeros 3 parámetros:<code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code>, <code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/name">name</a></code>, y <code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/version">version</a></code>, son obligatorios, y contienen metadatos básicos para la extensión.</li> + <li><code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/description">description</a></code> es opcional, pero se recomienda: Se muestra en el Administrador de Add-ons.</li> + <li><code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> es opcional, pero recomendado: permite especificar un ícono para la extensión, se mostrará en el Administrador de Add-ons.</li> +</ul> + +<p>El parámetro más interesante aquí es <code><a href="/es/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code>, el cual le dice a Firefox que cargue el script en las páginas Web, cuyas URL coincidan con un patrón especifico. En este caso, le estamos pidiendo a Firefox que cargue el script llamado "borderify.js" en todas las paginas HTTP o HTTPS cargadas desde "mozilla.org" o cualquiera de sus subdominios.</p> + +<ul> + <li><a href="/es/Add-ons/WebExtensions/Content_scripts">Aprenda más acerca de los scripts contenidos.</a></li> + <li><a href="/es/Add-ons/WebExtensions/Match_patterns">Aprenda más acerca de los patrones coincidentes</a>.</li> +</ul> + +<div class="warning"> +<p><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/WebExtensions_and_the_Add-on_ID#When_do_you_need_an_Add-on_ID">En algunas situaciones usted necesita especificar un ID para su extensión</a>. Si necesita especificar un ID para el complemento, incluya el parámetro <code><a href="/es/Add-ons/WebExtensions/manifest.json/applications">applications</a></code> en el <code>manifest.json</code> y configure la propiedad <code>gecko.id</code>:</p> + +<pre class="brush: json notranslate">"applications": { + "gecko": { + "id": "borderify@example.com" + } +}</pre> +</div> + +<h3 id="iconsborder-48.png">icons/border-48.png</h3> + +<p>La extensión debería tener un ícono. Este se mostrará junto al listado de extensiones en el Administrador de Add-ons. Nuestro manifest.json promete que tendremos un ícono en el directorio "icons/border-48.png".</p> + +<p>Crea el directorio "icons" dentro de la carpeta "borderify". Almacena ahí el icono y nómbralo "border-48.png". Puedes utilizar <a href="https://github.com/mdn/webextensions-examples/blob/master/borderify/icons/border-48.png">el de nuestro ejemplo</a>, el cual se obtuvo a partir del Google Material Design iconset, y es utilizado bajo los términos de la licencia <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike</a>.</p> + +<p>Si eliges emplear tu propio icono, este debe ser de 48x48 pixeles. También puedes aplicar un icono de 96x96 pixeles, para resoluciones mayores, y si haces esto, se especifica como la propiedad <code>96</code> en el objeto icons del manifest.json:</p> + +<pre class="brush: json notranslate">"icons": { + "48": "icons/border-48.png", + "96": "icons/border-96.png" +}</pre> + +<p>Alternativamente, puedes aplicar un archivo SVG ahí, y este se escalará apropiadamente. (Aunque: si usas SVG y tu icono incluye texto, puedes usar la herramienta "convert to path" del editor SVG para aplanar el texto, de modo que se escalone con un tamaño/posición coherente).</p> + +<ul> + <li><a href="/es/Add-ons/WebExtensions/manifest.json/icons">Aprender mas acerca de la especificación de iconos.</a></li> +</ul> + +<h3 id="borderify.js">borderify.js</h3> + +<p>Finalmente, crea un archivo de nombre "borderify.js" directamente en el directorio "borderify". Y déjale el siguiente contenido:</p> + +<pre class="brush: js notranslate">document.body.style.border = "5px solid red";</pre> + +<p>Este script se cargara en las páginas que coincidan con el patrón dado en el parámetro <code>content_scripts</code> del archivo manifest.json. El script tiene acceso directo al documento, de la misma manera que los scripts cargados por la propia página.</p> + +<ul> + <li><a href="/es/Add-ons/WebExtensions/Content_scripts">Aprender más acerca de los scripts de contenido.</a></li> +</ul> + +<h2 id="Probándolo">Probándolo</h2> + +<p>Primero, verifica que tienes todos los archivos en su lugar:</p> + +<pre class="notranslate">borderify/ + icons/ + border-48.png + borderify.js + manifest.json</pre> + +<h3 id="Instalación">Instalación</h3> + +<p>Abre "about:debugging" en Firefox, da click en "Cargar complemento temporal" y selecciona cualquier archivo en el directorio de la extensión:</p> + +<p>{{EmbedYouTube("cer9EUKegG4")}}</p> + +<p>La extensión se encontrará instalada, y lo estará hasta que reinicies Firefox.</p> + +<p>Alternativamente, puede ejecuturar la extensión desde la línea de comandos utilizando la herramienta <a href="/es/docs/Mozilla/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a>.</p> + +<h3 id="Probando">Probando</h3> + +<p>Ahora pruebe visitando una página bajo "mozilla.org", y usted verá el borde rojo alrededor de la página:</p> + +<p>{{EmbedYouTube("rxBQl2Z9IBQ")}}</p> + +<div class="note"> +<p>No lo intentes en addons.mozilla.org! Los scripts de contenido están actualmente bloqueados en ese dominio.</p> +</div> + +<p>Experimenta un poco. Edita el contenido del script para cambiar el color del borde, o haz algo más en el contenido de la página. Si actualizas el script de contenido, recarga los archivos de la extensión haciendo clic en el botón "Recargar" en about:debugging. Podrás ver los cambios en el momento:</p> + +<p>{{EmbedYouTube("NuajE60jfGY")}}</p> + +<ul> + <li><a href="/es/Add-ons/WebExtensions/Temporary_Installation_in_Firefox">Aprende más sobre cómo recargar las extensiones</a></li> +</ul> + +<h2 id="Empaquetar_y_publicar">Empaquetar y publicar</h2> + +<p>Para que otras personas puedan utilizar tu extensión, necesitas empaquetarlo y enviarlo a Mozilla para que lo firmen. Para que aprendas más sobre eso, mira <a href="/es/docs/Mozilla/Add-ons/WebExtensions/Publishing_your_WebExtension">"Publicando tu extension"</a>.</p> + +<h2 id="¿Qué_sigue">¿Qué sigue?</h2> + +<p>Ahora que tienes una idea acerca del proceso de desarrollo de una WebExtension para Firefox, continúa con:</p> + +<ul> + <li><a href="/es/Add-ons/WebExtensions/Your_second_WebExtension">escribe una extensión más compleja</a></li> + <li><a href="/es/Add-ons/WebExtensions/Anatomy_of_a_WebExtension">leer más acerca de la anatomía de una extensión</a></li> + <li><a href="https://wiki.developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions/Examples">explora los ejemplos de extensiones</a></li> + <li><a href="https://wiki.developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions/What_next_">encuentra lo que necesitas para desarrollar, probar y publicar tu extensión</a></li> + <li><a href="/es/Add-ons/WebExtensions/API">leer acerca de las APIs de JavaScript disponibles para las extensiones.</a></li> + <li><a href="https://wiki.developer.mozilla.org/es/docs/Mozilla/Add-ons/WebExtensions/What_next_#Continue_your_learning_experience">lleva tu aprendizaje más lejos</a></li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/tutorial/index.html b/files/es/mozilla/add-ons/webextensions/tutorial/index.html new file mode 100644 index 0000000000..559320eca0 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/tutorial/index.html @@ -0,0 +1,459 @@ +--- +title: Tu segunda extensión +slug: Mozilla/Add-ons/WebExtensions/Tutorial +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>Si ya ha visto el artículo <a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Tu_primera_WebExtension">tu primer extensión</a>, ya posee una idea de como escribir una extensión. En este artículo se escribirá una extensión ligeramente más compleja para demostrar un par de cosas más de las APIs.</p> + +<p>La extensión añade un nuevo botón a la barra de herramientas de Firefox. Cuando el usuario da clic sobre el botón, mostraremos una ventana emergente que permite escoger un animal. Una vez que un animal sea escogido, reemplazaremos todas las imágenes en la página actual con la imagen del animal seleccionado.</p> + +<p>Para implementar esto, haremos lo siguiente:</p> + +<ul> + <li><strong>Definir una <a href="/es/Add-ons/WebExtensions/user_interface/Browser_action">acción del navegador</a>, que será el botón añadido a la barra de herramientas de Firefox</strong>.<br> + Para el botón vamos a proporcionar: + <ul> + <li>un icono, llamado "beasts-32.png"</li> + <li>una ventana emergente para abrir cuando el botón sea presionado. La ventana emergente incluye HTML, CSS y JavaScript.</li> + </ul> + </li> + <li><strong>Define un ícono para la extensión,</strong> llamado "beasts-48.png". Este será mostrado en el Administrador de Complementos.</li> + <li><strong>Escribe un script de contenido, "beastify.js" que será inyectado dentro de las páginas web.</strong><br> + Este es el código que modificará las páginas web.</li> + <li><strong>Empaqueta algunas imágenes de animales, para reemplazar las imágnes de la página web</strong>.<br> + Nosotros haremos las imágenes "recursos web accesibles" para que la página web pueda referenciarlos.</li> +</ul> + +<p>Tu puedes notar que la estructura general de la extensión luce como esto:</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>Esta es una extensión simple, pero muestra muchos de los principales conceptos de la API WebExtensions:</p> + +<ul> + <li>Adicionando un botón a la barra de herramientas</li> + <li>Definiendo un panel emergente usando HTML, CSS y JavaScript</li> + <li>Inyectando scripts de contenido dentro de las páginas web</li> + <li>Comunicándonos entre los scripts de contenido y el resto de la extensión</li> + <li>Empaquetando recursos con tu extensión que pueden ser usados por las páginas web</li> +</ul> + +<p>Tu puedes encontrar el <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">código fuente completo de la extensión en GitHub</a>.</p> + +<p>Para escribir una extensión, necesitará de Firefox 45 o más reciente.</p> + +<h2 id="Escribiendo_la_extensión">Escribiendo la extensión</h2> + +<p>Crea una carpeta nueva y navega hacia ella:</p> + +<pre class="brush: bash">mkdir beastify +cd beastify</pre> + +<h3 id="manifest.json">manifest.json</h3> + +<p>Ahora crea un archivo llamado "manifest.json", y agrega el siguiente contenido:</p> + +<pre class="brush: json">{ + + "manifest_version": 2, + "name": "Beastify", + "version": "1.0", + + "description": "Agrega un icono de acción navegación a la barra de herramientas. Haga clic en el botón para elegir una bestia. El contenido del cuerpo de la pestaña activa se sustituye por una imagen de la bestia elegida. Consulte https://developer.mozilla.org/es/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": "Bestificar", + "default_popup": "popup/choose_beast.html" + }, + + "web_accessible_resources": [ + "beasts/frog.jpg", + "beasts/turtle.jpg", + "beasts/snake.jpg" + ] + +} +</pre> + +<ul> + <li>Las tres primeras llaves: <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/manifest_version">manifest_version</a></code> , <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/name">name</a></code> , y <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/version">version</a></code> , son obligatorias y contienen los metadatos básicos para la extensión.</li> + <li><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/description">description</a></code> y <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/homepage_url">homepage_url</a></code> son opcionales, pero recomendadas: proporcionan información útil acerca de la extensión.</li> + <li><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/icons">icons</a></code> es opcional, pero recomedada: permite la especificación de un ícono para la extensión, que será mostrada en el Administrador de Complementos.</li> + <li><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a></code> lista los permisos que la extensión necesita. Aquí solo se pide el permiso de <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission"><code>activeTab</code> permission</a>.</li> + <li><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> especifica el botón de la barra de herramientas. Nosotros proveemos tres piezas de información aquí: + <ul> + <li><code>default_icon</code> es obligatorio y enlaza al icono para el botón</li> + <li><code>default_title</code> es opcional y será mostrado como descripción</li> + <li><code>default_popup</code> es usado su tu quieres una ventana emergente que será mostrada cuando el usuario de clic en el botón. Lo hacemos y hemos incluido esta llave que apunta a un archivo HTML de la extensión.</li> + </ul> + </li> + <li><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code> lista los archivos que queremos hacer accesibles a las páginas web. Como la extensión reemplaza imágenes en una página con imágenes que hemos empaquetado, necesitamos hacer estas imágenes accesibles a la página.</li> +</ul> + +<p>Nota que todas las rutas dadas son relativas a manifest.json.</p> + +<h3 id="El_ícono">El ícono</h3> + +<p>La extensión debería tener un íncono. Éste, será mostrado junto a la lista de complementos en el Administrador de Complementos (Pude abrirlo introduciendo en la URL "about:addons"). El manifest.json promete que se posee un ícono para la barra de herramientas en "icons/beasts-48.png".</p> + +<p>Cree el directorio "icons" y guarde un ícono ahí y nómbrelo como "beasts-48.png". Puede utilizar <a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-48.png">uno de nuestro ejemplo</a>, el cual ha sido tomado del <a href="https://www.iconfinder.com/iconsets/free-retina-icon-set">conjuto de íconos Aha-Soft’s Free Retina</a>, que es utilizado bajo el término de su propia <a href="http://www.aha-soft.com/free-icons/free-retina-icon-set/">licencia</a>.</p> + +<p>Si elige proporcionar su propio ícono, debería ser de 48x48 pixeles. También puede proporcionar un ícono de 96x96 pixeles, para pantallas de altas resoluciones y, si usted hace esto, deberá especificarlo como la propiedad <code>96</code> del objeto <code>icons</code> en el 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="El_botón_de_la_barra_de_herramientas">El botón de la barra de herramientas</h3> + +<p>El botón de la barra de herramientas necesita un ícono, y nuestro manifest.json promete eso y nos gustaría tener un ícono para la barra de herramientas en "icons/beasts-32.png".</p> + +<p>Guarde un ícono llamado "beasts-32.png" en el directorio "icons". Tu podrías usar <a href="https://github.com/mdn/webextensions-examples/blob/master/beastify/icons/beasts-32.png">uno de nuestros ejemplos</a>, los cuales son tomados desde el sitio <a href="http://www.iconbeast.com/free">IconBeast Lite icon set</a> y empleados bajo sus términos de <a href="http://www.iconbeast.com/faq/">licencia</a>.</p> + +<p>Si tu no provees una ventana emergente, entonces el evento clic es disparado hacia tu extensión cuando el usuario de clic sobre el botón. Si provees una ventana emergente entonces el evento clic no se disparará, pero en cambio, se muestra la ventana emergente. Nosotros queremos una ventana emergente, así que vamos a crearla.</p> + +<h3 id="La_ventana_emergente">La ventana emergente</h3> + +<p>La función de la ventana emergente es habilitada si el usuario escoge una de los tres animales.</p> + +<p>Crea una nueva carpeta llamada "popup" bajo la carpeta raíz de la extensión . Esta será donde pondremos el código para la ventana emergente. La carpeta "popup" contendrá estos tres archivos:</p> + +<ul> + <li><strong><code>choose_beast.html</code></strong> define el contenido del panel</li> + <li><strong><code>choose_beast.css</code></strong> los estilos CSS para el contenido</li> + <li><strong><code>choose_beast.js</code></strong> maneja las opciones del usuario ejecutando un script de contenido en la pestaña activa</li> +</ul> + +<h4 id="choose_beast.html">choose_beast.html</h4> + +<p>El archivo HTML luce así:</p> + +<pre class="brush: html line-numbers language-html"><code class="language-html"><span class="doctype token"><!DOCTYPE html></span> + +<span class="tag token"><span class="tag token"><span class="punctuation token"><</span>html</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>head</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>meta</span> <span class="attr-name token">charset</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>utf-8<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>link</span> <span class="attr-name token">rel</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>stylesheet<span class="punctuation token">"</span></span> <span class="attr-name token">href</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>choose_beast.css<span class="punctuation token">"</span></span><span class="punctuation token">/></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"></</span>head</span><span class="punctuation token">></span></span> + +<span class="tag token"><span class="tag token"><span class="punctuation token"><</span>body</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">id</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>popup-content<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">class</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>button beast<span class="punctuation token">"</span></span><span class="punctuation token">></span></span>Frog<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">class</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>button beast<span class="punctuation token">"</span></span><span class="punctuation token">></span></span>Turtle<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">class</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>button beast<span class="punctuation token">"</span></span><span class="punctuation token">></span></span>Snake<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">class</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>button reset<span class="punctuation token">"</span></span><span class="punctuation token">></span></span>Reset<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>div</span> <span class="attr-name token">id</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>error-content<span class="punctuation token">"</span></span> <span class="attr-name token">class</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>hidden<span class="punctuation token">"</span></span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>p</span><span class="punctuation token">></span></span>Can't beastify this web page.<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>p</span><span class="punctuation token">></span></span><span class="tag token"><span class="tag token"><span class="punctuation token"><</span>p</span><span class="punctuation token">></span></span>Try a different page.<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>p</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"></</span>div</span><span class="punctuation token">></span></span> + <span class="tag token"><span class="tag token"><span class="punctuation token"><</span>script</span> <span class="attr-name token">src</span><span class="attr-value token"><span class="punctuation token">=</span><span class="punctuation token">"</span>choose_beast.js<span class="punctuation token">"</span></span><span class="punctuation token">></span></span><span class="tag token"><span class="tag token"><span class="punctuation token"></</span>script</span><span class="punctuation token">></span></span> +<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>body</span><span class="punctuation token">></span></span> + +<span class="tag token"><span class="tag token"><span class="punctuation token"></</span>html</span><span class="punctuation token">></span></span></code></pre> + +<p>Tenemos un elemento <code><div></code> con un ID <code>"popup-content"</code> que contiene un elemento para cada elección de animal. Además, tenemos otro <code><div></code> con un ID <code>"error-content"</code> y una clase <code>"hidden"</code>, que usaremos en el case de que surja algún problema al inicializar la ventana emergente.</p> + +<p>Note que referenciamos los archivos CSS y JS en el HTML como lo haríamos si se tratase de una página web.</p> + +<h4 id="choose_beast.css">choose_beast.css</h4> + +<p>El CSS ajusta el tamaño de la ventana emergente, se asegura que las tres posibles opciones llenen el espacio y les da un poco de estilo básico. Además oculta los elementos con <code>class="hidden"</code>: esto significa que nuestro <code>"error-content"</code> <code><div></code> estará oculto por defecto.</p> + +<pre class="brush: css line-numbers language-css"><code class="language-css"><span class="selector token">html, body</span> <span class="punctuation token">{</span> + <span class="property token">width</span><span class="punctuation token">:</span> <span class="number token">100</span><span class="token unit">px</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.hidden</span></span> <span class="punctuation token">{</span> + <span class="property token">display</span><span class="punctuation token">:</span> none<span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.button</span></span> <span class="punctuation token">{</span> + <span class="property token">margin</span><span class="punctuation token">:</span> <span class="number token">3</span><span class="token unit">%</span> auto<span class="punctuation token">;</span> + <span class="property token">padding</span><span class="punctuation token">:</span> <span class="number token">4</span><span class="token unit">px</span><span class="punctuation token">;</span> + <span class="property token">text-align</span><span class="punctuation token">:</span> center<span class="punctuation token">;</span> + <span class="property token">font-size</span><span class="punctuation token">:</span> <span class="number token">1.5</span><span class="token unit">em</span><span class="punctuation token">;</span> + <span class="property token">cursor</span><span class="punctuation token">:</span> pointer<span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.beast</span><span class="pseudo-class token">:hover</span></span> <span class="punctuation token">{</span> + <span class="property token">background-color</span><span class="punctuation token">:</span> <span class="hexcode token">#CFF2F2</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.beast</span></span> <span class="punctuation token">{</span> + <span class="property token">background-color</span><span class="punctuation token">:</span> <span class="hexcode token">#E5F2F2</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.reset</span></span> <span class="punctuation token">{</span> + <span class="property token">background-color</span><span class="punctuation token">:</span> <span class="hexcode token">#FBFBC9</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="selector token"><span class="class token">.reset</span><span class="pseudo-class token">:hover</span></span> <span class="punctuation token">{</span> + <span class="property token">background-color</span><span class="punctuation token">:</span> <span class="hexcode token">#EAEA9D</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span></code></pre> + +<h4 id="choose_beast.js">choose_beast.js</h4> + +<p>Aquí está el JavaScript para la ventana emergente:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="comment token">/** + * CSS para ocultar toda la página + * Excepto los elementos que pertenecen a la clase "beastify-image". + */</span> +<span class="keyword token">const</span> hidePage <span class="operator token">=</span> <span class="template-string token"><span class="string token">`body > :not(.beastify-image) { + display: none; + }`</span></span><span class="punctuation token">;</span> + +<span class="comment token">/** + * Esucha los clicks en los botones y envía el mensaje apropiado + * al script de contenido de la página. + */</span> +<span class="keyword token">function</span> <span class="function token">listenForClicks</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + document<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">"click"</span><span class="punctuation token">,</span> <span class="punctuation token">(</span><span class="parameter token">e</span><span class="punctuation token">)</span> <span class="operator token">=></span> <span class="punctuation token">{</span> + + <span class="comment token">/** + * Recibe el nombre de una bestia y obtiene la URL de la imagen correspondiente. + */</span> + <span class="keyword token">function</span> <span class="function token">beastNameToURL</span><span class="punctuation token">(</span><span class="parameter token">beastName</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">switch</span> <span class="punctuation token">(</span>beastName<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">case</span> <span class="string token">"Frog"</span><span class="punctuation token">:</span> + <span class="keyword token">return</span> browser<span class="punctuation token">.</span>extension<span class="punctuation token">.</span><span class="function token">getURL</span><span class="punctuation token">(</span><span class="string token">"beasts/frog.jpg"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="keyword token">case</span> <span class="string token">"Snake"</span><span class="punctuation token">:</span> + <span class="keyword token">return</span> browser<span class="punctuation token">.</span>extension<span class="punctuation token">.</span><span class="function token">getURL</span><span class="punctuation token">(</span><span class="string token">"beasts/snake.jpg"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="keyword token">case</span> <span class="string token">"Turtle"</span><span class="punctuation token">:</span> + <span class="keyword token">return</span> browser<span class="punctuation token">.</span>extension<span class="punctuation token">.</span><span class="function token">getURL</span><span class="punctuation token">(</span><span class="string token">"beasts/turtle.jpg"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + <span class="punctuation token">}</span> + + <span class="comment token">/** + * Inserta dentro de la pestaña activa el CSS que oculta la página + * luego toma la URL de la imagen y + * envía un mensaje "beastify" al script de contenido de la pestaña activa. + */</span> + <span class="keyword token">function</span> <span class="function token">beastify</span><span class="punctuation token">(</span><span class="parameter token">tabs</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">insertCSS</span><span class="punctuation token">(</span><span class="punctuation token">{</span>code<span class="punctuation token">:</span> hidePage<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="operator token">=></span> <span class="punctuation token">{</span> + <span class="keyword token">let</span> url <span class="operator token">=</span> <span class="function token">beastNameToURL</span><span class="punctuation token">(</span>e<span class="punctuation token">.</span>target<span class="punctuation token">.</span>textContent<span class="punctuation token">)</span><span class="punctuation token">;</span> + browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">sendMessage</span><span class="punctuation token">(</span>tabs<span class="punctuation token">[</span><span class="number token">0</span><span class="punctuation token">]</span><span class="punctuation token">.</span>id<span class="punctuation token">,</span> <span class="punctuation token">{</span> + command<span class="punctuation token">:</span> <span class="string token">"beastify"</span><span class="punctuation token">,</span> + beastURL<span class="punctuation token">:</span> url + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + + <span class="comment token">/** + * Remueve el CSS que oculta la página y + * envía un mensaje de "reset" al script de contenido de la pestaña activa. + */</span> + <span class="keyword token">function</span> <span class="function token">reset</span><span class="punctuation token">(</span><span class="parameter token">tabs</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">removeCSS</span><span class="punctuation token">(</span><span class="punctuation token">{</span>code<span class="punctuation token">:</span> hidePage<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="operator token">=></span> <span class="punctuation token">{</span> + browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">sendMessage</span><span class="punctuation token">(</span>tabs<span class="punctuation token">[</span><span class="number token">0</span><span class="punctuation token">]</span><span class="punctuation token">.</span>id<span class="punctuation token">,</span> <span class="punctuation token">{</span> + command<span class="punctuation token">:</span> <span class="string token">"reset"</span><span class="punctuation token">,</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + + <span class="comment token">/** + * Imprime el error en consola. + */</span> + <span class="keyword token">function</span> <span class="function token">reportError</span><span class="punctuation token">(</span><span class="parameter token">error</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">error</span><span class="punctuation token">(</span><span class="template-string token"><span class="string token">`Could not beastify: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>error<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + + <span class="comment token">/** + * Toma la pestaña activa y + * llama a "beastify()" o "reset()" según corresponda. + */</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>e<span class="punctuation token">.</span>target<span class="punctuation token">.</span>classList<span class="punctuation token">.</span><span class="function token">contains</span><span class="punctuation token">(</span><span class="string token">"beast"</span><span class="punctuation token">)</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">query</span><span class="punctuation token">(</span><span class="punctuation token">{</span>active<span class="punctuation token">:</span> <span class="boolean token">true</span><span class="punctuation token">,</span> currentWindow<span class="punctuation token">:</span> <span class="boolean token">true</span><span class="punctuation token">}</span><span class="punctuation token">)</span> + <span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>beastify<span class="punctuation token">)</span> + <span class="punctuation token">.</span><span class="function token">catch</span><span class="punctuation token">(</span>reportError<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + <span class="keyword token">else</span> <span class="keyword token">if</span> <span class="punctuation token">(</span>e<span class="punctuation token">.</span>target<span class="punctuation token">.</span>classList<span class="punctuation token">.</span><span class="function token">contains</span><span class="punctuation token">(</span><span class="string token">"reset"</span><span class="punctuation token">)</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">query</span><span class="punctuation token">(</span><span class="punctuation token">{</span>active<span class="punctuation token">:</span> <span class="boolean token">true</span><span class="punctuation token">,</span> currentWindow<span class="punctuation token">:</span> <span class="boolean token">true</span><span class="punctuation token">}</span><span class="punctuation token">)</span> + <span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>reset<span class="punctuation token">)</span> + <span class="punctuation token">.</span><span class="function token">catch</span><span class="punctuation token">(</span>reportError<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="comment token">/** + * Si hubo algún error al ejecutar el script, + * Despliega un popup con el mensaje de error y oculta la UI normal. + */</span> +<span class="keyword token">function</span> <span class="function token">reportExecuteScriptError</span><span class="punctuation token">(</span><span class="parameter token">error</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + document<span class="punctuation token">.</span><span class="function token">querySelector</span><span class="punctuation token">(</span><span class="string token">"#popup-content"</span><span class="punctuation token">)</span><span class="punctuation token">.</span>classList<span class="punctuation token">.</span><span class="function token">add</span><span class="punctuation token">(</span><span class="string token">"hidden"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + document<span class="punctuation token">.</span><span class="function token">querySelector</span><span class="punctuation token">(</span><span class="string token">"#error-content"</span><span class="punctuation token">)</span><span class="punctuation token">.</span>classList<span class="punctuation token">.</span><span class="function token">remove</span><span class="punctuation token">(</span><span class="string token">"hidden"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + console<span class="punctuation token">.</span><span class="function token">error</span><span class="punctuation token">(</span><span class="template-string token"><span class="string token">`Failed to execute beastify content script: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>error<span class="punctuation token">.</span>message<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="comment token">/** + * Cuando se carga la ventana emergente, inyecta el script de contenido en la pestaña activa, + * y agrega un manejador de eventos. + * Si no es posible inyectar el script, se ocupa de manejar el error. + */</span> +browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">executeScript</span><span class="punctuation token">(</span><span class="punctuation token">{</span>file<span class="punctuation token">:</span> <span class="string token">"/content_scripts/beastify.js"</span><span class="punctuation token">}</span><span class="punctuation token">)</span> +<span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>listenForClicks<span class="punctuation token">)</span> +<span class="punctuation token">.</span><span class="function token">catch</span><span class="punctuation token">(</span>reportExecuteScriptError<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>Empecemos por la linea 96. La ventana emergente ejecuta un script de contenido en la pestaña activa tan pronto como se termina de cargar, usando la API <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/executeScript">browser.tabs.executeScript()</a></code>. Si la ejecución del script de contenido es exitosa, este quedará cargado en la página hasta que sea cerrada la pestaña o hasta que el usuario navegue hacia una página distinta.</p> + +<div class="blockIndicator note"> +<p>Un motivo común por el cual el llamado a <code>browser.tabs.executeScript()</code> puede fallar, es porque no es posible ejecutar scripts de contenido en todas las páginas, por ejemplo, en páginas de navegador privilegiadas como about:debugging, o páginas del dominio <a href="https://addons.mozilla.org/">addons.mozilla.org</a>, no es posible hacerlo.</p> +</div> + +<p>Si la ejecución falla, <code>reportExecuteScriptError()</code> ocultará el <code><div></code> <code>"popup-content"</code>, mostrará el <code><div></code> <code>"error-content"</code>, y reportará el error en la consola.</p> + +<p>Si la ejecución del script de contenido es exitosa, se llamará a <code>listenForClicks()</code>, que atiende los eventos que se generan al cliquear en la ventana emergente.</p> + +<ul> + <li>Si el clic se produjo en el botón con <code>class="beast"</code>, se llama a <code>beastify()</code>.</li> + <li>Si el clic se produjo en el botón con <code>class="reset"</code>, se llama a <code>reset()</code>.</li> +</ul> + +<p>La función <code>beastify()</code> hace tres cosas:</p> + +<ul> + <li>map the button clicked to a URL pointing to an image of a particular beast</li> + <li>Oculta todo el contenido de la página al insertar CSS con la API <code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/insertCSS">browser.tabs.insertCSS()</a></code></li> + <li>Envía un mensaje "beastify" al script de contenido usando la API <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/sendMessage">browser.tabs.sendMessage()</a></code>, solicitándole "bestificar" la página, y enviándole la URL de la imagen.</li> +</ul> + +<p>La función <code>reset()</code> deshace lo hecho por <code>beastify()</code>:</p> + +<ul> + <li>Remueve el CSS que agregó, usando la API <code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/removeCSS">browser.tabs.removeCSS()</a></code></li> + <li>Envía un mensaje de "reset" al script de contenido, solicitándole que resetee la página</li> +</ul> + +<h3 id="El_script_de_contenido">El script de contenido</h3> + +<p>Crea una carpeta nueva bajo la raíz del complemento llamada "content_scripts" y crea un nuevo archivo en ella llamado "beastify.js", con el contenido siguiente:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="punctuation token">(</span><span class="keyword token">function</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="comment token">/** + * Revisa e inicializa una variable de guardia. + * Si este script de contenido es insertado más de una vez + * en la misma página, dejará de ejecutarse. + */</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>window<span class="punctuation token">.</span>hasRun<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">return</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + window<span class="punctuation token">.</span>hasRun <span class="operator token">=</span> <span class="boolean token">true</span><span class="punctuation token">;</span> + +<span class="comment token">/** +* Recibe la URL de la imagen, remueve las que se hayan agregado antes, +* crea un nodo IMG que apunt hacia la imagen +* e inserta ese nodo en el documento. +*/</span> + <span class="keyword token">function</span> <span class="function token">insertBeast</span><span class="punctuation token">(</span><span class="parameter token">beastURL</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="function token">removeExistingBeasts</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="keyword token">let</span> beastImage <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">createElement</span><span class="punctuation token">(</span><span class="string token">"img"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + beastImage<span class="punctuation token">.</span><span class="function token">setAttribute</span><span class="punctuation token">(</span><span class="string token">"src"</span><span class="punctuation token">,</span> beastURL<span class="punctuation token">)</span><span class="punctuation token">;</span> + beastImage<span class="punctuation token">.</span>style<span class="punctuation token">.</span>height <span class="operator token">=</span> <span class="string token">"100vh"</span><span class="punctuation token">;</span> + beastImage<span class="punctuation token">.</span>className <span class="operator token">=</span> <span class="string token">"beastify-image"</span><span class="punctuation token">;</span> + document<span class="punctuation token">.</span>body<span class="punctuation token">.</span><span class="function token">appendChild</span><span class="punctuation token">(</span>beastImage<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + + <span class="comment token">/** + * Remueve todas las bestias de la página. + */</span> + <span class="keyword token">function</span> <span class="function token">removeExistingBeasts</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">let</span> existingBeasts <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">querySelectorAll</span><span class="punctuation token">(</span><span class="string token">".beastify-image"</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="keyword token">for</span> <span class="punctuation token">(</span><span class="keyword token">let</span> beast <span class="keyword token">of</span> existingBeasts<span class="punctuation token">)</span> <span class="punctuation token">{</span> + beast<span class="punctuation token">.</span><span class="function token">remove</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + <span class="punctuation token">}</span> + + <span class="comment token">/** + * Atiende mensajes del script de segundo plano. + * Llama a "beastify()" o "reset()". + */</span> + browser<span class="punctuation token">.</span>runtime<span class="punctuation token">.</span>onMessage<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span><span class="punctuation token">(</span><span class="parameter token">message</span><span class="punctuation token">)</span> <span class="operator token">=></span> <span class="punctuation token">{</span> + <span class="keyword token">if</span> <span class="punctuation token">(</span>message<span class="punctuation token">.</span>command <span class="operator token">===</span> <span class="string token">"beastify"</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="function token">insertBeast</span><span class="punctuation token">(</span>message<span class="punctuation token">.</span>beastURL<span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> <span class="keyword token">else</span> <span class="keyword token">if</span> <span class="punctuation token">(</span>message<span class="punctuation token">.</span>command <span class="operator token">===</span> <span class="string token">"reset"</span><span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="function token">removeExistingBeasts</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> + <span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">;</span> + +<span class="punctuation token">}</span><span class="punctuation token">)</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>Lo primero que hace el script de contenido es revisar la variable global <code>window.hasRun</code>: si está inicializada termina su ejecución, sino, la inicializa y continúa. La razón por la que hacemos esto es porque cada vez que el usuario abre la ventana emergente, se vuelve a ejecutar el script de contenido en la pestaña activa, por lo que podríamos tener múltiples instancias del script ejecutandose en una sola pestaña. Si esto sucede, necesitamos asegurarnos de que sea sólo la primera instancia la que vaya a realizar cambios.</p> + +<p>Luego, en la linea 40, donde el script de contenido atiende mensajes provenientes de la ventana emergente (usando la API <code><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/runtime/onMessage">browser.runtime.onMessage</a></code>), vemos que ésta puede enviar dos mensajes diferentes: "beastify" y "reset".</p> + +<ul> + <li>si el mensaje es "beastify", esperamos que contenga la URL de la imagen. Removemos el contenido que ha sido agregado por el anterior llamado a "beastify", y luego construimos y añadimos un elemento <code><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img"><img></a></code> cuyo atributo <code>src</code> contiene la URL de la imagen.</li> + <li>si el mensaje es "reset", simplemente removemos cualquier imagen que haya sido agregada antes.</li> +</ul> + +<h3 id="Las_bestias">Las bestias</h3> + +<p>Finalmente, necesitamos incluir las imágenes de los animales.</p> + +<p>Crea una carpeta nueva llamada "beasts", y adiciona tres imágenes en ella, con su nombre apropiado. Tu puedes obtener estas imágenes desde el <a href="https://github.com/mdn/webextensions-examples/tree/master/beastify/beasts">repositorio en GitHub</a>, o desde aquí:</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="Probándolo">Probándolo</h2> + +<p>Primero, comprueba nuevamente que tienes todos los archivos necesarios en el lugar adecuado:</p> + +<pre class="line-numbers language-html"><code class="language-html">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</code></pre> + +<p>Comenzando con Firefox 45, pueden instalar temporalmente una extensión desde el disco.</p> + +<p>Abre "about:debugging" en Firefox, de clic en "Cargar complemento temporalmente", y seleccione el archivo manifest.json. Entonces, debería de ver el ícono de la extensión aparecer en la barra de herramientas de Firefox:</p> + +<p>{{EmbedYouTube("sAM78GU4P34")}}</p> + +<p>Abra una página web, luego haga clic sobre el ícono, seleccione una bestia, y vea cómo cambia la página web:</p> + +<p>{{EmbedYouTube("YMQXyAQSiE8")}}</p> + +<h2 id="Desarrollo_desde_la_línea_de_comandos">Desarrollo desde la línea de comandos</h2> + +<div id="gt-res-content"> +<div class="trans-verified-button-small" dir="ltr" id="gt-res-dir-ctr"> +<div id="tts_button"> </div> + +<p><span id="result_box" lang="es"><span>Puede automatizar el paso de instalación temporal mediante la herramienta <a href="https://developer.mozilla.org/es/Add-ons/WebExtensions/Getting_started_with_web-ext">web-ext</a>.</span> <span>Pruebe esto</span></span>:</p> +</div> +</div> + +<pre class="brush: bash line-numbers language-bash"><code class="language-bash">cd beastify +web-ext run</code></pre> + +<p> </p> diff --git a/files/es/mozilla/add-ons/webextensions/user_interface/accion_navegador/index.html b/files/es/mozilla/add-ons/webextensions/user_interface/accion_navegador/index.html new file mode 100644 index 0000000000..55ce89a9c7 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/user_interface/accion_navegador/index.html @@ -0,0 +1,50 @@ +--- +title: Botón de la Barra de Herramientas +slug: Mozilla/Add-ons/WebExtensions/user_interface/Accion_navegador +tags: + - WebExtension +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +--- +<div>{{AddonSidebar}}</div> + +<p>Generalmente referidas como <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">acciones de navegador</a>, esta opción de interfaz de usuario corresponde a un botón agregado a la barra de herramientas del navegador. Los usuarios pueden hacer click en el botón para interactuar con tu extensión.<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>El botón de la barra de herramientas (acción de navegador) es muy parecido al botón de la barra de direcciones (acción de página). Para conocer las diferencias y obtener consejo en cuándo usar qué tipo de botón, te recomendamos ver <a href="/en-US/Add-ons/WebExtensions/user_interface/Page_actions#Page_actions_and_browser_actions">Acciones de página y acciones de navegador</a>.</p> + +<h2 id="Especificando_la_acción_de_navegador">Especificando la acción de navegador</h2> + +<p>Puedes definir las propiedades de la acción de navegador utilizando la llave <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> del archivo 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>El único campo obligatorio es <code>default_icon</code>.</p> + +<p>Existen dos formas de especificar una acción de navegador: con o sin una <a href="/en-US/Add-ons/WebExtensions/Popups">ventana emergente</a>. Si no especificas una ventana emergente, se le entregará un evento a la extensión cada vez que el usuario haga click en el botón. El evento es escuchable usando <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>En cambio, si especificas una ventana emergente, el evento de click no es despachado al hacer click en el botón: en su lugar, la ventana emergente es mostrada. El usuario podrá interactuar con la ventana emergente, la cual se cerrará automáticamente cada vez que el usuario haga click fuera de ella. Te recomendamos revisar el artículo de <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Popups">ventanas emergentes</a> para conocer más detalles sobre la creación y administración de éstas.</p> + +<p>Cabe destacar que tu extensión puede tener solamente una acción de navegador.</p> + +<p>Puedes cambiar cualquier propiedad de la acción de navegador de forma programática, utilizando la API <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code>.</p> + +<h2 id="Íconos">Íconos</h2> + +<p>Para más detalles sobre cómo crear íconos para usarlos en tu acción de navegador, revisa <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconografía</a> en la documentación del <a href="https://design.firefox.com/photon/index.html">Sistema de Diseño Photon</a>.</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<p>El repositorio de GitHub <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> contiene dos ejemplos de extensiones que implementan acciones de navegador:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/blob/master/bookmark-it/">bookmark-it</a> usa una acción de navegador sin una ventana emergente.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> usa una acción de navegador con una ventana emergente.</li> +</ul> diff --git a/files/es/mozilla/add-ons/webextensions/user_interface/index.html b/files/es/mozilla/add-ons/webextensions/user_interface/index.html new file mode 100644 index 0000000000..5ddf11d958 --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/user_interface/index.html @@ -0,0 +1,95 @@ +--- +title: User interface +slug: Mozilla/Add-ons/WebExtensions/user_interface +tags: + - Landing + - NeedsTranslation + - TopicStub + - User Interface + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +<div>{{AddonSidebar}}</div> + +<p>Extensions that use WebExtension APIs are provided with several user interface options so that their functionality can be made available to the user. A summary of those options is provided below, with a more detailed introduction to each user interface option in this section.</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">UI option</th> + <th scope="col">Description</th> + <th scope="col" style="width: 350px;">Example</th> + </tr> + </thead> + <tbody> + <tr> + <td><a href="/Add-ons/WebExtensions/user_interface/Browser_action">Toolbar button</a> (browser action)</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 showing a toolbar button (browser action)." src="https://mdn.mozillademos.org/files/15751/browser-action.png" style="height: 364px; width: 700px;"></td> + </tr> + <tr> + <td>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 the pop-up on a toolbar button" src="https://mdn.mozillademos.org/files/15753/popup-shadow.png" style="height: 624px; width: 700px;"></td> + </tr> + <tr> + <td><a href="/Add-ons/WebExtensions/user_interface/Page_actions">Address bar button</a> (page action)</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/15745/address_bar_button.png" style="height: 348px; width: 700px;"></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/15747/page_action_popup.png" style="height: 524px; width: 700px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items">Context menu item</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="Example of content menu items added by a WebExtension, from the context-menu-demo example" src="https://mdn.mozillademos.org/files/15756/context_menu_example.png" style="height: 942px; width: 864px;"></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 sidebar" src="https://mdn.mozillademos.org/files/15755/bookmarks-sidebar.png" style="height: 846px; width: 700px;"></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 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/15748/options_page.png"></td> + </tr> + <tr> + <td><a href="/Add-ons/WebExtensions/user_interface/Extension_pages">Extension page</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/15752/bundled_page_as_panel_small.png" style="height: 432px; width: 700px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications">Notification</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 of an extension triggered system notification" src="https://mdn.mozillademos.org/files/15754/notify-shadowed.png" style="height: 294px; width: 780px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox">Address bar suggestion</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/15749/omnibox_example_small.png" style="height: 464px; width: 700px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels">Developer tools panel</a></td> + <td>A tab with an associated HTML document that displays in the browser's developer tools.</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/15746/developer_panel_tab.png" style="height: 224px; width: 700px;"></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/es/mozilla/add-ons/webextensions/user_interface/page_actions/index.html b/files/es/mozilla/add-ons/webextensions/user_interface/page_actions/index.html new file mode 100644 index 0000000000..0ec310af9f --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/user_interface/page_actions/index.html @@ -0,0 +1,96 @@ +--- +title: Address bar button +slug: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +--- +<div>{{AddonSidebar}}</div> + +<p>Comúnmente denominado botón de acción de página, esta opción de interfaz de usuario es un botón agregado a la barra de direcciones del navegador. Los usuarios pueden hacer clic en el botón para interactuar con sus extensiones.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15745/address_bar_button.png" style="display: block; height: 174px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<h2 id="Acciones_de_página_y_acciones_de_navegador">Acciones de página y acciones de navegador</h2> + +<p>El botón de la barra de direcciones (o página de acción) es muy parecida al botón de la barra de herramientas (o acción del navegador).</p> + +<p>Las diferencias son:</p> + +<ul> + <li><strong>La localización del botón:</strong> + + <ul> + <li>La acción de página es mostrado dentro de la barra de direcciones del navegador.</li> + <li>La acción del navegador es mostrado fuera de la barra de direcciones, exactamente en la barra de herramientas del navegador.</li> + </ul> + </li> + <li><strong>La visibilidad del botón:</strong> + <ul> + <li>La acción de página esta oculta por defecto (sin embargo esto puede ser cambiado en la propiedades <code>show_matches</code> y <code>hide_matches</code> <a href="/en-US/Add-ons/WebExtensions/manifest.json/page_action">manifest key</a>), y tu puedes llamar <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> y <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> para mostrar o ocultar esto en pestañas especificas.</li> + <li>La acción del navegador siempre esta mostrada.</li> + </ul> + </li> +</ul> + +<p>Usa una página de acción cuando cuando la acción este relacionada a la página en curso, y una acción de navegador cuando cuando la acción este relacionada a todas o a muchas páginas. Por ejemplo:</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row">Type</th> + <th scope="col">Bookmarks action</th> + <th scope="col">Content action</th> + <th scope="col">Tabs operation</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">page action</th> + <td>Marcar esta página</td> + <td>Reddit enhancement</td> + <td>Enviar una pestaña</td> + </tr> + <tr> + <th scope="row">browser action</th> + <td>Mostrar todos los marcadores</td> + <td>Habilitar ad-blocking</td> + <td>Sincronizar todas las pestañas</td> + </tr> + </tbody> +</table> + +<h2 id="Specifying_the_page_action">Specifying the page action</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>.</p> + +<ul> + <li><strong>Without a popup:</strong> 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>:</li> + <li> + <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> + </li> + <li><strong>With a popup:</strong> the <code>click</code> event is not dispatched. Instead, the popup appears when the user clicks the button. The user then interacts with the popup. When the user clicks outside of the popup, it closes automatically. 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.</li> +</ul> + +<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="Icons">Icons</h2> + +<p>For details on how to create icons to use with your page 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="Examples">Examples</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/chill-out">chill-out</a> example which implements a page action without a popup.</p> diff --git a/files/es/mozilla/add-ons/webextensions/what_next_/index.html b/files/es/mozilla/add-ons/webextensions/what_next_/index.html new file mode 100644 index 0000000000..7566eb1bff --- /dev/null +++ b/files/es/mozilla/add-ons/webextensions/what_next_/index.html @@ -0,0 +1,56 @@ +--- +title: What next? +slug: Mozilla/Add-ons/WebExtensions/What_next_ +translation_of: Mozilla/Add-ons/WebExtensions/What_next_ +--- +<div>{{AddonSidebar}}</div> + +<p>Ahora estarás listo para comenzar a convertir tus idea para una extensión de navegador en realidad. Antes de comenzar ese viaje, vale la pena ser consciente de algunas cosas que ayudarán a que sea más sencillo.</p> + +<h2 id="Tu_ambiente_de_desarrollo">Tu ambiente de desarrollo</h2> + +<p>No necesitas ninguna herramienta de desarrollo ni entorno de creación en especial a la hora de crear extensiones de navegador: es completamente posible crear grandes extensiones de navegador solo con un editor de texto. Sin embargo, puede ser que tu hayas estado desarrollando para la web y ya poseas un conjunto de herramientas y un entorno que desees reutilizar. Si este es el caso, necesitarás estar al tanto de un par de cosas.</p> + +<p>Si utilizas herramientas de minificación u ofuscación para obtener tu código final, deberás proporcionar tu código fuente al <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/What_next_#The_review_process">proceso de revisión de AMO</a>. Además, las herramientas que uses (aquellas para los procesos de minificación, ofuscación y creación) deberán ser de código abierto (u ofrecer un uso gratuito ilimitado) y estar disponibles para ejecutarse en la computadora del revisor (Windows, Mac o Linux). Desafortunadamente, nuestros revisores no pueden trabajar con herramientas comerciales o basadas en la web.</p> + +<p><a href="/en-US/Add-ons/Source_Code_Submission#About_build_tools">Aprenda más sobre las herramientas de construcción</a></p> + +<h2 id="Bibliotecas_de_Terceros">Bibliotecas de Terceros</h2> + +<p>Las bibliotecas de terceros son una excelente manera de agregar características complejas o funcionalidades a su extensiones para navegador rápidamente. Cuando envía una extensión al <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/What_next_#The_review_process">proceso de revisión de AMO</a>, el proceso también considerará las bibliotecas de terceros utilizadas. Para simplificar la revisión, asegúrese de descargar siempre bibliotecas de terceros desde su sitio web oficial o repositorio, y si la biblioteca está minimizada, proporcione un enlace al código fuente. Tenga en cuenta que las bibliotecas de terceros no se pueden modificar de ninguna manera.</p> + +<p><a href="/en-US/Add-ons/Source_Code_Submission">Aprenda más sobre el envío de código fuente </a></p> + +<h2 id="Acuerdo_de_Distribución_para_Complementos_de_Firefox">Acuerdo de Distribución para Complementos de Firefox</h2> + +<p>Las extensiones del navegador deben estar firmadas para instalarse en la versión de lanzamiento o en las versiones beta de Firefox. La firma se realiza en addons.mozilla.org (AMO) y está sujeta a los términos y condiciones del Acuerdo de Distribución de Complementos de Firefox. El objetivo del acuerdo es garantizar que los usuarios de Firefox tengan acceso a complementos de calidad bien soportados que mejoren la experiencia de Firefox.</p> + +<p><a href="/Add-ons/AMO/Policy/Agreement">Lea el Acuerdo</a></p> + +<p><a href="/en-US/Add-ons/WebExtensions/Distribution">Aprenda más sobre la firma</a></p> + +<h2 id="Proceso_de_revisión">Proceso de revisión</h2> + +<p>Cuando se envíe una extensión del navegador para su firma, estará sujeta a revisión automática. También podría estar sujeto a una revisión manual, cuando la revisión automática determine que se necesita una revisión manual. La extensión de su navegador no se firmará hasta que haya pasado la revisión automática y puede revocarse su firma si no pasa la revisión manual. El proceso de revisión sigue un estricto conjunto de pautas, por lo que es fácil verificar y evitar cualquier posible problema de revisión.</p> + +<p><a href="/en-US/Add-ons/AMO/Policy/Reviews">Echa un vistazo a las políticas y directrices de revisión</a></p> + +<h2 id="Entensiones_de_navegador_destacadas_AMO">Entensiones de navegador destacadas AMO</h2> + +<p>Si eliges enlistar tu extensión de navegador en AMO, tu extensión podría aparecer en el sitio web de AMO, en el administrador de complementos del navegador Firefox, o en cualquier otro lugar en un sitio web de Mozilla. Hemos compilado una lista de pautas sobre cómo se seleccionan las extensiones para presentarlas; al seguir estas pautas, le da a su extensión la mejor oportunidad de ser presentada.</p> + +<p><a href="/en-US/Add-ons/AMO/Policy/Featured">Aprenda más sobre como destacar sus complementos</a></p> + +<h2 id="Continua_tu_experiencia_de_aprendizaje">Continua tu experiencia de aprendizaje</h2> + +<p>Ahora que sabe lo que sigue, es hora de profundizar en más detalles sobre el desarrollo de extensiones de navegador. En las siguientes secciones, descubrirás:</p> + +<ul> + <li>Más sobre los conceptos fundamentales detrás de las extensiones del navegador, comenzando con detalles sobre cómo <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Using_the_JavaScript_APIs">usar las API de JavaScript</a>.</li> + <li>Una guía de los <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface">componentes de interfaz de usuario</a> disponibles para las extensiones de su navegador.</li> + <li>Una recopilación de guías prácticas sobre cómo lograr tareas clave en sus extensiones o hacer uso de las API de JavaScript.</li> + <li>Información sobre cómo portar otras extensiones de navegador a Firefox.</li> + <li>Detalles sobre los flujos de trabajo específicos de Firefox que puede utilizar para desarrollar extensiones de navegador.</li> + <li>Una completa guía de referencia sobre las API de JavaScript.</li> + <li>Una completa guía de referencia sobre Manifest keys.</li> +</ul> |