Firefox Browser Extensions App (WebExtensions)

For people whose work involves using the Internet, browser extensions can be very useful tools. Using them, you can save the user from repeating the same actions and better organize the workflow. You can compose a toolbox from existing extensions, but this is not enough.

For someone who knows web development, it’s easy to create a new browser extension. Now most of the most popular browsers support the standard development system, which uses mainly JavaScript, HTML and CSS, - WebExtensions .

It may be difficult for a person who has never created a browser add-on based on WebExtensions before to immediately understand what basic parts it should consist of and what it can do. On the Internet there is a lot of information about this system, but in order to create an overall picture for yourself, you will have to spend a lot of time. This article will help you quickly understand the structure of the WebExtensions system and show how to better navigate the documentation for its API . The extension for the Firefox browser is described here , so almost all the information used in the article is taken from the MDN website . But the article will be useful to those who want to create an extension for other browsers that support WebExtensions, - primarily for Google Chrome and Chromium .

This section covers creating desktop- only extensions . If you need to create an extension for the Chrome or Firefox mobile browser , this article can also be something useful, but you will have to find and study most of the information yourself.

Introduction

What you need to get started

And here's what you need:

• Firefox Browser - Best Version 60 or Higher. Throughout the article, it is assumed that such a browser is used, unless otherwise stated. But you can use Google Chrome or Chromium instead .
  
• HTML CSS, -.
  
• Javascript. ECMA, Promise .
  
• , API. , , ( ), . - «» MDN — , .
  
• Python Node.js.
  
• , , - .
  

Firefox 60 WebExtensions — . - Firefox 52.

Google Chrome Chromium WebExtensions , . , , . API Firefox , Building a cross-browser extension. , , Firefox, Chrome.

, , API Chrome.

, . , . , , .

— . — manifest.json. — -, . - , , , , , . — Javascript, HTML, CSS, (, ).

, :

• . , , . , . .
  
• - .
  
• , , . , , .
  
• , .
  
• , .
  
• , .
  
• , , . . , -.
  
• .
  

, — . . , , -, — .

— , .

«» , API WebExtensions. API, .

:

• « » MDN
• «Overview» developer.chrome.com

WebExtensions

, WebExtensions, , MDN. .

API WebExtensions:

, API WebExtensions, . Firefox browser, Google Chrome — chrome. , — window, — -.

, . — window. — API WebExtensions, — browser. window . , , , — , window, «window.» . API WebExtensions «browser.» . , WebExtensions MDN, , runtime.id . , —

var myAddonId = browser.runtime.id;

browser , . , API WebExtensions , .

— . , . . , .

DOM . -, HTML-, , HTML-! , , — window browser.

. — -. , -. , , . , . , . , , , ( « ») — .

:

• API WebExtensions, . MDN .
  
• HTML-, CSS JavaScript, JavaScript. HTML- . , , -. : HTML- JavaScript, <script>, — <script src="my_script.js"></script>! , .
  
• -, . window HTML-.
  
• JavaScript -, . . , HTML, , . — .
  

( )

- :

• API WebExtensions, .
  
• -. HTML — -. JavaScript CSS.
  
• DOM , — , API window. «» -. , , -. , - window, — .
  

, — -. , , , .

. , : window HTML- browser. , — , — - ( , ) . .

, , .

, : — , («Extension»), — , («Design»), — , («Native»). «Build», -. , , . , , : , «icons», «_locales» ( ). :

My_project
|--Design
|  |--concept.md
|
|--Build
|  |--my_extension-1.0.0.zip
|
|--Native
|  |--native_program.py
|  |--native_program_manifest.json
|  |--run.bat
|  |--install.sh
|  |--install.bat
|
|--Extension
   |--manifest.json
   |--background.js
   |--content.js
   |--browser_popup
   |  |--menu.html
   |  |--menu.css
   |  |--menu.js
   |
   |--icons
      |--my_extension.svg

manifest.json, . , . JSON. JavaScript, .

manifest.json MDN.

, — :

• manifest_version — 2.
  
• name — , .
  
• version — .
  

— short_name. , .

— description

. , , :

• author — . , , , .
  
• homepage_url — URL- . - , , , GitHub.
  

- developer. , .

,

browser_specific_settings.

Firefox, . , , ID . ( ) , ID . ID , . , — .

my_extension@user.habr.com
my_extension@user.github.com
my_extension@user.addons.mozilla.org

-

-, . , : ( -> -> ) , . icons.

