Ваше первое расширение - Mozilla

Ваше первое расширение
======================

**Примечание:** Если вы уже знакомы с основными понятиями о браузерных расширениях, то можете пропустить этот раздел и узнать как собираются файлы расширений. Также вы можете использовать справочную документацию чтобы начать создавать свои расширения. Посетите Мастер-класс по расширениям Firefox чтобы узнать больше о тестировании и публикации расширений для Firefox

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

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

Написание расширения
--------------------

Создайте новую папку с именем `borderify` и перейдите в неё. Вы можете сделать это с помощью Проводника вашего компьютера или терминала командной строки (en-US). Умение работать с терминалом командной строки очень полезно, поскольку оно помогает вести более продвинутую разработку расширений. Используя терминал, создать папку можно следующим образом:

```bash
mkdir borderify
cd borderify
```

### manifest.json

Используя удобный текстовый редактор, создайте в папке `borderify` новый файл с именем `manifest.json` и таким содержимым:

```json
{
  "manifest\_version": 2,
  "name": "Borderify",
  "version": "1.0",

  "description": "Adds a red border to all webpages matching mozilla.org.",

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

  "content\_scripts": [
    {
      "matches": ["\*://\*.mozilla.org/\*"],
      "js": ["borderify.js"]
    }
  ]
}
```

* Первые три ключа: `manifest_version`, `name` и `version`, являются обязательными и содержат основные метаданные о расширении.
* `description` не обязателен, но рекомендуется добавлять его: это описание отображается в Управлении дополнениями.
* `icons` не обязателен, но рекомендуется добавлять его: он позволяет указать значок дополнения, который будет виден в Управлении дополнениями.

Самый интересный ключ здесь — это `content_scripts` (en-US), он даёт указание Firefox загружать указанный скрипт на веб-страницах, у которых URL совпадает с заданным шаблоном. В нашем случае, мы просим Firefox загрузить скрипт с названием `borderify.js` на всех HTTP или HTTPS страницах, полученных с `mozilla.org` или любого из его поддоменов.

* Узнать больше о шаблонах совпадения

**Предупреждение:** В некоторых случаях вам нужно указать ID для вашего дополнения. Если это необходимо, то добавьте ключ `browser_specific_settings` (en-US) в файл `manifest.json` и установите свойство `gecko.id`:

```json
"browser\_specific\_settings": {
  "gecko": {
    "id": "borderify@example.com"
  }
}
```

### icons/border-48.png

Если у расширения есть значок, то он будет отображаться в списке расширений Управления дополнениями. Наш файл `manifest.json` сообщает, что значок находится в файле `icons/border-48.png`.

Создайте папку `icons` внутри `borderify` и поместите в неё файл значка с именем `border-48.png`. Вы можете использовать значок из нашего примера, который взят из набора Google Material Design и используется по лицензии Creative Commons Attribution-ShareAlike.

Вы можете использовать собственный значок. Его размер должен быть 48x48 пикселей или 96x96 пикселей для отображения на мониторах с высоким разрешением. В этом случае необходимо указать его в качестве свойства `96` объекта `icons` в файле `manifest.json`:

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

Также можно использовать файл в формате SVG, и он будет правильно масштабироваться. Но нужно иметь в виду, что если вы используете SVG и ваш значок содержит текст, то возможно стоит воспользоваться инструментом «преобразовать в контур» в редакторе SVG, чтобы текст масштабировался корректно.

* Узнать больше об использовании значков
### borderify.js

Наконец, создайте в папке `borderify` файл с именем `borderify.js` с таким содержимым:

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

Этот скрипт будет встраиваться в страницы, адрес которых совпадает с шаблоном, указанном в ключе `content_scripts` файла `manifest.json`. Этот скрипт имеет прямой доступ ко всему документу, как если бы он был загружен самой страницей.

* Узнать больше о встраиваемых скриптах
Пробуем
-------

Сначала внимательно проверьте, что вы правильно разместили файлы и дали им правильные имена:
```

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

### Установка

В Firefox: откройте страницу about:debugging, кликните `Этот Firefox`, далее нажмите на кнопку `Загрузить временное дополнение...` и выберите любой файл из папки с нашим примером.

Расширение будет установлено и остается установленным до перезапуска Firefox.

Также можно запустить расширение с помощью командной строки используя утилиту web-ext.

### Тестирование

**Примечание:** По умолчанию расширения не работают в режиме приватного просмотра. Если вы хотите протестировать расширение в режиме приватного просмотра, то откройте `about:addons`, выберите расширение и установите переключатель `Запуск в приватных окнах` в положение `Разрешить`.

Теперь перейдите на любую страницу "`https://www.mozilla.org/ru/`" и вы должны будете увидеть красную границу вокруг страницы.

![На mozilla.org отображается рамка](/ru/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension/border_on_mozilla_org.png)

**Примечание:** Не проверяйте на `addons.mozilla.org`! Встраиваемые скрипты на данный момент запрещены на этом поддомене.

Попробуйте немного поэкспериментировать. Измените цвет границы или сделайте что-нибудь ещё с содержимым страницы. Для этого внесите изменения в скрипт и перезагрузите файлы расширения, нажав кнопку `Обновить` в `about:debugging`. Сразу после этого изменения станут видны.

* Узнать больше о временной установке расширений в Firefox
Упаковка и публикация
---------------------

Чтобы другие люди могли использовать ваше дополнение, необходимо запаковать его и отправить в Mozilla для добавления подписи. Узнать больше об этом можно в разделе "Publish" Мастер-класса по расширениям Firefox.

Что дальше?
-----------

Теперь, когда вы имеете представление о разработке расширений для Firefox, вы можете:

* создать более сложное расширение,
* узнать больше о внутреннем устройстве расширений,
* посмотреть примеры расширений,
* узнать, что необходимо для разработки, тестирования и публикации расширений (en-US).


Интернационализация - Mozilla

Интернационализация
===================

WebExtensions API предоставляет полезный модуль для интернационализации расширений — i18n (en-US). В этой статье мы рассмотрим его особенности и пример его работы. Система для расширений, построенных с помощью WebExtension API, i18n похожа на библиотеки JavaScript для i18n, такие как i18n.js.

**Примечание:** Расширение, используемое в этой статье в качестве примера, — notify-link-clicks-i18n — доступно на GitHub. Читая последующие секции этой статьи, вы можете исследовать его исходный код.

Структура интернализированного расширения
-----------------------------------------

Интернационализированное расширение может содержать такие же элементы, как и любое другое расширение — фоновые скрипты, встраиваемые скрипты, и т. д. — а также дополнительные инструменты, позволяющие переключаться между разными локализациями. Их можно представить следующим деревом директорий:

* корневая-директория-расширения/
    + \_locales
        - en
            * messages.json
                + Сообщения на английском (строки)
        - de
            * messages.json
                + Сообщения на немецком (строки)
        - и т. д.
    + manifest.json
        - Метаданные, зависящие от локализации
    + myJavascript.js
        - Файл JavaScript, получающий локализацию браузера, сообщения, зависящие от локализации, и т. д.
    + myStyles.css
        - CSS, зависящий от локализации

Давайте отдельно рассмотрим каждый элемент — последующие секции представляют собой шаги, которым стоит следовать во время интернационализации вашего расширения.

Добавление локализованных строк в \_locales
-------------------------------------------

Вы можете определить тэг языка при помощи инструмента *Find* на странице определения языковых тегов. Обратите внимание на то, что при поиске нужно использовать английское название языка

Каждая система i18n требует предоставить строки во всех локализациях, которые вы хотите поддерживать. В расширениях они хранятся в директории `_locales`, размещённой внутри корневой директории. Строки каждой локализации (также называемые сообщениями) хранятся в файле `messages.json`, находящемся в поддиректории `_locales`, название которой - тег языка локализации.

Стоит заметить, что если тег включает в себя и базовый язык, и его региональный вариант, то по конвенции эти язык и вариант разделяются дефисом: например, "en-US". Однако в поддиректориях `_locales`, **вместо дефиса используется нижнее подчёркивание**: "en\_US".

Таким образом, в нашем примере существую директории "en" (английский), "de" (немецкий), "nl" (голландский), and "ja" (японский). Внутри каждой из них находится файл `messages.json` .

Давайте рассмотрим структуру одного из этих файлов (\_locales/en/messages.json):

```json
{
  "extensionName": {
    "message": "Notify link clicks i18n",
    "description": "Name of the extension."
  },

  "extensionDescription": {
    "message": "Shows a notification when the user clicks on links.",
    "description": "Description of the extension."
  },

  "notificationTitle": {
    "message": "Click notification",
    "description": "Title of the click notification."
  },

  "notificationContent": {
    "message": "You clicked $URL$.",
    "description": "Tells the user which link they clicked.",
    "placeholders": {
      "url": {
        "content": "$1",
        "example": "https://developer.mozilla.org"
      }
    }
  }
}
```

Это стандартный файл JSON — каждый из его элементов является объектом с именем, содержащим сообщение (`message)` и описание (`description)`. Оба предмета - строки; `$URL$` — это заполнитель, который заменяется подстрокой, когда элемент `notificationContent` вызывается расширением. Вы научитесь это делать в секции Получение сообщений из JavaScript.

**Примечание:** вы можете найти больше информации о структуре `messages.json` здесь (en-US).

Интернационализация manifest.json
---------------------------------

Для интернационализации файла manifest.json нужно предпринять несколько шагов.

### Получение локализованных строк в манифестах

Ваш файл manifest.json содержит строки, отображаемые пользователю, такие как имя и описание расширения. Если вы интернационализируете эти строки и поместите их переводы в messages.json, то эти переводы будут отображаться пользователю в зависимости от локализации его браузера.

Чтобы интернационализировать строки, их нужно указывать следующим образом:

```json
"name": "\_\_MSG\_extensionName\_\_",
"description": "\_\_MSG\_extensionDescription\_\_",
```

Здесь мы получаем сообщения, зависящие от локализации браузера, а не просто статические строки.

Чтобы получить строку сообщения, её нужно указать следующим образом:

1. Два подчёркивания
2. Строка "MSG"
3. Одно подчёркивание
4. Имя сообщения так как оно указано в `messages.json`
5. Два подчёркивания
```

__MSG_ + messageName + __
```

### Локализация по умолчанию

Ещё одно поле. которое нужно указать в manifest.json — это default\_locale (en-US):

```json
"default\_locale": "en"
```

Этот параметр устанавливает локализацию по умолчанию, используемую, если расширение не поддерживает локализацию браузера пользователя. Любые сообщения, недоступные в текущей локализации, будут браться из той локализации, которая установлена по умолчанию. There are some more details to be aware of in terms of how the browser selects strings — see Выбор локализованной строки.

CSS, зависящий от локализации
-----------------------------

Локализованные строки также можно получить из CSS-файлов расширения. Например, вы можете создать поля CSS, зависящие от локализации, так:

```css
header {
  background-image: url(../images/\_\_MSG\_extensionName\_\_/header.png);
}
```

Эта функциональность может быть полезна, однако, возможно, для этих целей стоит использовать Заранее определённые сообщения.

Получение сообщений из JavaScript
---------------------------------

Допустим, вы добавили сообщения в ваш manifest.json. Чтобы ваше расширение начало использовать правильные языки, соответствующие сообщения следует вызывать при помощи JavaScript. API i18n (en-US) достаточно прост и содержит всего 4 основных метода:

* Скорее всего, наиболее часто вы будете использовать `i18n.getMessage()` (en-US) — этот метод используется для получения конкретного сообщения. Примеры его использования можно увидеть ниже.
* Методы `i18n.getAcceptLanguages()` (en-US) и `i18n.getUILanguage()` (en-US) используются, если UI надо менять в зависимости от локализации — например, если вы хотите, чтобы предпочтения, свойственные носителям какого-либо языка, находились выше в списке, или чтобы формат дат соответствовал локализации браузера.
* Метод `i18n.detectLanguage()` (en-US) используется для получения языка информации, введённой пользователем, и её форматирования.

В нашем примере notify-link-clicks-i18n , фоновый скрипт содержит следующие строки:

```js
var title = browser.i18n.getMessage("notificationTitle");
var content = browser.i18n.getMessage("notificationContent", message.url);
```

Первая из них получает поле `notificationTitle message` из доступного файла `messages.json`, соответствующее наиболее подходящей локализации . Вторая строка похожа на первую, но в ней метод принимает URL в качестве второго параметра. Зачем? С помощью этого параметра мы указываем, на что нужно заменить заполнитель `$URL$` в поле `notificationContent message`:

```json
"notificationContent": {
  "message": "You clicked $URL$.",
  "description": "Tells the user which link they clicked.",
  "placeholders": {
    "url" : {
      "content" : "$1",
      "example" : "https://developer.mozilla.org"
    }
  }
}
```

Объект `"placeholders"` определяет все заполнители и то, откуда их нужно получать. Заполнитель `"url"` указывает, что информация о нем должна содержаться в $1 — первое значение, заданное внутри второго параметра `getMessage()`. Поскольку заполнитель называется `"url"`, `$URL$` используется для его вызова внутри сообщения (то есть для заполнителя `"name"` нужно использовать `$NAME$`, и т. д.). Если вы хотите задать значения нескольких заполнителей, их можно передавать во второй аргумент `i18n.getMessage()` (en-US) в виде массива — массив `[a, b, c]`передаёт значения`$1`, `$2`и`$3`, и т. д. внутрь `messages.json`.

Давайте посмотрим на пример: изначально сообщение `notificationContent` в файле `en/messages.json` такое:
```

You clicked $URL$.
```

Пусть эта ссылка указывает на `https://developer.mozilla.org`. После вызова `i18n.getMessage()` (en-US), содержание второго параметра становится доступно в messages.json в качестве значения `$1`, замещающего `$URL$`, так как это указано в заполнителе `"url"`. Таким образом, итоговое значение строки:
```

You clicked https://developer.mozilla.org.
```

### Прямое использование заполнителей

Переменные (`$1`, `$2`, `$3`, и т. д.) можно вставлять напрямую в сообщения. Например, можно переписать объект `"notificationContent"` следующим образом:

```json
"notificationContent": {
  "message": "You clicked $1.",
  "description": "Tells the user which link they clicked."
}
```

Этот метод может показаться более быстрым и простым, но другой способ (использование `"placeholders"`) считается лучшей практикой. Это вызвано тем, что имена заполнителей (например `"url"`) и примеры помогают понять, что означают заполнители — через неделю после написания кода Вы, наверное, забудете, что обозначают заполнители `$1`–`$8`, что менее вероятно, если заполнители именованы.

### Заданные замены

Значения заполнителей можно задавать вручную, если вы хотите, чтобы каждый раз это значение было одним и тем же, а не определялось переменной в коде. Например:

```json
"mdn\_banner": {
  "message": "For more information on web technologies, go to $MDN$.",
  "description": "Tell the user about MDN",
  "placeholders": {
    "mdn": {
      "content": "https://developer.mozilla.org/"
    }
  }
}
```

В этом примере мы сами задаём значение заполнителя, а не получаем его из переменной, такой как `$1`. Это может быть полезно, если сообщение очень сложное, и вы хотите разделить значения, чтобы сделать строки более читаемыми. К тому же, доступ к этим значениям можно получить внутри программы.

Вы также можете использовать такие замены для указания частей строки, не нуждающихся в переводе, таких как имена или названия.

Выбор локализованной строки
---------------------------

Локализации могут быть указаны с помощью кода языка, например `fr` или `en`. Они также могут содержать региональный код, например `en_US` или `en_GB`, описывающий региональный вариант языка. Когда вы запрашиваете строку у системы i18n, системы возвращает её используя следующий алгоритм:

1. Если для текущей локализации существует файл `messages.json`, содержащий требуемую строку, возвращается она.
2. Иначе,если текущая локализация — региональный вариант (например `en_US`) и существует файл `messages.json` для этого языка, но без указания региона (например `en`), содержащий строку, возвращается она.
3. Иначе, если существует файл `messages.json` для `default_locale`, указанной в `manifest.json`, и этот файл содержит нужную строку, возвращается она.
4. В противном случае возвращается пустая строка.

Рассмотрим следующий пример:

* корневая-директория-расширения/
    + \_locales
        - en\_GB
            * messages.json
                + `{ "colorLocalised": { "message": "colour", "description": "Color." }, ... }`en
            * messages.json
                + `{ "colorLocalised": { "message": "color", "description": "Color." }, ... }`
        - fr
            * messages.json
                + `{ "colorLocalised": { "message": "couleur", "description": "Color." }, ...}`

Пусть `default_locale` установлен как `fr`, а текущая локализация браузера — `en_GB`:

* Вызов `getMessage("colorLocalised")` вернёт "colour".
* Если бы в `en_GB` не было "colorLocalized", то вызов `getMessage("colorLocalised")`, вернул бы "color", а не "couleur".
Заранее определённые сообщения
------------------------------

Модуль i18n module предоставляет заранее определённые сообщения, которые можно вызвать таким же образом, как мы это делали в разделе Интернационализация manifest.json. Например:
```

__MSG_extensionName__
```

Заранее определённые сообщения используют такой же синтаксис, за исключением `@@` перед именем сообщения, например:
```

__MSG_@@ui_locale__
```

Следующая таблица содержит различные заранее определённые сообщения:

| Message name | Description |
| --- | --- |
| `@@extension_id` | Внутренний UUID расширения. Эту строку можно использовать для создания URL ресурсов внутри расширения.Даже нелокализованные расширения могут использовать это сообщения.Это сообщения нельзя использовать в manifest.json.Также стоит заметить, что этот ID — *не* ID аддона, которое возвращает `runtime.id` (en-US), и которое может быть установлено с помощью ключа applications (en-US) в manifest.json. Это сгенерированный UUID, содержащийся в URL аддона. Это означает, что данную величину нельзя использовать в качестве параметра `extensionId` метода `runtime.sendMessage()` (en-US), или для проверки поля `id` объекта `runtime.MessageSender` (en-US). |
| `@@ui_locale` | Текущая локализация; эту строку можно использовать для создания URL, зависящих от локализации. |
| `@@bidi_dir` | Направления чтения, либо "ltr" для языков, таких как английский, где текст читается слева направо, либо "rtl" для языков, считающихся справа налево, таких как арабский. |
| `@@bidi_reversed_dir` | Если `@@bidi_dir` имеет значение "ltr", то возвращает "rtl"; иначе "ltr". |
| `@@bidi_start_edge` | Если `@@bidi_dir` имеет значение "ltr", то возвращает "left"; иначе "right". |
| `@@bidi_end_edge` | Если `@@bidi_dir` имеет значение "ltr", то возвращает "right"; иначе "left". |

Возвращаясь к нашему примеру, лучше было бы написать:

```css
header {
  background-image: url(../images/\_\_MSG\_@@ui\_locale\_\_/header.png);
}
```

Теперь мы можем хранить изображения в директориях поддерживаемых локализаций — en, de, и т. д. — что выглядит логичней.

Давайте рассмотрим пример использования сообщений `@@bidi_*` в файле CSS:

```css
body {
  direction: __MSG_@@bidi\_dir\_\_;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi\_start\_edge\_\_: 0;
  padding-__MSG_@@bidi\_end\_edge\_\_: 1.5em;
  position: relative;
}
```

Для языков, в которых текст читается слева направо, таких как английский, правила CSS, использующие заранее определённые сообщения, сверху задают такие значения:

```css
direction: ltr;
padding-left: 0;
padding-right: 1.5em;
```

Для языков, читающихся справа налево, значения будут следующими:

```css
direction: rtl;
padding-right: 0;
padding-left: 1.5em;
```

Тестирование расширения
-----------------------

Начиная с Firefox 45, расширения могут быть временно установлены с диска — подробнее об этом написано в статье Loading from disk. Сделайте это и попробуйте протестировать наше расширение notify-link-clicks-i18n. Перейдите на одну из ваших любимых страниц и нажмите на ссылку, чтобы проверить, появляется ли сообщения, содержащее URL нажатой ссылки.

Затем измените локализацию Firefox на какую-либо поддерживающуюся расширением, которое вы хотите протестировать.

1. Откройте "about:config" в Firefox, и найдите параметр `intl.locale.requested` (обратите внимание на версию Firefox: в версиях до Firefox 59 этот параметр называется `general.useragent.locale`).
2. Если параметр существует, нажмите на него дважды (или нажмите Return/Enter), чтобы выбрать его, введите языковой код локализации, которую вы хотите протестировать и нажмите "OK" (или Return/Enter). Например, в нашем примере расширение поддерживает "en" (английский), "de" (немецкий), "nl" (голландский), and "ja" (японский). Вы также можете указать пустую строку (`""`) в качестве значения. В этом случае браузер выберет язык вашей ОС по умолчанию.
3. Если параметр `intl.locale.requested` не существует, нажмите правой кнопкой мыши на список параметров (или откройте контекстное меню при помощи клавиатуры), и выберите "New", а затем "String". Введите `intl.locale.requested` как имя настройки и, "de", "nl", и т. д. как значение, как это описано в шаге 2.
4. Найдите `intl.locale.matchOS` и, если параметр существует и равен `true`, дважды нажмите на него и установите на `false`.
5. Перезапустите браузер, чтобы изменения вступили в силу.

**Примечание:** Этот метод работает, даже если у вас не установлен языковой пакет для выбранного языка. В этом случае UI браузера просто будет использовать ваш язык по умолчанию.

**Примечание:** Чтобы изменить результат `getUILanguage` требуется языковой пакет, поскольку он отражает язык UI браузера, а не язык сообщений расширения.

Ещё раз загрузите расширение с диска и протестируйте локализацию:

* Ещё раз откройте "about:addons" — теперь вы должны увидеть ваше расширение, его иконку, имя и описание на выбранном языке.
* Ещё раз протестируйте расширение. Для нашего примера, вам следовало бы посетить другую страницу и, нажав на ссылку, проверить, появляется ли сообщение на нужном языке.


Веб Запрос - Mozilla

Веб Запрос
==========

Добавляет обработчики событий на различных стадиях HTTP запроса. Обработчик получить детальную информацию о запросе и способен изменить или отменить запрос.

Каждое событие запущено на определённой стадии запроса. Типичный порядок событий такой:
 ![](/ru/docs/Mozilla/Add-ons/WebExtensions/API/webRequest/webrequest-flow.png)

`onErrorOccurred` (en-US) Может быть запущен в любой момент во время запроса. Чреда событий может отличаться от приведённой выше: например, в Firefox, после HSTS обновления, событие `onBeforeRedirect` будет запущено сразу же после `onBeforeRequest`.

Все события, кроме `onErrorOccurred`, могут принимать три аргумента в `addListener()`:

* сам обработчик
* объект `filter` (en-US) , который позволяет получать оповещения о запросах, сделанных к определённым URL или определённым типам ресурсов.
* необязательный объект `extraInfoSpec` . Может быть использован для передачи дополнительных специфических для события инструкций.

Функции - обработчику передаётся объект `details` который содержит информацию о запросе. Она содержит ID запроса, который обеспечен для включения надстройки, которая позволяет соотносить события, ассоциируемые с одним запросом. Это уникально в пределах сессии и контекста надстройки. Информация остаётся одинаковой везде на протяжении запроса, даже при перенаправлениях и обменах аутентификации.

Для использования webRequest API для определённого хоста, расширение должно иметь "webRequest" API permission и host permission для этого хоста. Для использования возможности "блокирования" расширение должно также иметь "webRequestBlocking" API разрешение.

Для перехвата ресурсов, загруженных страницей (таких как картинки, скрипты или таблицы стилей), расширение должно иметь разрешение хоста для ресурса также как и для главной страницы, запрашивающей ресурс. К примеру, если страница на `https://developer.mozilla.org` загружает картинку из `https://mdn.mozillademos.org`, тогда расширение должно иметь разрешения обоих хостов чтобы перехватить запрос картинки.

Модифицирование заголовков
--------------------------

Используя некоторые из этих событий, вы можете модифицировать запрос. Конкретно, вы можете:

* отменить запрос в:
    + `onBeforeRequest` (en-US)
    + `onBeforeSendHeaders` (en-US)
    + `onAuthRequired` (en-US)
* перенаправить запрос в:
    + `onBeforeRequest` (en-US)
    + `onHeadersReceived` (en-US)
* модифицировать заголовки запроса в:
    + `onBeforeSendHeaders` (en-US)
* модифицировать заголовки ответа в:
    + `onHeadersReceived` (en-US)
* предоставить учётные данные аутентификации в:
    + `onAuthRequired` (en-US)

Чтобы сделать это, вам необходимо передать опцию со значением "blocking" в аргументе `extraInfoSpec` к `addListener()`. Это делает обработчик синхронным. В обработчике, вы можете тогда возвратить объект `BlockingResponse` (en-US) который индикует модификацию, какую вам нужно сделать: например, модифицированный заголовок запроса который вы хотите отправить.

Доступ к информации о безопасности
----------------------------------

В обработчике `onHeadersReceived` (en-US) вы имеете доступ к TLS свойствам запроса через вызов `getSecurityInfo()` (en-US). Чтобы сделать это, вы должны также передать "blocking" в `extraInfoSpec` аргументе к `addListener()` события.

Вы можете прочитать детали TLS хэндшейка, но не можете модифицировать их или перезаписать решения доверы браузера.

Modifying responses
-------------------

Для того, чтобы модифицировать тело HTTP ответа на запрос, вызовите `webRequest.filterResponseData` (en-US), и передайте ID запроса. Это возвратит объект `webRequest.StreamFilter` (en-US) который вы сможете использовать чтобы исследовать и изменять данные когда они получены браузером.

Чтобы сделать это, у вас должно быть "webRequestBlocking" API разрешение, а также "webRequest" API permission и host permission от соответствующего хоста.

Types
-----

`webRequest.BlockingResponse` (en-US)

An object of this type is returned by event listeners that have set `"blocking"` in their `extraInfoSpec` argument. By setting particular properties in `BlockingResponse`, the listener can modify network requests.

`webRequest.CertificateInfo` (en-US)

An object describing a single X.509 certificate.

`webRequest.HttpHeaders` (en-US)

An array of HTTP headers. Each header is represented as an object with two properties: `name` and either `value` or `binaryValue`.

`webRequest.RequestFilter` (en-US)

An object describing filters to apply to webRequest events.

`webRequest.ResourceType` (en-US)

Represents a particular kind of resource fetched in a web request.

`webRequest.SecurityInfo` (en-US)

An object describing the security properties of a particular web request.

`webRequest.StreamFilter` (en-US)

An object that can be used to monitor and modify HTTP responses while they are being received.

`webRequest.UploadData` (en-US)

Contains data uploaded in a URL request.

Properties
----------

`webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES` (en-US)

The maximum number of times that `handlerBehaviorChanged()` (en-US) can be called in a 10 minute period.

Functions
---------

`webRequest.handlerBehaviorChanged()` (en-US)

This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.

`webRequest.filterResponseData()` (en-US)

Returns a `webRequest.StreamFilter` (en-US) object for a given request.

`webRequest.getSecurityInfo()` (en-US)

Gets detailed information about the TLS connection associated with a given request.

Events
------

`webRequest.onBeforeRequest` (en-US)

Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.

`webRequest.onBeforeSendHeaders` (en-US)

Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.

`webRequest.onSendHeaders` (en-US)

Fired just before sending headers. If your add-on or some other add-on modified headers in ``onBeforeSendHeaders` (en-US)`, you'll see the modified version here.

`webRequest.onHeadersReceived` (en-US)

Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.

`webRequest.onAuthRequired` (en-US)

Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.

`webRequest.onResponseStarted` (en-US)

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

`webRequest.onBeforeRedirect` (en-US)

Fired when a server-initiated redirect is about to occur.

`webRequest.onCompleted` (en-US)

Fired when a request is completed.

`webRequest.onErrorOccurred` (en-US)

Fired when an error occurs.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Extra notes on Chrome incompatibilities.

Example extensions
------------------

* http-response
* root-cert-stats
* stored-credentials
* user-agent-rewriter

**Примечание:** Это API основано на API Chromium `chrome.webRequest`. Эта документация основана на `web_request.json` из кода Chromium.


downloads - Mozilla

downloads
=========

Позволяет расширениям взаимодействовать с менеджером загрузки браузера. Этот модуль API можно использовать для загрузки, отмены, приостановки, возобновления загрузки файлов и отображения загруженных файлов в файловом менеджере.

Для использования этого API вам необходимо указать "downloads" API permission в вашем manifest.json файле.

Types
-----

`downloads.FilenameConflictAction` (en-US)

Определяет действия в случае, если имя загружаемого файла конфликтует с именем существующего файла.

`downloads.InterruptReason` (en-US)

Defines a set of possible reasons why a download was interrupted.

`downloads.DangerType` (en-US)

Defines a set of common warnings of possible dangers associated with downloadable files.

`downloads.State` (en-US)

Defines different states that a current download can be in.

`downloads.DownloadItem` (en-US)

Represents a downloaded file.

`downloads.StringDelta` (en-US)

Represents the difference between two strings.

`downloads.DoubleDelta` (en-US)

Represents the difference between two doubles.

`downloads.BooleanDelta` (en-US)

Represents the difference between two booleans.

`downloads.DownloadTime` (en-US)

Represents the time a download took to complete.

`downloads.DownloadQuery` (en-US)

Defines a set of parameters that can be used to search the downloads manager for a specific set of downloads.

Functions
---------

`downloads.download()` (en-US)

Downloads a file, given its URL and other optional preferences.

`downloads.search()` (en-US)

Queries the `DownloadItems` (en-US) available in the browser's downloads manager, and returns those that match the specified search criteria.

`downloads.pause()` (en-US)

Pauses a download.

`downloads.resume()` (en-US)

Resumes a paused download.

`downloads.cancel()` (en-US)

Cancels a download.

`downloads.getFileIcon()` (en-US)

Retrieves an icon for the specified download.

`downloads.open()` (en-US)

Opens the downloaded file with its associated application.

`downloads.show()` (en-US)

Opens the platform's file manager application to show the downloaded file in its containing folder.

`downloads.showDefaultFolder()` (en-US)

Opens the platform's file manager application to show the default downloads folder.

`downloads.erase()` (en-US)

Erases matching `DownloadItems` (en-US) from the browser's download history, without deleting the downloaded files from disk.

`downloads.removeFile()` (en-US)

Removes a downloaded file from disk, but not from the browser's download history.

`downloads.acceptDanger()` (en-US)

Prompts the user to accept or cancel a dangerous download.

`downloads.drag()`

Initiates dragging the downloaded file to another application.

`downloads.setShelfEnabled()` (en-US)

Enables or disables the gray shelf at the bottom of every window associated with the current browser profile. The shelf will be disabled as long as at least one extension has disabled it.

Events
------

`downloads.onCreated` (en-US)

Fires with the `DownloadItem` (en-US) object when a download begins.

`downloads.onErased` (en-US)

Fires with the `downloadId` when a download is erased from history.

`downloads.onChanged` (en-US)

When any of a `DownloadItem` (en-US)'s properties except `bytesReceived` changes, this event fires with the `downloadId` and an object containing the properties that changed.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* latest-download

**Примечание:** Это API основано на API Chromium `chrome.downloads`.


windows - Mozilla

windows
=======

Взаимодействие с окнами браузера. Вы можете использовать этот API, чтобы получить информацию об открытых окнах, а также открывать, изменять и закрывать окна. Вы также можете обрабатывать события открытия, закрытия окна, и активировать события.

Types
-----

`windows.WindowType` (en-US)

Тип окна браузера.

`windows.WindowState` (en-US)

Состояние окна браузера.

`windows.Window` (en-US)

Информация об окне браузера.

`windows.CreateType`

Specifies the type of browser window to create.

Properties
----------

`windows.WINDOW_ID_NONE` (en-US)

The `windowId` value that represents the absence of a browser window.

`windows.WINDOW_ID_CURRENT` (en-US)

The `windowId` value that represents the current window.

Functions
---------

`windows.get()` (en-US)

Gets details about a window, given its ID.

`windows.getCurrent()` (en-US)

Gets the current window.

`windows.getLastFocused()` (en-US)

Gets the window that was most recently focused — typically the window 'on top'.

`windows.getAll()` (en-US)

Gets all windows.

`windows.create()` (en-US)

Creates a new window.

`windows.update()` (en-US)

Updates the properties of a window. Use this to move, resize, and (un)focus a window, etc.

`windows.remove()` (en-US)

Closes a window, and all its tabs.

Events
------

`windows.onCreated` (en-US)

Fired when a window is created.

`windows.onRemoved` (en-US)

Fired when a window is closed.

`windows.onFocusChanged` (en-US)

Fired when the currently focused window changes.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* annotate-page
* bookmark-it
* private-browsing-theme
* store-collected-images
* theme-integrated-sidebar
* window-manipulator

**Примечание:** Это API основано на API Chromium `chrome.windows`. Эта документация основана на `windows.json` из кода Chromium.

Информация о совместимости Microsoft Edge предоставлена корпорацией Microsoft и включена здесь под лицензией Creative Commons Attribution 3.0 United States License.


cookies - Mozilla

cookies
=======

Позволяет расширениям получать и устанавливать куки, а также сообщать об их изменении.

Для использования этого API,вам нужно предоставить доступ API permission в вашем файле manifest.json,а также host permissions для тех сайтов чьи куки вам нужны для доступа.Смотрите cookie Permissions.

Types
-----

`cookies.Cookie`

Предоставляет информацию о HTTP cookie

`cookies.CookieStore` (en-US)

Represents a cookie store in the browser.

`cookies.OnChangedCause` (en-US)

Represents the reason a cookie changed.

Methods
-------

`cookies.get()` (en-US)

Запрашивает информацию об одном кукис.

`cookies.getAll()` (en-US)

Выдаёт все кукис которые подходят установленному фильтру.

`cookies.set()` (en-US)

Устанавливает кукис с заданной информацией;в том случае если подобный кукис был информация будет перезаписана.

`cookies.remove()` (en-US)

Удаляет кукис по имени.

`cookies.getAllCookieStores()` (en-US)

Список всех существующих куки

Event handlers
--------------

`cookies.onChanged` (en-US)

Происходит когда кукис задаётся или меняется.

Permissions
-----------

In order to use this API, an add-on must specify the "cookies" API permission in its manifest, along with host permissions for any sites for which it wishes to access cookies. The add-on may read or write any cookies which could be read or written by a URL matching the host permissions. For example:

`http://*.example.com/`

An add-on with this host permission may:

* Read a non-secure cookie for `www.example.com`, with any path.
* Write a secure or non-secure cookie for `www.example.com`, with any path.

It may *not*:

* Read a secure cookie for `www.example.com`.

`http://www.example.com/`

An add-on with this host permission may:

* Read a non-secure cookie for `www.example.com`, with any path.
* Read a non-secure cookie for `.example.com`, with any path.
* Write a secure or non-secure cookie for `www.example.com` with any path.
* Write a secure or non-secure cookie for `.example.com` with any path.

It may *not*:

* Read or write a cookie for `foo.example.com`.
* Read or write a cookie for `foo.www.example.com`.

`*://*.example.com/`

An add-on with this host permission may:

* Read or write a secure or non-secure cookie for `www.example.com` with any path.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* cookie-bg-picker
* list-cookies

**Примечание:** Это API основано на API Chromium `chrome.cookies`. Эта документация основана на `cookies.json` из кода Chromium.


cookies.Cookie - Mozilla

cookies.Cookie
==============

Тип `Cookie` из `cookies` API представляет собой информацию о HTTP cookie.

Тип
---

Значения этого типа - объекты, которые могут содержать следующие свойства:

`name`

`string` - содержит имя cookie.

`value`

`string` - содержит значение cookie.

`domain`

`string` - содержит домен, которому принадлежит cookie (например, "www.google.com", "example.com").

`hostOnly`

`boolean` - `true` если cookie является host-only (то есть запрашивающий хост должен в точности совпадать с доменом cookie), в ином случае `false`.

`path`

`string` - содержит path cookie.

`secure`

`boolean` - `true`, если cookie помечен как secure (то есть его область действия ограничена безопасными каналами, обычно HTTPS), в ином случае `false`.

`httpOnly`

`boolean` - `true` если cookie помечен как HttpOnly (то есть он недоступен для клиентских скриптов), иначе `false`.

`session`

`boolean` - `true` если cookie является сессионным, `false` если cookie является постоянным с указанным временем жизни.

`expirationDate`Необязательный

`number` - содержит срок годности cookie, который представляется количеством секунд с начала UNIX-эры. Отсутствует для сессионных cookie.

`storeId`

`string` - представляет собой ID хранилища, в котором хранится данный cookie, как указано в соответствии с `cookies.getAllCookieStores()` (en-US).

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Примеры
-------

В большинстве методов из cookies API объекты типа `Cookie` используются как входные параметры методов, либо же как возвращаемые значения. К примеру, вызов `cookies.getAll()` (en-US) возвращает массив объектов типа `Cookie`.

В примере ниже мы запрашиваем все cookie, а затем выводим в лог некоторые из полей полученных `Cookie` объектов:

```js
function logCookies(cookies) {
  for (cookie of cookies) {
    console.log(`Domain: ${cookie.domain}`);
    console.log(`Name: ${cookie.name}`);
    console.log(`Value: ${cookie.value}`);
    console.log(`Persistent: ${!cookie.session}`);
  }
}

var gettingAll = browser.cookies.getAll({});
gettingAll.then(logCookies);
```

**Примечание:** Это API основано на API Chromium `chrome.cookies`. Эта документация основана на `cookies.json` из кода Chromium.


windows.CreateType - Mozilla

windows.CreateType
==================

Определение типа окна браузера для создания.

Тип
---

Значение данного типа `strings`. Возможные значения:

* `"normal"`
* `"popup"`
* `"panel"`
* `"detached_panel"`
Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Примечание:** Это API основано на API Chromium `chrome.windows`. Эта документация основана на `windows.json` из кода Chromium.

Информация о совместимости Microsoft Edge предоставлена корпорацией Microsoft и включена здесь под лицензией Creative Commons Attribution 3.0 United States License.


runtime.getManifest() - Mozilla

runtime.getManifest()
=====================

Получить весь файл manifest.json в виде объекта JavaScript, совместимого с JSON.Синтаксис
---------

```js
browser.runtime.getManifest();
```

### Параметры

Нет.

### Возвращаемое значение

`object` - объект JSON, представляющий манифест.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Примеры
-------

Получить манифест и вывести его свойство "name":

```js
var manifest = browser.runtime.getManifest();
console.log(manifest.name);
```

### Example extensions

* runtime-examples

**Примечание:** Это API основано на API Chromium `chrome.runtime`. Эта документация основана на `runtime.json` из кода Chromium.


tabs.get() - Mozilla

tabs.get()
==========

Получает сведения об указанной вкладке.

Синтаксис
---------

```js
browser.tabs.get(
  tabId,              // integer
  function(tab) {...} // function
)
```

### Параметры

`tabId`

`integer`.

`callback`

`function`. Функция принимает следующие аргументы:

`tab`

`tabs.Tab` (en-US).

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Примеры
-------

### Example extensions

* chill-out

**Примечание:** Этот API основан на Chromium `chrome.tabs` API. Это документация получена из `tabs.json` в коде Chromium.


Кнопка в панели инструментов - Mozilla

Кнопка в панели инструментов
============================

 Кнопка на панели инструментов браузера (оригинальное название browser action (en-US)) - это иконка, которую можно вывести в панель инструментов. Пользователь взаимодействует с расширением нажимая на неё как на кнопку.

 ![](/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Toolbar_button/browser-action.png)

Кнопка на панели инструментов одинаково отображается для любой открытой вкладки. Это предполагает, что расширение единообразно работает со всеми страницами.

Например, предустановленная кнопка "обновить" перезагружает любую страницу в активной вкладке, кнопка "добавить в избранное" добавляет любой адрес активной вкладки в список избранного. Кнопка загрузок показывает единый для всего браузера список скачанных файлов, независимо от того что за страница открыта в активной вкладке.

Применимые лишь к определённым страницам кнопки следует реализовывать с помощью кнопки в адресной строке (page action (en-US)).

Объявление в manifest.json
--------------------------

За кнопку на панели инструментов отвечает свойство манифеста `browser_action` (en-US):

```json
"browser\_action": {
  "default\_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default\_title": "Whereami?"
}
```

Свойство кнопки `default_icon` обязательно, оно определяет внешний вид кнопки - иконку, которая окажется на панели инструментов.

Расширение может иметь только одну кнопку для панели инструментов.

Возможны два способа реакции на нажатие кнопки: отображение всплывающего окна (описано в отдельном разделе) или отправка события в background script расширения. В таком случае реакция на нажатие обеспечивают обработчики событий, подключённые к `browserAction.onClicked` (en-US):

```js
browser.browserAction.onClicked.addListener(handleClick);
```

Если же указать в качестве реакции на нажатие всплывающее окно, то событие передано не будет. Вместо этого около кнопки отобразится всплывающее окно - отдельная маленькая страница, дальнейшее взаимодействие с пользователем берёт на себя она. Подробнее этот сценарий описан на отдельной странице, посвящённой всплывающим окнам.

Все свойства кнопки на панели инструментов можно изменить программно через API `browserAction` (en-US).

Примеры
-------

В GitHub репозитории webextensions-examples представлены несколько примеров расширений, которые создают кнопку на панели инструментов:

* bookmark-it использует событие browserAction.onClicked.
* beastify открывает всплывающее окно.


Боковые панели (Sidebars) - Mozilla

Боковые панели (Sidebars)
=========================

Боковая панель - это панель, которая отображается в левой части окна браузера, рядом с веб-страницей. В браузере предусмотрен пользовательский интерфейс, который позволяет пользователю видеть доступные боковые панели и выбирать боковую панель для отображения. Например, Firefox имеет меню "Вид > Боковая панель". Одновременно может отображаться только одна боковая панель, и эта боковая панель будет отображаться для всех вкладок и всех окон браузера.

Браузер может включать в себя ряд встроенных боковых панелей. Например, Firefox включает боковую панель для взаимодействия с закладками:

![](/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars/bookmarks-sidebar.png)Используя ключ `sidebar_action` в manifest.json, расширение может добавить свою боковую панель в браузер. Она будет доступна наравне со встроенными панелями, и пользователь сможет открыть её, используя тот же механизм, что и для встроенных боковых панелей.

Как и в случае всплывающих окон (Popups), вы задаёте содержимое боковой панели как документ HTML. Когда пользователь открывает боковую панель, этот документ загружается в каждое открытое окно браузера. Каждое окно получает свой экземпляр документа. Когда открываются новые окна, они также получат свои собственные экземпляры документа боковой панели.

Вы можете задать HTML документ для конкретной вкладки, используя функцию `sidebarAction.setPanel()` (en-US). Боковая панель может определить, к какому окну она принадлежит используя `windows.getCurrent()` (en-US) API:

```js
// sidebar.js
browser.windows.getCurrent({ populate: true }).then((windowInfo) => {
  myWindowId = windowInfo.id;
});
```

Это полезно, если боковая панель хочет отображать различный контент для разных окон. Использование такого подхода см. в примере "annotate-page" example.

HTML документ боковой панели получает доступ к тому же набору привилегированных JavaScript API, что и background и popup сценарии этого расширения. Они могут получить прямой доступ к фоновой странице с помощью `runtime.getBackgroundPage()` (en-US), и могут взаимодействовать с сценариями контента или нативными приложениями, используя API интерфейса обмена сообщениями, такие как `tabs.sendMessage()` (en-US) и `runtime.sendNativeMessage()` (en-US).

Документы боковой панели выгружаются, когда окно браузера закрывается или пользователь закрывает боковую панель. Это означает, что в отличие от background страниц документы боковой панели не остаются загруженными все время, но в отличие от popup окон они остаются загруженными, пока пользователь взаимодействует с веб-страницами.

После первой установки расширения, использующего боковую панель, его панель будет открыта автоматически. Это сделано для того, чтобы помочь пользователю понять, что расширение использует боковую панель. Обратите внимание, что расширение не может открывать боковые панели программно: боковые панели могут открываться только пользователем.

Использование боковых панелей
-----------------------------

Чтобы использовать боковую панель в своём расширении, укажите с помощью ключа `sidebar_action` в manifest.json key, HTML-документ панели, а также заголовок и значок по умолчанию:

```json
"sidebar\_action": {
  "default\_title": "My sidebar",
  "default\_panel": "sidebar.html",
  "default\_icon": "sidebar\_icon.png"
}
```

Вы можете изменить название и значок панели программно, используя `sidebarAction` (en-US) API.

Заголовок и значок отображаются пользователю в любом UI, предоставляемом браузером, для отображения боковых панелей, например меню "Вид > Боковые панели" в Firefox.

Примеры
-------

В репозитории webextensions-examples на GitHub содержится несколько примеров расширений, которые используют боковую панель:

* annotate-page использует боковую панель.


Страницы расширения - Mozilla

Страницы расширения
===================

В расширение можно добавить HTML-страницы, чтобы предоставить пользователю формы, помощь или другое необходимое содержимое.

![Example of a simple bundled page displayed as a detached panel.](/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages/bundled_page_as_panel_small.png)

Эти страницы получат доступ к привилегированным средствам JavaScript API — таким же как те, что доступны фоновым скриптам расширения. Но каждая из них будет открыта в своей отдельной вкладке — со своей очередью задач JavaScript, своими глобальными переменными и т. д.

Фоновую страницу можно считать "невидимой страницей расширения".

Определение страниц расширения
------------------------------

К расширению можно подключить файлы HTML и используемые в них файлы CSS и JavaScript. Можно расположить все эти файлы в корне папки расширения, а можно организовать более сложную структуру каталога.
```

/my-extension
    /manifest.json
    /my-page.html
    /my-page.js
```

Отображение страниц расширения
------------------------------

Есть два способа отобразить страницу расширения: `windows.create()` (en-US) и `tabs.create()` (en-US).

Например для того, чтобы создать окно сообщения, можно с помощью функции `windows.create()` открыть страницу HTML в отсоединённой панели (detached panel) — в окне без строки адреса, полосы закладок и других обычных элементов управления:

```js
let createData = {
  type: "detached\_panel",
  url: "panel.html",
  width: 250,
  height: 100,
};
let creating = browser.windows.create(createData);
```

Когда окно больше не будет нужно, его можно закрыть программно.

Например, когда пользователь нажмёт на кнопку, можно вызвать функцию `windows.remove()` (en-US) и передать ей идентификатор текущего окна:

```js
document.getElementById("closeme").addEventListener("click", function () {
  let winId = browser.windows.WINDOW\_ID\_CURRENT;
  let removing = browser.windows.remove(winId);
});
```

Страницы расширения и история
-----------------------------

По умолчанию страницы, открытые таким образом, будут сохранены в истории браузера — точно так же, как и обычные веб-страницы. Если такое поведение не нужно, используйте `history.deleteUrl()` (en-US), чтобы удалить запись:

```js
function onVisited(historyItem) {
  if (historyItem.url == browser.extension.getURL(myPage)) {
    browser.history.deleteUrl({ url: historyItem.url });
  }
}

browser.history.onVisited.addListener(onVisited);
```

Для использования API истории браузера нужно добавить разрешение "`history`" с помощью элемента permissions в файле `manifest.json`.

Дизайн веб-страницы
-------------------

Подробности о том, как сделать, чтобы дизайн ваших страниц совпадал со стилем Firefox, смотрите на сайте Система дизайна Photon (на английском языке) и в документации browser styles (en-US).

Примеры
-------

В репозитории webextensions-examples на GitHub есть пример window-manipulator, в котором используются некоторые из возможностей для создания окон.


Уведомления - Mozilla

Уведомления
===========

Уведомления позволяют вам передавать информацию пользователям вашего расширения через службу уведомлений в операционной системе.

![](/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications/notify-shadowed.png)

Уведомления могут включать в себя призывы к выполнению каких-либо действий, а ваше расширение может обрабатывать события закрытия или нажатия на уведомления.

Управление уведомлениями
------------------------

Управление уведомлениями происходит программным путём с помощью `notifications` (en-US) API. Для использования этого API вы должны иметь `notifications` полномочия в manifest.json:

```json
"permissions": ["notifications"]
```

После этого вы можете использовать `notifications.create` (en-US) для создания ваших уведомлений, как, например, в нижеприведённом коде, взятом из notify-link-clicks-i18n:

```js
var title = browser.i18n.getMessage("notificationTitle");
var content = browser.i18n.getMessage("notificationContent", message.url);
browser.notifications.create({
  type: "basic",
  iconUrl: browser.extension.getURL("icons/link-48.png"),
  title: title,
  message: content,
});
```

Этот код создаёт уведомление с иконкой, заголовком и сообщением.

Если уведомление имеет цель призвать пользователя к какому-либо действию, вы можете установить обработчик события на нажатия на уведомления:

```js
browser.notifications.onClicked.addListener(handleClick);
```

Если вы собираетесь призывать пользователей к действиям с помощью уведомлений, вам так же будет полезно определять `id` этих уведомлений, для того чтобы вы в дальнейшем имели возможность различать на какое конкретно уведомление было произведено нажатие.

Иконки
------

Смотрите статью Iconography в документации Photon Design System для получения информации по созданию иконок для уведомлений.

Примеры
-------

Репозиторий образцов расширений webextensions-examples на GitHub включает в себя расширение notify-link-clicks-i18n, которое реализует систему уведомлений.


Адресная строка - Mozilla

Адресная строка
===============

Используя `omnibox` (en-US) API, расширения могут взаимодействовать с адресной строкой и заполнять её выпадающий список предложений своими значениями, после введения пользователем определённого ключевого слова.

![Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions.](/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox/omnibox_example_small.png)

Это могло бы позволить вам написать расширение, которое, например, искало бы бесплатные книги в электронной библиотеке, или как в примере выше, строки кода из репозитория.

Настраивание взаимодействия с адресной строкой
----------------------------------------------

Чтобы получить возможность взаимодействия с адресной строкой, вам необходимо добавить ключ omnibox (en-US) в manifest.json файл, и присвоить ему значение в виде объекта, определяющего ключевое слово, после введения которого расширение активирует взаимодействие:

```json
  "omnibox": { "keyword" : "cs" }
```

При желании, используя метод `omnibox.setDefaultSuggestion()` (en-US), вы можете изменить текст изначального предложения, которое всегда будет появляться первым в списке предложений адресной строки. Как вариант, оно может быть использовано для описания предоставляемой расширением функциональности:

```js
browser.omnibox.setDefaultSuggestion({
  description: `Искать в кодовой базе firefox
 (пример: "hello world" | "path:omnibox.js onInputChanged")`,
});
```

Далее, вы можете зарегистрировать обработчики на событие `omnibox.onInputStarted` (en-US), которое будет распространяться после введения пользователем ключевого слова и нажатия на пробел, и на событие `omnibox.onInputChanged` (en-US), которое будет распространяться при изменении пользователем строки адреса. Так же, с помощью обработчика события `omnibox.onInputChanged` (en-US), вы будете иметь возможность заполнять выпадающий список своими предложениями. К примеру, в случае поиска кода на сайте https://searchfox.org/mozilla-central, используя введённые пользователем слова:

```js
browser.omnibox.onInputChanged.addListener((text, addSuggestions) => {
  let headers = new Headers({ Accept: "application/json" });
  let init = { method: "GET", headers };
  let url = buildSearchURL(text);
  let request = new Request(url, init);

  fetch(request).then(createSuggestionsFromResponse).then(addSuggestions);
});
```

Заметьте, что изначальное предложение в любом случае будет оставаться первым в выпадающем списке.

Чтобы обрабатывать нажатия пользователя на предложения из выпадающего списка, подпишитесь на событие `omnibox.onInputEntered` (en-US). При нажатии на изначальное предложение в функцию обработчика будет передана набранная в данный момент строка адреса, во всех остальных случаях будет передаваться значение из выбранного предложения. Вторым аргументом в функцию обработчика будет передана информация из настроек браузера о том, каким образом пользователь предпочитает открывать новые ссылки. Например, в нижерасположенном коде, нажатие на изначальное предложение запустит поиск, тогда как нажатие на все остальные предложения просто откроет определённые них URL:

```js
browser.omnibox.onInputEntered.addListener((text, disposition) => {
  let url = text;
  if (!text.startsWith(SOURCE\_URL)) {
    // Обновить url, если пользователь нажал на изначальное предложение.
    url = `${SEARCH\_URL}?q=${text}`;
  }
  switch (disposition) {
    case "currentTab":
      browser.tabs.update({ url });
      break;
    case "newForegroundTab":
      browser.tabs.create({ url });
      break;
    case "newBackgroundTab":
      browser.tabs.create({ url, active: false });
      break;
  }
});
```

Примеры
-------

Репозиторий образцов расширений webextensions-examples на GitHub включает в себя расширение firefox-code-search, демонстрирующее взаимодействие с адресной строкой.


Контекстное меню - Mozilla

Контекстное меню
================

Эта возможность пользовательского интерфейса позволяет добавлять новые элементы в контекстное меню браузера, появляющееся при нажатии правой кнопки мыши. Вкладки браузера также имеют контекстное меню доступное через browser.menus API.

![Example of content menu items added by a WebExtension, from the context-menu-demo example](/ru/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items/context_menu_example.png)

Возможность добавления элементов в контекстное меню позволяет предоставлять пользователю различные функции в зависимости от его действий на странице или в браузере. Например, можно отобразить элемент, который открывает графический редактор, если пользователь нажимает на изображение, или же предложить функцию для сохранения содержимого страницы, если выбрана некоторая её часть. Элементы могут представлять из себя не только текст, но и, например, кнопку-переключатель или разделитель (см. типы элементов меню (en-US)). После того, как элемент контекстного меню был добавлен с помощью `contextMenus.create` (en-US), он отображается во всех вкладках браузера, но вы можете удалить его при помощи `contextMenus.remove` (en-US).

Создание элементов контекстного меню
------------------------------------

Управление элементами контекстного меню осуществляется с помощью `contextMenus` (en-US) API. Однако, вам необходимо указать разрешение `contextMenus` в manifest.json, чтобы им воспользоваться.

```json
"permissions": ["contextMenus"]
```

Затем вы сможете добавлять, обновлять и удалять элементы контекстного меню в фоновом сценарии вашего расширения. Для создания элемента необходимо указать его id, заголовок и контекст, в котором элемент будет показан. В примере ниже элемент меню появляется, когда выделен текст или какая-либо другая часть страницы:

```js
browser.contextMenus.create(
  {
    id: "log-selection",
    title: browser.i18n.getMessage("contextMenuItemSelectionLogger"),
    contexts: ["selection"],
  },
  onCreated,
);
```

Затем вы можете добавить обработчик события нажатия на элемент. Передаваемая обработчику информация о контексте, в котором произошло нажатие, и о вкладке, где контекстное меню было вызвано, может быть использована вами для определения дальнейшего поведения расширения.

```js
browser.contextMenus.onClicked.addListener(function(info, tab) {
  switch (info.menuItemId) {
    case "log-selection":
      console.log(info.selectionText);
      break;
    ...
  }
})
```

Иконки
------

Чтобы добавить элементам меню иконки, смотрите документацию Iconography в Photon Design System.

Примеры
-------

Репозиторий webextensions-examples на GitHub содержит два примера расширений, в которых реализована работа элементов контекстного меню:

* menu-demo добавляет несколько элементов в контекстное меню;
* context-menu-copy-link-with-types добавляет элемент контекстного меню, который копирует URL ссылки в буфер в виде текста и форматированного HTML.


ключ name - Mozilla

ключ name
=========

|  |  |
| --- | --- |
| Тип | `String` |
| Обязательный | Да |
| Пример |
```json
"name": "My Extension"
```
 |

Имя расширения. Используется для идентификации расширения в интерфейсе браузера и на сайтах, подобных addons.mozilla.org.

Это локализуемое свойство.

Пример
------

```json
"name": "My Extension"
```

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


content_security_policy - Mozilla

content\_security\_policy
=========================

|  |  |
| --- | --- |
| Тип | `Строка` |
| Обязателен | Нет |
| Пример |
```json
"content\_security\_policy": "default-src 'self'"
```
 |

Политика защиты содержимого применяется к расширениям автоматически. Изначальная политика защиты содержимого ограничивает источники, из которых расширение может загружать <script> и <object> (en-US) ресурсы, а так же препятствует потенциально опасным практикам, например использованию `eval()`. Смотрите изначальные правила защиты содержимого, чтобы узнать о конкретных последствиях применения изначальных правил.

Ключ `"content_security_policy"` в manifest.json используется для ослабления или ужесточения политики защиты содержимого. Значения для этого ключа устанавливаются в точно таком же виде, как и для Content-Security-Policy HTTP заголовка. Смотрите Использование политики содержимого для получения общего представления о синтаксисе для написания правил политики.

Примеры использования ключа могут включать в себя:

* Разрешение на загрузку не запакованных в расширение скриптов и объектов, предоставляя их URL в `script-src` (en-US) и `object-src` (en-US) директивах.
* Разрешение на выполнение встраиваемых скриптов, предоставляя hash скрипта в `"script-src"` директиве (en-US).
* Разрешение на использование `eval()` и похожих функций, добавляя `'unsafe-eval'` в `script-src` (en-US) директиву.
* Ограничение допускаемых источников загрузки для других видов контента, например картинок или файлов стилей, используя соответствующие директивы (en-US).

При написании правил по защите содержимого, вы имеете некоторые ограничения:

* Правило должно включать в себя `script-src` (en-US) и `object-src` (en-US) директивы, и `script-src` (en-US) директива должна включать ключевое слово `'self'`.
* Удалённые источники должны иметь `https:` схему.
* Удалённые источники не должны определяться через универсальный символ `*` со следующим за ним доменным публичным суффиксом (например "\*.co.uk" и "\*.blogspot.com" являются не разрешёнными значениями, но "\*.foo.blogspot.com" разрешёно).
* У всех источников должен быть определён хост.
* Единственные позволенные схемы источников: `blob:`, `filesystem:`, `moz-extension:` и `https:`.
* Единственные позволенные ключевые слова (en-US): `'none'`, `'self'` и `'unsafe-eval'`.
Примеры
-------

### Работающие примеры

Разрешает загрузку скриптов из "https://example.com": (*смотрите примечание* 1)

```json
"content\_security\_policy": "script-src 'self' https://example.com; object-src 'self'"
```

Разрешает загрузку скриптов из любого субдомена "jquery.com":

```json
"content\_security\_policy": "script-src 'self' https://\*.jquery.com; object-src 'self'"
```

Разрешает использование `eval()` и его товарищей:

```json
"content\_security\_policy": "script-src 'self' 'unsafe-eval'; object-src 'self';"
```

Разрешает встроить скрипт: `"<script>alert('Hello, world.');</script>"`:

```json
"content\_security\_policy": "script-src 'self' 'sha256-qznLcsROx4GACP2dm0UCKCzCG+HiZ1guq6ZZDob/Tng='; object-src 'self'"
```

Оставляет изначальные правила, но так же требует, чтобы могли загружаться только изображения, запакованные вместе с расширением:

```json
"content\_security\_policy": "script-src 'self'; object-src 'self'; img-src 'self'"
```

Разрешает загрузку только тех ресурсов, которые были запакованы вместе с расширением:

```json
"content\_security\_policy": "default-src 'self'"
```

### Недопустимые примеры

Политика, не включающая `"object-src"` директиву:

```json
"content\_security\_policy": "script-src 'self' https://\*.jquery.com;"
```

Политика, не включающая ключевое слово `"self"` в `"script-src"` директиве:

```json
"content\_security\_policy": "script-src https://\*.jquery.com; object-src 'self'"
```

Использование отличной от `https` схемы для загрузки удалённых ресурсов:

```json
"content\_security\_policy": "script-src 'self' http://code.jquery.com; object-src 'self'"
```

Использование универсального символа в связке с публичным доменным суффиксом:

```json
"content\_security\_policy": "script-src 'self' https://\*.blogspot.com; object-src 'self'"
```

Указание схемы без хоста:

```json
"content\_security\_policy": "script-src 'self' https:; object-src 'self'"
```

Использование неподдерживаемого ключевого слова `'unsafe-inline'`:

```json
"content\_security\_policy": "script-src 'self' 'unsafe-inline'; object-src 'self'"
```

*Примечание: Работающие примеры демонстрируют правильное написание политики защиты содержимого. Тем не менее, расширения с политикой, включающей ключевые словами 'unsafe-eval', 'unsafe-inline', разрешающей загрузку удалённых скриптов и ресурсов, а так же blob файлов не будут допущены к распространению на addons.mozilla.org из-за значительных проблем с безопасностью.*

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


permissions - Mozilla

permissions
===========

|  |  |
| --- | --- |
| Тип | `Массив` |
| Обязателен | Нет |
| Пример |
```json
"permissions": [
  "\*://developer.mozilla.org/\*",
  "webRequest"
]
```
 |

Используйте ключ `permissions` для получения дополнительных возможностей для вашего расширения. Значением ключа является массив строк, каждая из которых представляет собой запрос на какие-либо полномочия.

При объявлении запросов полномочий с помощью этого ключа, браузер проинформирует пользователей, о том какие полномочия необходимы расширению во время его установки, и задаст вопрос, согласны ли они выдать их расширению. Браузер так же даёт пользователям возможность изучить полномочия расширения уже после установки. Так как требование дополнительных полномочий может повлиять на желание пользователя использовать ваше расширение, решение использования конкретной функциональности может стоить тщательного рассмотрения. К примеру, есть смысл избегать запрашивания необязательных полномочий, и предоставлять информацию о том, зачем вашему расширению нужны какие-либо полномочия в описании расширения. Более подробная информация о проблемах, которые вам стоит рассмотреть касательно этой темы, предоставлена в статье Запрашивание правильных полномочий.

Значение ключа может содержать три вида запросов полномочий:

* Запрос на полномочия для хоста
* Запрос на API полномочия
* Запрос на activeTab полномочия
Запрос полномочий для хоста
---------------------------

Запрос на полномочия для хоста объявляется через шаблоны совпадения, где каждый шаблон определяет группу URL, при посещении которых расширение будет иметь эти дополнительные полномочия. Например, запрос на полномочия для хоста может быть задан подобной строкой `"*://developer.mozilla.org/*"`.

Полномочия для хоста включают:

* Возможность выполнять XMLHttpRequest и fetch запросы на ресурсы, которые имеют заданный origin, не испытывая cross-origin ограничений (даже для запросов, выполняемых из встраиваемого скрипта)
* Возможность встраивать скрипты программным путём, используя tabs.executeScript (en-US), на веб-страницах загруженных с заданного origin
* Возможность обрабатывать события из webRequest API для заданных хостов
* Доступ к cookies на заданных хостах, используя cookies API, при условии получения дополнительного "cookies" API полномочия.
* Возможность обходить защиту от слежения, при условии полностью указанного хоста, без использования универсального символа `*`. Не будет работать с `<all_urls>`.

В Firefox, начиная с версии 56, расширения автоматически получают полномочия для своего собственного хоста, который имеет вид:
```

moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/
```

где `60a20a9b-1ad4-af49-9b6c-c64c98c37920` - внутреннее ID расширения. Расширение может получить это URL программным путём, через вызов метода extension.getURL() (en-US):

```js
browser.extension.getURL("");
// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/
```

Запрос на API полномочия
------------------------

Запрос на API полномочия объявляется через ключевые слова, каждое из которых представляет собой название WebExtension API, доступ к которому необходим расширению.

Следующие ключевые слова доступны на данный момент:

* `activeTab`
* `alarms`
* `background`
* `bookmarks`
* `browserSettings`
* `browsingData`
* `clipboardRead`
* `clipboardWrite`
* `contentSettings`
* `contextMenus`
* `contextualIdentities`
* `cookies`
* `debugger`
* `dns`
* `downloads`
* `downloads.open`
* `find`
* `geolocation`
* `history`
* `identity`
* `idle`
* `management`
* `menus`
* `menus.overrideContext`
* `nativeMessaging`
* `notifications`
* `pageCapture`
* `pkcs11`
* `privacy`
* `proxy`
* `search`
* `sessions`
* `storage`
* `tabHide`
* `tabs`
* `theme`
* `topSites`
* `unlimitedStorage`
* `webNavigation`
* `webRequest`
* `webRequestBlocking`

В большинстве случаев полномочие просто делает возможным доступ к определённому API, за исключением следующих ситуаций:

* `tabs` предоставляет доступ к привилегированным частям `tabs` API: `Tab.url`, `Tab.title`, and `Tab.faviconUrl`. В Firefox, вам так же понадобятся `tabs` полномочия, если вы собираетесь использовать `url` ключ в параметре `queryInfo` для `tabs.query()` (en-US) метода. Весь остальной `tabs` API доступен без запрашивания каких-либо полномочий.
* `webRequestBlocking` позволяет вам использовать "blocking" аргумент, для возможности изменять и отменять запросы.
* `downloads.open` позволяет использовать `downloads.open()` (en-US) API.
* `tabHide` позволяет использовать `tabs.hide()` (en-US) API.
Запрос на activeTab полномочия
------------------------------

Этот вид запроса объявляется через ключевое слово `"activeTab"`. `activeTab` полномочия предоставляются расширению на активной в данный момент вкладке, и вступают в эффект только в момент, когда пользователь взаимодействует с расширением.

"Взаимодействие пользователя" включает:

* Пользователь нажимает на кнопку расширения на панели инструментов или адресной строке
* Пользователь взаимодействует с контекстным меню расширения
* Пользователь нажимает комбинацию клавиш, ассоциированную с расширением

activeTab полномочия включают:

* Возможность программно встраивать JavaScript или CSS на страницу, используя `browser.tabs.executeScript` и `browser.tabs.insertCSS`
* Получение доступа к привилегированным частям tabs API для активной вкладки: `Tab.url`, `Tab.title` и `Tab.faviconUrl`.

Цель этих полномочий – позволить расширению выполнять наиболее распространённые сценарии работы, без необходимости выдавать ему более серьёзные привилегии, так как большинство расширений задумано для выполнения какой-либо работы на активной вкладке после взаимодействия с пользователем. Например, представьте расширение, которое встраивает скрипт на текущую страницу, после того как пользователь нажимает на кнопку расширения на панели инструментов. Если бы `activeTab` полномочий не существовало, расширению бы пришлось запрашивать `<all_urls>`. Но они бы давали расширению намного больше привилегий, чем ему было бы необходимо: расширение могло бы встраивать скрипты на любую вкладку и в любой момент, когда пожелает.

Заметьте, что вы сможете иметь доступ к привилегированному tab API, только на момент взаимодействия расширения с пользователем, и пока вкладка не изменила своё состояние. То есть расширение перестанет иметь данные привилегии при изменении адреса страницы или каком-либо другом событии с вкладкой.

Обычно вкладкой, получающей `activeTab` полномочия, является активная в данный момент вкладка, за исключением одного случая. `menus` (en-US) API позволяет расширению создавать элементы контекстного меню, которые будут появляться непосредственно при нажатии на вкладку (элемент на панели вкладок, при нажатии на который изменяется активная вкладка). Если пользователь вызывает контекстное меню на этом элементе, тогда `activeTab` полномочия выдадутся для вкладки, по которой было произведено нажатие, несмотря на то, что она могла бы не является активной (Firefox bug 1446956 начиная с Firefox версии 63).

Доступ к буферу обмена
----------------------

Два полномочия предоставляют расширению привилегии для взаимодействия с буфером обмена:

* `clipboardWrite`: для записи в буфер обмена с помощью `Clipboard.write()` (en-US), `Clipboard.writeText()` (en-US), `document.execCommand("copy")` или `document.execCommand("cut")`
* `clipboardRead`: для чтения из буфера обмена с помощью `Clipboard.read()` (en-US), `Clipboard.readText()` (en-US) или `document.execCommand("paste")`

Смотрите Взаимодействие с буфером обмена (en-US) для более подробной информации.

Неограниченное хранилище
------------------------

Полномочие `unlimitedStorage`:

* Позволяет расширению превышать любые ограничения размера хранимой информации для `storage.local` (en-US) API
* В Firefox, позволяет расширению создавать "persistent" базу данных IndexedDB, не запрашивая разрешения у пользователя в момент её создания.
Примеры
-------

```json
 "permissions": ["\*://developer.mozilla.org/\*"]
```

Запрашивает полномочия для хостов, имеющих developer.mozilla.org в их URL.

```json
  "permissions": ["tabs"]
```

Запрашивает доступ к привилегированным частям `tabs` API.

```json
  "permissions": ["\*://developer.mozilla.org/\*", "tabs"]
```

Запрашивает несколько типов полномочий из примеров выше.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


ключ version - Mozilla

ключ version
============

|  |  |
| --- | --- |
| Тип | `String` |
| Обязательный | Да |
| Пример |
```json
"version": "0.1"
```
 |

Версия дополнения, отформатированная как числа и символы ASCII, разделённые точками. Подробнее о формате версий смотрите страницу Version format.

Обратите внимание, что синтаксис ключа `version` для Chrome более ограниченный, чем у Firefox:

* значения `version` которые действительны для Chrome, всегда будут действительны для Firefox
* значения `version` которые действительны для Firefox, могут быть не действительны для Chrome
Пример
------

```json
"version": "0.1"
```

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


ключ icons - Mozilla

ключ icons
==========

|  |  |
| --- | --- |
| Тип | `Object` |
| Обязательный | Нет |
| Пример |
```json
"icons": {
  "48": "icon.png",
  "96": "icon@2x.png"
}
```
 |

Ключ `icons` определяет, какие иконки (значки) будет использовать ваше дополнение. Эти иконки будут использоваться при показе вашего дополнения в менеджерах компонентов, таких как Менеджер Дополнений.

Он содержит информацию вида ключ-значение со следующими данными: размер изображения в пикселях и путь к соответствующему изображению относительно директории, в которой содержится дополнение.

Если иконки не предоставлены с помощью этого ключа `icons`, вместо них будет использоваться стандартная иконка для расширений.

Вы должны указать по крайней мере одну главную иконку, в идеале размером 48х48 пикселей. Эта иконка будет использоваться по умолчанию в Менеджере Дополнений. Конечно, можно добавить иконки любого размера, и Firefox постарается найти лучшую из них для показа в разных компонентах.

Firefox учитывает разрешение экрана, когда выбирает иконку. Чтобы получить наилучший результат на мониторах с большим разрешением, использующих технологию Retina display, добавьте для каждой иконки версию с размерами в два раза больше.

Пример
------

Ключи в объекте icons определяют размеры иконок в пикселях, значения - относительный путь к файлам с изображениями. Этот пример содержит иконку размером 48х48 пикселей и увеличенную версию для мониторов высокого разрешения.

```json
"icons": {
  "48": "icon.png",
  "96": "icon@2x.png"
}
```

SVG
---

В качестве иконки можно использовать файл SVG. Тогда браузер будет масштабировать иконку так, чтобы она подходила к компоненту, в котором она используется. Но есть два предостережения:

1. В файле изображения должен быть определён viewBox. Например:

```html
<svg viewBox="0 0 48 48" width="48" height="48" ...
```

2. Даже в том случае, если используется всего один файл, нужно определить его для разных размеров иконки в манифесте. Например:

```json
"icons": {
  "48": "icon.svg",
  "96": "icon.svg"
}
```

**Примечание:** Если вы используете программу Inkscape или подобную ей для создания SVG, сохраняйте изображение как "Простой SVG". Иначе Firefox может запутаться во множестве специальных пространств имён и не отобразить картинку.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


ключ background - Mozilla

ключ background
===============

|  |  |
| --- | --- |
| Тип | `Object` |
| Обязательный | Нет |
| Пример |
```json
"background": {
  "scripts": ["background.js"]
}
```
 |

Используйте ключ `background` для включения одного или нескольких фоновых сценариев и, возможно, фоновой страницы в ваше расширение.

Фоновые сценарии — это место для размещения кода, который должен поддерживать долгосрочное состояние или выполнять долгосрочные операции, независимо от времени жизни каких-либо конкретных веб-страниц или окон браузера.

Фоновые сценарии загружаются сразу при загрузке расширения и остаются загруженными до тех пор, пока расширение не будет отключено или удалено. Вы можете использовать любой API-интерфейс WebExtension в сценарии, если вы запросили необходимые права (permissions).

Дополнительную информацию можно найти в статье Внутреннее устройство расширения.

Ключ `background` это объект, у которого есть два следующих необязательных свойства:

|  |  |
| --- | --- |
| `scripts` |
 Массив строк, каждая из которых представляет собой путь к файлу
 JavaScript. Путь к этим файлам указывают относительно папки, в которой
 находится файл manifest.json. Это скрипты, которые будут выполняться в
 фоновой странице расширения.

У этих скриптов общий глобальный контекст объекта `window`.
Скрипты загружаются в том порядке, в котором они указаны в массиве.

 Если вы указали значения с помощью свойства `scripts`,
 будет создана пустая фоновая страница, в которой будут работать все
 эти скрипты.

**Примечание:** Если вы хотите добавить скрипт из
 удалённого расположения с помощью тега
 `<script>` (например,
 `<script src =
"https://code.jquery.com/jquery-1.7.1.min.js">`), может также понадобиться изменить значение ключа
 `content\_security\_policy`
 в файле manifest.json вашего расширения.

**Примечание:** В Firefox до версии 50, когда открыт
 отладчик, скрипты не всегда загружаются в том порядке, в котором они
 расположены в массиве. Чтобы обойти этот баг, можно использовать
 свойство `page` (вместо `scripts`) и добавить
 фоновые скрипты с помощью тегов `<script>` в
 странице HTML. Этот баг починен в Firefox 50. Начиная с этой версии,
 скрипты всегда загружаются в том порядке, в котором они следуют в
 массиве.

 |
| `page` |
 Если вам нужно какое-нибудь содержимое HTML-страницы, можно определить
 свою фоновую страницу с помощью свойства `page`. Это
 строка, которая представляет собой путь к файлу документа HTML,
 заданный относительно расположения файла manifest.json. Этот файл HTML
 должен находиться внутри вашего расширения.

 Если используется это свойство, то уже нельзя добавлять скрипты с
 помощью свойства `scripts`. Вместо этого нужно добавлять
 скрипты в страницу — точно таким же образом, как в обычную
 веб-страницу.
  |

Ключ `background` также может содержать следующее необязательное свойство:

|  |  |
| --- | --- |
| `persistent` | Двоичное значение (`Boolean`).* `true` определяет, что фоновая страница должна храниться
 в памяти с момента, когда загрузилось расширение или запустился
 браузер и до того, как расширение будет удалено или выключено, или
 браузер будет закрыт (то есть фоновая страница постоянна).
* `false` определяет, что фоновая страница может быть
 выгружена из памяти во время бездействия и создана заново, когда
 будет нужна. Такие фоновые страницы часто называются «Страницами
 Событий» (Event Pages) — потому, что они загружаются в память только
 для того, чтобы обрабатывать события, для которых в фоновых скриптах
 назначены функции-обработчики. Зарегистрированные события остаются
 когда фоновая страница выгружена из памяти, но остальные значения
 сбрасываются. Если нужно хранить постоянные данные при использовании
 страницы событий, используйте
 storage API (en-US).
 |

Примеры
-------

```json
  "background": {
    "scripts": ["jquery.js", "my-background.js"]
  }
```

Загрузит два фоновых скрипта.

```json
  "background": {
    "page": "my-background.html"
  }
```

Загрузит файл фоновой страницы.

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


description - Mozilla

description
===========

|  |  |
| --- | --- |
| Тип | `String` |
| Обязательный | Нет |
| Пример |
```json
"description": "Заменяет картинки на картинки с котиками."
```
 |

Краткое описание дополнения, предназначенное для показа в интерфейсе браузера.

Это локализуемое свойство.

Пример
------

```json
"description": "Заменяет картинки на картинки с котиками."
```

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


manifest_version - Mozilla

manifest\_version
=================

|  |  |
| --- | --- |
| Тип | `Number` |
| Обязательный | Да |
| Пример |
```json
"manifest\_version": 3
```
 |

Этот ключ определяет версию `manifest.json`, использующуюся в этом дополнении.

Пример
------

```json
"manifest\_version": 3
```

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Замечания к релизу Firefox для разработчиков - Mozilla

Замечания к релизу Firefox для разработчиков
============================================

Далее ссылки на "Firefox X for developer" (Firefox для разработчиков, где X это версия релиза). Эти замечания описывают новые фичи к релизу и исправленные баги.

1. Firefox 68 for developers
2. Firefox 65 для разработчиков
3. Firefox 64 для разработчиков
4. Firefox 63 для разработчиков
5. Firefox 62 для разработчиков
6. Firefox 53 для разработчиков
7. Firefox 43 для разработчиков
8. Firefox 33 для разработчиков
9. Firefox 32 для разработчиков
10. Firefox 31 for developers
11. Firefox 29 для разработчика
12. Firefox 28 для разработчика
13. Firefox 3.5 для разработчика
14. Firefox 3 для разработчиков


Firefox 43 для разработчиков - Mozilla

Firefox 43 для разработчиков
============================

Установить Firefox Developer Edition Firefox 43 был выпущен 15 декабря 2015 года. В этой статье перечислены ключевые изменения, которые полезны не только для веб-разработчиков, но и для разработчиков Firefox и Gecko, а также для разработчиков приложений.

Важные изменения для Веб Разработчиков
--------------------------------------

### Инструменты разработчика

Главное:

* Просмотр логов сервера в Консоли Веб (en-US)
* Быстрый поиск правила переопределяющего объявление CSS
* Новый пункт в контекстном меню Инспектора : "Use in Console"
* "Strict" опция для фильтрации в Rules view
* Сообщения в панели Сеть, в Консоли теперь ссылаются на Сетевой Монитор (en-US)
* В Инспекторе при обзоре разметки можно увидеть индикатор указывающий псевдоклассы у соответствующих элементов
* Новая боковая панель в WebIDE

И как обычно исправлены обнаруженные баги в инструментах разработчика в версиях Firefox 42 и Firefox 43.

### CSS

* Удалён префикс CSS-свойства `hyphens` (Firefox bug 953408).
* CCS свойство `font` теперь поддерживает указание `font-stretch` (en-US) Firefox bug 1057680).
* Псевдокласс `:fullscreen` теперь выбирает весь стек элементов с дисплея в полноэкранном режиме, а не только элементы высшего уровня (Firefox bug 1199522).
* Устаревшие свойства SVG `writing-mode`, `lr`, `lr-tb`, `rl`, `tb`, and `tb-rl`, добавлены в CSS как алиасы стандартных CSS-свойств (Firefox bug 1205787).
### HTML

* Для тега `<img>` с изображением формата ICO содержащего несколько кадров (анимированного), разрешение изображения будет равным разрешению самого большого кадра, а не самого малого Firefox bug 1201796.
* Значение области просмотра документа (viewport) (определённого с помощью тега `<meta name="viewport>`) можно динамически изменять с помощью JavaScript (Firefox bug 976616).
### JavaScript

#### Новые API

* Новые методы ES2016 `Array.prototype.includes()` и `TypedArray.prototype.includes()` (en-US) доступны по умолчанию (Firefox bug 1070767).

#### Изменения связанные с объектом `arguments`

* Более полное соответствие спецификации ES2015, стрелочные функции больше не содержат свой собственный встроенный объект `arguments`. Объект `arguments` теперь прикреплён лексически (наследуется от внешней функции). В большинстве случаев, остаточные параметры лучшая альтернатива `(...args) => args[i]`, смотри Firefox bug 889158.
* Объект arguments теперь разрешается использовать вместе с остаточными параметрами (Firefox bug 1133298).
* Теперь, объект map `arguments` в нестрогих функциях доступен только если функция не содержит другие остаточные параметры, или параметры по умолчанию илиdestructured parameters (Firefox bug 1175394).
### Interfaces/APIs/DOM

#### DOM & HTML DOM

*Без изменений.*

#### IndexedDB

* Добавлена сортировка с учётом локали, которая позволяет создавать индексы учитывающие локаль. Эти индексы потом могут быть использованы чтобы отсортировать данные с учётом правил локали. (Firefox bug 871846). Это не стандартная функция и доступна только в Firefox.

#### Service Workers

* Согласно спецификации, если `ExtendableEvent.waitUntil()` был вызван вне обработчика `ExtendableEvent` (en-US), Firefox выбросит `InvalidStateError`; также несколько подряд идущих вызовов `waitUntil()` теперь будут помещены в стек, и результирующие промисы будут добавлены в extend lifetime promises (Firefox bug 1180274).
* Реализованы методы `PushMessageData` (en-US) (Firefox bug 1149195).

#### WebRTC

* Метод `HTMLCanvasElement.captureStream()` активирован в Firefox по умолчанию (Firefox bug 1177276).

#### Разное

* Battery Status API (en-US) теперь использует новый синтаксис промисов для `Navigator.getBattery()`, так как это описано в последней версии спецификации (Firefox bug 1050749).
* Заголовок `User-Agent` более не в списке forbidden header names и теперь может быть установлен в объект Fetch `Headers` (en-US), через XHR `XMLHttpRequest.setRequestHeader()`,… (Firefox bug 1188932).
* Конструктор `MediaRecorder.MediaRecorder()` теперь принимает дополнительно необязательный параметр типа словарь (dictionary), который позволяет вам устанавливать произвольный битрейт для записываемого аудио/видео (Firefox bug 1161276).
* Реализован интерфейс `PerformanceObserver` (en-US), из Performance Timeline API (Firefox bug 1165796).
* Добавлены дополнительно два интерфейса в Frame Timing API, `PerformanceRenderTiming` и `PerformanceCompositeTiming` (Firefox bug 1191178).
* Реализована современная версия Screen Orientation API (en-US): доступны беспрефиксные интерфейсы `Screen.orientation` (en-US) и `ScreenOrientation` (en-US) (Firefox bug 1131470). Не стандартные `Screen.mozOrientation`, `Screen.onmozorientationchange`, `Screen.mozLockOrientation()`, и `Screen.mozUnlockOrientation()` будут удалены в будущем.
* В Линукс, как и в Windows, `Event.timeStamp` теперь возвращает {domxref("DOMHighResTimeStamp")}} (Firefox bug 1026803).
* Экспериментальная поддержка `Selection` (en-US) событий `selectionchange` и `selectstart`, а также добавлены `Document.onselectionchange` (en-US) и `GlobalEventHandlers.onselectstart` (en-US) свойства для обработчиков событий (Firefox bug 571294). Событие `selectionchange` теперь возникает на `Document` если связано с объектом `Selection`, или в особом случае `HTMLInputElement` (en-US) или `HTMLTextAreaElement` (en-US) (Firefox bug 1196479). Это свойство контролируется с помощью настройки `dom.select_events.enabled`, которое по умолчанию имеет значение `false`, за исключением Firefox Nightly.
* Поддержка `MouseEvent.offsetX` и `MouseEvent.offsetY` (en-US) доступна по умолчанию в Android версии Firefox и Firefox OS (Firefox bug 1204841).
* Удалён метод `HTMLCanvasElement.mozFetchAsStream()` (Firefox bug 1206030).
* Конструктор `Request()` (en-US) а также `fetch()` (en-US) теперь выбросит исключение `TypeError` если будет использовано в URL которое содержит параметры с именами username и password (Firefox bug 1195820).
### MathML

*Без изменений.*

### SVG

*Без изменений.*

### Audio/Video

*Без изменений.*

HTTP
----

*Без изменений.*

Networking
----------

*Без изменений.*

Безопасность
------------

* Доступ к Web Storage (i.e. `localStorage` и `sessionStorage`) из других IFrame-мов запрещён если у пользователя заблокированы куки из сторонних сервисов (других веб-сайтов) (Firefox bug 536509).
* Белый список удалён из Nightly и Aurora/Dev Edition браузеров (Firefox bug 1201023). Также запланировано удаление из Beta и Release версий в следующей версии (Firefox 44).
* Реализована целостность ресурсов для `<script>` и `<link>` которые ведут к файлам стилей (Firefox bug 992096).
Изменения для разработчиков дополнений и разработчиков Mozilla
--------------------------------------------------------------

### Interfaces

*Без изменений.*

### XUL

*Без изменений.*

### JavaScript code modules

*Без изменений.*

### XPCOM

*Без изменений.*

### Other

*Без изменений.*

Старые версии
-------------

* Firefox 42 для разработчиков (en-US)
* Firefox 41 для разработчиков (en-US)
* Firefox 40 для разработчиков (en-US)
* Firefox 39 для разработчиков (en-US)
* Firefox 38 для разработчиков (en-US)
* Firefox 37 для разработчиков (en-US)
* Firefox 36 для разработчиков (en-US)
* Firefox 35 для разработчиков (en-US)
* Firefox 34 для разработчиков (en-US)
* Firefox 33 для разработчиков
* Firefox 32 для разработчиков
* Firefox 31 для разработчиков
* Firefox 30 для разработчиков (en-US)
* Firefox 29 для разработчиков
* Firefox 28 для разработчиков
* Firefox 27 для разработчиков (en-US)
* Firefox 26 для разработчиков (en-US)
* Firefox 25 для разработчиков (en-US)
* Firefox 24 для разработчиков (en-US)
* Firefox 23 для разработчиков (en-US)
* Firefox 22 для разработчиков (en-US)
* Firefox 21 для разработчиков (en-US)
* Firefox 20 для разработчиков (en-US)
* Firefox 19 для разработчиков (en-US)
* Firefox 18 для разработчиков (en-US)
* Firefox 17 для разработчиков (en-US)
* Firefox 16 для разработчиков (en-US)
* Firefox 15 для разработчиков (en-US)
* Firefox 14 для разработчиков (en-US)
* Firefox 13 для разработчиков (en-US)
* Firefox 12 для разработчиков (en-US)


Firefox 31 for developers - Mozilla

Firefox 31 for developers
=========================

Хотите помочь документировать Firefox 31? См. список багов, требующих описания, и беритесь за дело!

Изменения для Web-разработчиков
-------------------------------

### Инструменты разработчика

Важные моменты:

* «пипетка» для выбора цветов на web-страницах
* полное отслеживание стека для консольных сообщений об ошибках
* редактируемое Box Model View
* %c-форматирование для стилизации консольных сообщений
* команда «copy as cURL» в Network Monitor
* клавишные привязки Sublime Text в редакторе источника
* возможность сделать логи Network Monitor персистентными
* JavaScript-предупреждения включены по умолчанию в Web-консоли
* Alt+клик раскрывает всех потомков узла

Все баги инструментов разработчика, исправленные с Firefox 30 по Firefox 31.

### CSS

* Префикс «var-» у CSS-переменных изменён на «--» (Firefox bug 985838).
* Исправлен нежелательный пробел для кратного 10 000 в корейских стилях счётчика (Firefox bug 985186).
* Исправлены переходы CSS-прозрачности при псевдоклассе родителя :before и значении auto свойства overflow (Firefox bug 990340).
* Псевдоэлемент ::-moz-math-stretchy удалён (Firefox bug 1000879).
### HTML

