JavaScript API

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

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

Доступ к API можно получить с использованием пространства имён browser:

function logTabs(tabs) {
  console.log(tabs)
}

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

Многие API асинхронные, возвращая Promise:

function logCookie(c) {
  console.log(c)
}

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

let setCookie = browser.cookies.set(
  {url: "https://developer.mozilla.org/"}
);
setCookie.then(logCookie, logError)

Отличия API браузера

Обратите внимание, что это отличается от системы расширений Google Chrome, которая вместо browser использует пространство имён chrome и для асинхронных функций использует обратные вызовы вместо промисов. В качестве инструмента для переноса, реализация API WebExtensions в Firefox поддерживает chrome и обратные вызовы, а также browser и промисы. Mozilla также написала полифилл, который позволяет коду, использующему browser и промисы, работать без изменений в Chrome: https://github.com/mozilla/webextension-polyfill.

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

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

Не все браузеры поддерживают все API. Подробнее см. Поддержка JavaScript API в браузерах и Несовместимости с Chrome.

Примеры

Во всех списках JavaScript API приведены краткие примеры кода, демонстрирующие использование API. Большинство из этих примеров можно протестировать с помощью консоли в инструментах разработчика. Однако инструменты разработчика должны быть запущены в контексте веб-расширения. Для этого откройте about:debugging затем Этот Firefox, щелкните Просмотреть рядом с любым установленным или временным расширением и откройте Консоль. Затем вы можете вставить и запустить пример кода в консоли.

Например, вот первый пример кода на этой странице, запущенный в консоли инструментов разработчика Firefox:

Illustration of a snippet of web extension code run from the console in the Toolbox

Список JavaScript API

Полный список JavaScript API приведен ниже:

action: Добавляет кнопку на панель инструментов браузера.
alarms: Планирует выполнение кода в определенное время в будущем. Это похоже на setTimeout() и setInterval(), за исключением того, что эти функции не работают со страницами фоновых процессов, загружаемых по требованию.
bookmarks: API bookmarks расширений WebExtensions позволяет расширению взаимодействовать с системой закладок браузера и изменять её. Вы можете использовать его для добавления закладок, получения существующих закладок, а также редактирования, удаления и упорядочивания закладок.
browserAction: Добавляет кнопку на панель инструментов браузера.
browserSettings: Позволяет расширению изменять определенные глобальные настройки браузера. Каждое свойство этого API является объектом types.BrowserSetting, предоставляющим возможность изменения конкретной настройки.
browsingData: Позволяет расширениям очищать данные, накапливаемые во время просмотра пользователем.
captivePortal: Определяет состояние портала доступа для подключения пользователя. Портал доступа — это веб-страница, отображаемая при первом подключении пользователя к Wi-Fi сети. Пользователь предоставляет информацию или выполняет действия на странице портала доступа, чтобы получить более широкий доступ к ресурсам сети, например, принимая условия или делая платеж.
clipboard: API расширений WebExtension clipboard (отличается от стандартного Clipboard API) позволяет расширению копировать элементы в системный буфер обмена. В настоящее время API расширений WebExtension clipboard поддерживает только копирование изображений, но в будущем планируется поддержка копирования текста и HTML.
commands: Прослушивает выполнение пользователем команд, которые вы зарегистрировали, используя ключ commands manifest.json.
contentScripts: Используйте этот API для регистрации скриптов содержимого. Регистрация скрипта содержимого сообщает браузеру о вставке заданных скриптов содержимого на страницы, соответствующие заданным шаблонам URL.
contextualIdentities: Работа с контекстными идентификаторами: список, создание, удаление и обновление контекстных идентификаторов.
cookies: Позволяет расширениям получать и устанавливать куки, а также получать уведомления об их изменении.
declarativeNetRequest: Этот API позволяет расширениям получать информацию о декларативных правилах, блокирующих или изменяющих сетевые запросы, и изменять их. Использование декларативных правил означает, что расширения не перехватывают и не просматривают содержимое запросов, обеспечивая большую конфиденциальность.
devtools: Позволяет расширениям взаимодействовать с инструментами разработчика браузера. Вы можете использовать этот API для создания страниц инструментов разработчика, взаимодействия с окном, которое проверяется, просмотра использования сети страницы.
dns: Позволяет расширению разрешать доменные имена.
dom: Доступ к специальным функциям DOM, доступным только расширениям.
downloads: Позволяет расширениям взаимодействовать с менеджером загрузок браузера. Вы можете использовать этот модуль API для загрузки файлов, отмены, приостановки, возобновления загрузок и отображения загруженных файлов в файловом менеджере.
events: Общие типы, используемые API, которые отправляют события.
extension: Утилиты, относящиеся к вашему расширению. Получение URL-адресов ресурсов пакетов вашего расширения. Получение объекта Window для страниц вашего расширения. Получение значений различных настроек.
extensionTypes: Некоторые общие типы, используемые в других API WebExtension.
find: Находит текст на веб-странице и выделяет совпадения.
history: Используйте API history для взаимодействия с историей браузера.
i18n: Функции для локализации вашего расширения. Вы можете использовать эти API для получения локализованных строк из файлов локализации, упакованных с вашим расширением, определения текущего языка браузера и получения значения его Accept-Language header.
identity: Используйте API identity для получения кода авторизации OAuth2 или токена доступа, который расширение может затем использовать для доступа к данным пользователя из сервиса, поддерживающего доступ OAuth2 (например, Google или Facebook).
idle: Определяет, когда система пользователя находится в режиме ожидания, блокировки или активности.
management: Получает информацию об установленных дополнениях.
menus: Добавляет элементы в систему меню браузера.
notifications: Отображает уведомления пользователю, используя механизм уведомлений операционной системы. Поскольку этот API использует механизм уведомлений операционной системы, детали отображения и поведения уведомлений могут отличаться в зависимости от операционной системы и настроек пользователя.
omnibox: Позволяет расширениям реализовать настраиваемое поведение при вводе пользователем текста в адресную строку браузера.
pageAction: Действие на странице — настраиваемая кнопка внутри адресной строки браузера.
permissions: Позволяет расширениям запрашивать дополнительные разрешения во время выполнения после их установки.
pkcs11: API pkcs11 позволяет расширению перечислять модули безопасности PKCS #11 и делать их доступными для браузера как источники ключей и сертификатов.
privacy: Доступ и изменение различных настроек браузера, связанных с конфиденциальностью.
proxy: Используйте API proxy для проксирования веб-запросов. Вы можете использовать обработчик событий proxy.onRequest для перехвата веб-запросов и возврата объекта, описывающего, нужно ли и как их проксировать.
runtime: Этот модуль предоставляет информацию о вашем расширении и среде его работы.
scripting: Вставляет JavaScript и CSS на веб-сайты. Этот API предлагает два подхода к вставке содержимого:
search: Используйте API поиска для получения установленных поисковых систем и выполнения поисковых запросов.
sessions: Используйте API сессий для отображения и восстановления вкладок и окон, которые были закрыты во время работы браузера.
sidebarAction: Получение и установка свойств боковой панели расширения.
storage: Позволяет расширениям хранить и получать данные, а также прослушивать изменения сохраненных элементов.
tabs: Взаимодействие с системой вкладок браузера.
theme: Позволяет расширениям браузера обновлять тему браузера.
topSites: Используйте API topSites для получения массива, содержащего часто посещаемые пользователем страницы.
types: Определяет тип BrowserSetting, используемый для представления настройки браузера.
userScripts

END_OF_DOCUMENT_MARKER

Используйте этот API для регистрации пользовательских скриптов, сторонних скриптов, предназначенных для управления веб-страницами или предоставления новых функций. Регистрация пользовательского скрипта инструктирует браузер прикрепить скрипт к страницам, которые соответствуют шаблонам URL, указанным при регистрации.
webNavigation: Добавьте обработчики событий для различных стадий навигации. Навигация состоит из фрейма в браузере, переходящего от одного URL к другому, обычно (но не всегда) в ответ на действие пользователя, такое как щелчок по ссылке или ввод URL в адресной строке.
webRequest: Добавьте обработчики событий для различных стадий выполнения HTTP-запроса, что включает запросы WebSocket на ws:// и wss://. Обработчик событий получает подробную информацию о запросе и может изменять или отменять запрос.
windows: Взаимодействуйте с окнами браузера. Вы можете использовать этот API для получения информации об открытых окнах, для открытия, изменения и закрытия окон. Вы также можете прослушивать события открытия, закрытия и активации окна.

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API