MDN , — 48x48 , 32x32. — , Retina display Apple. , , : 32x32, 64x64, 48x48 96x96 .

PNG SVG. SVG , — . , Google Chrome SVG .

manifest.json. , .

{
  //       2
  "manifest_version": 2,

  //  
  "name": "Habr article editor",
  "short_name": "Habr Editor",

  // 
  "version": "1.0.0",

  //   
  "description": "Enhances editor of articles on habr.com site to support Markdown Extra",

  //   —   
  "author": "Aleksandr Solovyov",

  //    ,  —  
  //    GitHub
  "homepage_url": "https://github.com/alexandersolovyov/habr_editor",


  //       Firefox
  "browser_specific_settings": {
    "gecko": {
      "id": "habr_editor@alexandersolovyov.github.com",
      "strict_min_version": "52.0"
    }
  },

  // -
  "icons": {
    "32": "icons/habr_editor.svg",
    "64": "icons/habr_editor.svg",
    "48": "icons/habr_editor.svg",
    "96": "icons/habr_editor.svg"
  },

  ...
}

, , , , - . .

API

, API WebExtensions. , «» API, - .

permissions . , , , , , . , , « », .

, . , , . , , . optional_permissions. , , , permissions. API.

— permissions, optional_permissions. API . API, . , , permissions, optional_permissions. : — , ! API, , API WebExtensions. API , — , API, , .

-

- . , (host permissions) (activeTab). , .

activeTab . , -. , , URL, . , <all_urls> tabs, , .

host permissions . URL -, URL . , AJAX — , , HTTP- cookie. <all_urls> host permissions. , .

(options page)

, — . , -> ( ), . , ( , ) , . , , , . — - .

, -: HTML, CSS JavaScript.

HTML- options_ui. , . , , "open_in_tab": true options_ui.

, , , . — .

Options page.

storage API.

. , — , .

JavaScript, HTML- ( CSS!). background . , , DOM . HTML .

: , . WebExtensions . — , . persistent background — true. , , JavaScript .

:

1. Firefox, , ( ) , , , . . browser_action. , - — HTML, CSS JavaScript. , . — .addListener() - browser.browserAction.onClicked. — Toolbar Buttton MDN
   
2. URL . — page_action. . , browser.pageAction.onClicked. — Address bar button.
   
3. Firefox , -> . , sidebar_action. — , . , — . ( — ), . , -. Sidebars
   

Popups MDN

, , . — «», .

-

, -, , JavaScript CSS. , - , — , . .

- :

• content_scripts. JavaScript, CSS. , URL- . - , URL- . ( ) , , . (permissions).
  
• . : URL . , . . JavaScript, CSS, , . API browser.contentScripts. browser.contentScripts.register() URL . Promise. «» ( .then()) browser.contentScripts.RegisteredContentScript, « ». .unregister() . , -, . permissions - (host permissions), -, .
  
• . JavaScript — , . browser.tabs.executeScript(). , , (ID). Promise. , URL , browser.tabs.query(). Promise, - . ID browser.tabs.executeScript(). , , , permissions activeTab, , URL- (host permissions).
  

, . , , : , HTML- , . API: content_scripts , run_at, JavaScript, , — runAt .

, , , «» ( , ).

CSS , - <link>. JavaScript :

• DOM -, .
• API WebExtensions. API.
• AJAX ( XMLHttpRequest Fetch). - (host permissions), - AJAX , .
• «» - , API window. , , MDN.

, «» DOM , window, :

• JavaScript, «» -.
  
• , , «» .
  
• , «» -, , DOM. , , -, «» , .
  

MDN.

, - CSS JavaScript. , , - HTML. , — , StackOverflow.

, - . commands -.

. — , . — , . . — browser.commands.onCommand.addListener().

- , . context_menus. , — .

Firefox API browser.menus. - — browser.contextMenus. Firefox, , . .

, browser.menus.create(). ( ). , , , — , — .

, . , browser.menus.onClicked. , , , : , HTML-, .

DOM -, , JavaScript — browser.tabs.executeScript(). : , HTML-, . browser.menus.getTargetElement().

API

API WebExtensions. browser.runtime . API . — browser.tabs. . API .

API WebExtensions , :

• API browser.runtime.
  
• API browser.tabs.
  
• , - ( ), .
  

JavaScript, , , JSON . . JSON. , , , undefined, Symbol . , DOM . , , JSON JSON.stringify() , .

.

, , , . , . - , . :

1. , , sendMessage(). , browser.runtime.sendMessage(), — browser.tabs.sendMessage(). -, , , — , , .
   