* Реализован элемент <track> (Firefox bug 629350).
### JavaScript

Реализована новая функциональность ECMAScript 6:

* Новый метод экземпляров `Array`: `Array.prototype.fill()` (Firefox bug 911147)
* Новая `Math`-функция: `Math.clz32()` (Firefox bug 925123)
* Новый метод экземпляров `String`: `String.prototype.normalize()` доступен в Firefox Desktop (Firefox bug 918987).
* Новый метод `Object` `Object.setPrototypeOf()`.
* Новые константы `Number`: `Number.MAX_SAFE_INTEGER` and `Number.MIN_SAFE_INTEGER`.
### Интерфейсы/API/DOM

* Реализован конструктор для `KeyboardEvent` (Firefox bug 930893).
* Реализован атрибут `KeyboardEvent.isComposing` (Firefox bug 993234).
* Реализован интерфейс `InputEvent` (Firefox bug 993253).
* Реализован атрибут `InputEvent.isComposing` (Firefox bug 993253).
* Реализован `CSS.escape()` (en-US) (Firefox bug 955860).
* Событие `mousemove` теперь отменяемое, как в других браузерах (Firefox bug 704423). Вызов `preventDefault()` только выставляет атрибут `defaultPrevented` в `true`. То есть остальное поведение не изменилось. Например, это не может предотвратить выставление состояния `:hover`.
### MathML

