Ваш первый WebExtension

В этой статье мы пройдем весь путь создания WebExtension для Firefox, от начала и до конца. Это дополнение будет просто добавлять красную рамку ко всем страницам, загруженным с "mozilla.org" или любого из его поддоменов.

Исходный код этого дополнения доступен на GitHub: https://github.com/mdn/webextensions-examples/tree/master/borderify.

Для начала вам нужен Firefox 45 или более поздней версии.

Написание WebExtension

Создайте новую директорию (папку) и перейдите в нее:

mkdir borderify
cd borderify

manifest.json

Теперь создайте новый файл, назовите его "manifest.json" в папке "borderify". Вставьте туда следующий код:

{

  "manifest_version": 2,
  "name": "Borderify",
  "version": "1.0",
 
  "description": "Adds a solid red border to all webpages matching mozilla.org.",
  "icons": {
    "48": "icons/border-48.png"
  },

  "applications": {
    "gecko": {
      "id": "[email protected]",
      "strict_min_version": "45.0"
    }
  },

  "content_scripts": [
    {
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ]

}

Первые три ключа: manifest_version, name и version, являются обязательными и содержат основные метаданные о дополнении.
description не обязателен, но рекомендуется: он отображается в диспетчере дополнений.
icons не обязателен, но рекомендуется: позволяет указать значок для дополнения, который будет виден в диспетчере дополнений.
applications является обязательным для Firefox, и определяет ID дополнения. Он так же может использоваться для указания минимальной и максимальной версии Firefox, поддерживаемой расширением.

Самый интересный ключ здесь - это content_scripts, который говорит Firefox загружать скрипт на Web страницах, чей URL совпадает с заданным шаблоном. В нашем случае, мы просим Firefox загрузить скрипт с названием "borderify.js" на всех HTTP или HTTPS страницах, полученных с "mozilla.org" или любого из его поддоменов. /en-US/Add-ons/WebExtensions/Content_scripts

icons/border-48.png

Дополнение должно иметь значок. This will be shown next to the add-on's listing in the Add-ons Manager. Our manifest.json promised that we would have an icon at "icons/border-48.png".

Create the "icons" directory directly under the "borderify" directory. Save an icon there named "border-48.png". You could use the one from our example, which is taken from the Google Material Design iconset, and is used under the terms of the Creative Commons Attribution-ShareAlike license.

If you choose to supply your own icon, It should be 48x48 pixels. You could also supply a 96x96 pixel icon, for high-resolution displays, and if you do this it will be specified as the 96 property of the icons object in manifest.json:

"icons": {
  "48": "icons/border-48.png",
  "96": "icons/border-96.png"
}

Alternatively, you could supply an SVG file here, and it will be scaled correctly.

Learn more about specifying icons.

borderify.js

Finally, create a file called "borderify.js" directly under the "borderify" directory. Give it this content:

document.body.style.border = "5px solid red";

This script will be loaded into the pages that match the pattern given in the content_scripts manifest.json key. The script has direct access to the document, just like scripts loaded by the page itself.

Learn more about content scripts.

Testing it out

First, double check that you have the right files in the right places:

borderify/
    icons/
        border-48.png
    borderify.js
    manifest.json

Starting in Firefox 45, you can install WebExtensions temporarily from disk.

Open "about:debugging" in Firefox, click "Load Temporary Add-on" and select your manifest.json file:

The add-on will now be installed, and will stay until you restart Firefox.

To check, visit "about:addons" to open the Add-ons Manager. You should see the add-on listed, with its icon, name, and description:

Now try visiting a page under "mozilla.org", and you should see the red border round the page:

Try experimenting a bit. Change the color of the border, or do something else to the page content. If you save the content script, then reload the target page, you can see the changes right away:

Note, though, that if you change manifest.json, you must manually reload the add-on. At the moment, this means you need to restart Firefox, and load the add-on in about:debugging again. We're working on improving this.

Learn more about loading add-ons

Packaging and publishing

For other people to use your add-on, you need to package it. Firefox add-ons are packaged as XPI files, which are just ZIP files with an "xpi" extension.

One trick is that the ZIP file must be a ZIP of the files in the extension, not of the containing directory. So to create an XPI from the borderify files, navigate to the "borderify" directory in a command shell and type:

   zip -r ../borderify.xpi *

From Firefox 43 onwards, add-ons must be signed before they can be installed in Firefox. You can remove this restriction in Firefox Developer Edition or Firefox Nightly only, by following these steps:

type about:config into the URL bar in Firefox
in the Search box type xpinstall.signatures.required
double-click the preference, or right-click and selected "Toggle", to set it to false.

What's next?

Now you've got an idea of the process of developing a WebExtension for Firefox, try: