recursal/MDN huggingface dataset:
JavaScript APIs
===============

JavaScript WebExtension API может быть использован в фоновых скриптах расширения, а так же в любых других документах, поставляемых вместе с расширением, таких как документы во всплывающих окнах после нажатия кнопок активации расширения browser actionна панели инструментов или page action (en-US) в строке адреса, боковой панели, страницах настроек (en-US) или новых открытых вкладках (en-US). Некоторые из этих API могут быть доступны на встраиваемых в страницу скриптах (см. список в руководстве по встраиваемым скриптам).

Для использования отдельных более продвинутых API, необходимо запросить разрешения в manifest.json вашего дополнения.

Вы можете получить доступ к API, используя пространство имён `browser`:


```js
function logTabs(tabs) {
  console.log(tabs);
}

browser.tabs.query({ currentWindow: true }, logTabs);
```


Многие API выполняются асинхронно, возвращая `Promise`:


```js
function logCookie(c) {
  console.log(c);
}

function logError(e) {
  console.error(e);
}

var setCookie = browser.cookies.set({ url: "/" });
setCookie.then(logCookie, logError);
```


Обратите внимание, что это отличается от расширений Google Chrome, которые используют пространство имён `chrome` вместо `browser` и колбэки для асинхронных функций вместо промисов.

Для поддержки портирования, реализация Firefox WebExtension API так же поддерживает пространство имён `chrome` и использование колбэков. Это позволяет в большинстве случаев не изменять код, изначально написанный для Chrome.

Mozilla так же предоставляет полифил, который позволяет коду, использующему `browser` и промисы, работать без изменений в Chrome: https://github.com/mozilla/webextension-polyfill.

Microsoft Edge использует пространство имён `browser`, но ещё не поддерживает, основанный на промисах асинхронный API. В Edge на данный момент асинхронные вызовы API должны использовать колбэки.

Не все браузеры поддерживают все API: детали см. Browser support for JavaScript APIs (en-US).

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

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

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

Веб ЗапросДобавляет обработчики событий на различных стадиях HTTP запроса. Обработчик получить детальную информацию о запросе и способен изменить или отменить запрос.
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
=======

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

Для использования этого 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
==============

Тип `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
==================

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

Тип
---

Значение данного типа `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()
=====================

Получить весь файл 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()
==========

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

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


```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.
Кнопка в панели инструментов
============================

 Кнопка на панели инструментов браузера (оригинальное название 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 открывает всплывающее окно.
Страницы расширения
===================

В расширение можно добавить 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, в котором используются некоторые из возможностей для создания окон.
Уведомления
===========

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

![](/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, которое реализует систему уведомлений.
Контекстное меню
================

Эта возможность пользовательского интерфейса позволяет добавлять новые элементы в контекстное меню браузера, появляющееся при нажатии правой кнопки мыши. Вкладки браузера также имеют контекстное меню доступное через 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
=========

|  |  |
| --- | --- |
| Тип | `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.
ключ 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.