2. onMessage, — browser.runtime.onMessage. . - — browser.runtime.onMessage.addListener(). - -, .
   
3. - , Promise. Promise . , , Promise resolve() reject(). , -, JSON. Error: !
   
4. , , sendMessage() Promise, — .then() .catch(). - - — .
   

, , — . , ( ), , «» Promise «».

, « ». API , — , . . :

1. connect(). , , browser.runtime.connect(), — browser.tabs.connect(). , . , .
   
2. connect() browser.runtime.Port, API «» . , - port1.
   
3. , , browser.runtime.onConnect — , , . - — browser.runtime.onConnect.addListener(). , - browser.runtime.Port — , , , . , port2. , -.
   
4. , . postMessage() ( port1.postMessage()) -.
   
5. onMessage ( — port2.onMessage). , port2.onMessage.addListener(). - . , port2.postMessage().
   
6. , «-». , , -, , : , «status» «error» «ok».
   
7. « » .disconnect() -. , , . window.onclose() port1.disconnect(). .
   
8. , - . port2.onDisconnect.addListener(). - - . - .disconnect() , .error window.Error. , . error Firefox, , browser.runtime.lastError.
   

, API WebExtensions , , ( «» «native»), , . .

, API . — , (, Python, Node.js Java), . — . , . .

— Python Node.js, . , , . . , -, , .

Native messaging. , — .

, , , . , , , - , - ( ). , «», . , -. , , Native Manifests.

API WebExtensions . , . .

.

, , JavaScript, JSON. UTF-8. (), 4 . — . ( stdin). (stdout) JSON , . JavaScript, .

, , . , , , JSON — , . , , , .

:

1. browser.runtime.sendNativeMessage(). ( name ) -, .
   
2. stdin , , .
   
3. .
   
4. stdout.
   
5. ! .
   
6. , (browser.runtime.sendNativeMessage()), Promise. : .then() .catch(). :
   
   • , . , .then(), - .
     
   • , , , , , (null undefined).
     
   • , , .catch(). Error .
     
   
   

, , — . , , , , , .

. :

1. browser.runtime.connectNative() — ( ).
   
2. . . , !
   
3. browser.runtime.connectNative(), , browser.runtime.Port — , , . port.
   
4. port.postMessage() .
   
5. (stdin) .
   
6. , — stdout.
   
7. , . - port.onMessage.addListener(). - .
   
8. :
   
   • , . , .
     
   • - , .
     
   • port.disconnect(), .
     
   
   
9. port.onDisconnect. -. , .error, . , Chromium, - — Firefox. browser.runtime.lastError.
   

, , .

API WebExtensions . :

• API browser.storage.
  
• . , Internationalization.
  
• : , , - . API browser.downloads.
  
• — , , . . browser.windows.create().
  
• . - , . browser.windows.create().
  
• — theme .
  
• HTTP- . API browser.webRequest.
  
• . browser.runtime.sendMessage(), — browser.runtime.onMessageExternal.
  
• , . Extending the developer tools.
  

web-ext

WebExtensions MDN web-ext. , Node.js, , , , Mozilla. , , , , «» . «» Firefox , , , .

web-ext Extension Workshop. , , «».

, , , :

• about:debugging Enter . Firefox.
  
• .
  
• - , .
  

. about:debugging . «» .

, :

• about:debugging , .
  
• , , .
  
• , .
  
• , , F12.
  

. , — , . , . , -. , , -, .

Firefox web-ext, , , , , ZIP. , : , GIT, NPM , , , Managed Storage PKCS#11.

Firefox . Extension Workshop.

, , , . , API WebExtensions. — , .

«» , :

• , Firefox — Extension Workshop
  
• - — Browser Extensions: Firefox workflow overview
  
• - — manifest.json
  
• API WebExtensions MDN — JavaScript APIs
  
• API WebExtensions Google Chrome — Chrome APIs
  
• API WebExtensions Opera — Extension APIs Supported in Opera
  
• API WebExtensions Edge — Microsoft Edge: Supported APIs
  
• - : , — Native Manifests
  

:

• 
  
• developer.chrome.com: Overview
  
• Building a cross-browser extension
  
• Options page
  
• Toolbar Buttton
  
• Address bar button
  
• Sidebars
  
• Popups
  
• Content scripts
  
• StackOverflow: Adding complex HTML using a Chrome content script
  
• Internationalization
  
• Native messaging
  

• Firefox Add-ons Site (Firefox Browser ADD-ONS)