* Частичная реализация OpenType MATH table, раздел 6.3.6 (Firefox bug 407059). Подробнее см. шрифты для Mozilla-всякого движка MathML (en-US) и MathML torture test .
* Псевдоэлемент `::-moz-math-stretchy` удалён (Firefox bug 1000879).
* Если они доступны, юникодовские математические буквенно-цифровые символы используются для полужирных, курсивных и полужирно-курсивных mathvariants (Firefox bug 930504).
### SVG

*Нет изменений.*

### Аудио/видео

*Нет изменений.*

Безопасность
------------

* Привилегированный код теперь получает Xray vision для экземпляров `Date` (en-US).
Изменения для аддонов и разработчиков Mozilla
---------------------------------------------

* Атрибут «`align`» для `urlbar-wrapper` (ранее для `urlbar-container`), который был установлен в «`center`» со времён незапамятных, удалён. Это, как известно, влияет на сторонние темы. Вам следует внимательно посмотреть, какое исправление будет правильным для вашей темы, но для поддержания эквивалентного эффекта вы можете добавить в свою тему следующее CSS-правило:
 `#urlbar-wrapper { -moz-box-align: center; }`
* `nsIDOMWindowUtils.sendQueryContentEvent()` и `nsIDOMWindowUtils.sendSelectionSetEvent()` имеют `aAdditionalFlags` как необязательный аргумент. Если вы вызываете `nsIDOMWindowUtils.sendSelectionSetEvent()` со значением `true` для `aReverse`, поведение может быть сломано этим изменением. См. подробности о `aAdditionalFlags` в объяснении каждого флага (`QUERY_CONTENT_FLAG_*` and `SELECTION_SET_FLAG_*`).
### Add-on SDK

Важные моменты:

* Add-on Debugger
* Добавлена возможность преобразования между высокоуровневыми объектами BrowserWindow и окнами DOM и между высокоуровневыми объектами Tab и вкладками XUL.
* Обновлена тема по умолчанию, используемая для панелей в Mac OS X.
* Добавлены опции панели contentStyle и contentStyleFile.

GitHub-коммиты, выполненные с Firefox 30 по Firefox 31. Это не включает никакие uplifts, сделанные после того, как этот релиз вступил в фазу Aurora.

Исправления багов с Firefox 30 по Firefox 31. Это не включает никакие uplifts, сделанные после того, как этот релиз вступил в фазу Aurora.

Смотрите также
--------------

* Совместимость сайтов для Firefox 31
### Старшие версии

* Firefox 30 для разработчиков (en-US)
* Firefox 29 для разработчиков
* Firefox 28 для разработчиков
* Firefox 27 для разработчиков (en-US)
* Firefox 26 для разработчиков (en-US)
* Firefox 25 для разработчиков (en-US)
* Firefox 24 для разработчиков (en-US)
* Firefox 23 для разработчиков (en-US)
* Firefox 22 для разработчиков (en-US)
* Firefox 21 для разработчиков (en-US)
* Firefox 20 для разработчиков (en-US)
* Firefox 19 для разработчиков (en-US)
* Firefox 18 для разработчиков (en-US)
* Firefox 17 для разработчиков (en-US)
* Firefox 16 для разработчиков (en-US)
* Firefox 15 для разработчиков (en-US)
* Firefox 14 для разработчиков (en-US)
* Firefox 13 для разработчиков (en-US)
* Firefox 12 для разработчиков (en-US)
* Firefox 11 для разработчиков (en-US)
* Firefox 10 для разработчиков (en-US)
* Firefox 9 для разработчиков (en-US)
* Firefox 8 для разработчиков (en-US)
* Firefox 7 для разработчиков (en-US)
* Firefox 6 для разработчиков (en-US)
* Firefox 5 для разработчиков (en-US)
* Firefox 4 для разработчиков (en-US)
* Firefox 3.6 для разработчиков (en-US)
* Firefox 3.5 для разработчиков
* Firefox 3 для разработчиков
* Firefox 2 для разработчиков (en-US)
* Firefox 1.5 для разработчиков (en-US)