Spec-Zone.ru › Web Extensions

browser_action

Тип Object
Обязательность Нет
Версия манифеста 2
Пример
"browser_action": {
  "browser_style": true,
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html",
  "theme_icons": [{
    "light": "icons/geo-16-light.png",
    "dark": "icons/geo-16.png",
    "size": 16
  }, {
    "light": "icons/geo-32-light.png",
    "dark": "icons/geo-32.png",
    "size": 32
  }]
}

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

Этот ключ заменяется на action в расширениях манифеста версии 3.

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

Вы также можете программно создавать и управлять действиями браузера, используя API browserAction.

Синтаксис

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

Имя Тип Описание
browser_style Boolean

Необязательно, по умолчанию false.

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

В Firefox, таблицу стилей можно увидеть по адресу chrome://browser/content/extension.css или chrome://browser/content/extension-mac.css на macOS. При настройке размеров, учитывайте, что эта таблица стилей в настоящее время устанавливает box-sizing: border-box (см. box-sizing).

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

Расширение latest-download использует browser_style в своём всплывающем окне.

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

  1. Установите browser_style в значение false
  2. Используйте стили CSS для тела вашего бокового меню или HTML всплывающего окна, чтобы разрешить выделение текста, добавив правило -moz-user-select со значением all или text.
default_area String

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

  • "navbar": кнопка размещается в основной панели инструментов браузера, рядом с адресной строкой.
  • "menupanel": кнопка размещается в всплывающем окне.
  • "tabstrip": кнопка размещается в панели инструментов, содержащей вкладки браузера.
  • "personaltoolbar": кнопка размещается в панели закладок.

Это свойство поддерживается только в Firefox.

Это свойство необязательно и по умолчанию имеет значение "menupanel".

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

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

default_icon Object или String

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

Значки задаются как URL-адреса, относительные к файлу manifest.json.

Вы можете указать один значок, указав здесь строку:

"default_icon": "path/to/geo.svg"

Чтобы указать несколько значков разных размеров, укажите здесь объект. Имя каждой свойства — высота значка в пикселях, и оно должно быть преобразуемо в целое число. Значение — URL-адрес. Например:

    "default_icon": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png"
    }

Вы не можете указать несколько значков одного размера.

См. Выбор размеров значков для получения более подробной информации об этом.

default_popup String

Путь к HTML-файлу, содержащему описание всплывающего окна.

HTML-файл может содержать CSS и JavaScript-файлы, используя элементы <link> и <script>, как и обычная веб-страница. Однако, <script> должен иметь атрибут src для загрузки файла. Не используйте <script> с встроенным кодом, так как вы получите ошибку политики нарушения содержимого.

В отличие от обычной веб-страницы, JavaScript, выполняемый во всплывающем окне, имеет доступ ко всем API расширений веб-браузера (разумеется, при условии, что у расширения есть соответствующие разрешения).

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

default_title String

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

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

theme_icons Array

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

Если это свойство присутствует, это массив, содержащий по крайней мере один объект ThemeIcons. Объект ThemeIcons содержит три обязательных свойства:

"dark"
URL-адрес, указывающий на значок. Этот значок отображается, когда активна тема с тёмным текстом (например, тема Firefox Light и тема по умолчанию, если значок по умолчанию не указан).
"light"
URL-адрес, указывающий на значок. Этот значок отображается, когда активна тема со светлым текстом (например, тема Firefox Dark).
"size"
Размер двух значков в пикселях.

Значки задаются как URL-адреса, относительные к файлу manifest.json.

Вы должны предоставить значки 16x16 и 32x32 (для дисплеев с высоким разрешением) ThemeIcons.

Выбор размеров значков

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

  • Значок отображается в панели инструментов браузера. Более старые версии Firefox поддерживали возможность размещения значка на панели меню браузера (панель, открывающаяся при нажатии пользователем значка «гамбургер»). В этих версиях Firefox значок на панели меню был больше, чем значок в панели инструментов.
  • На дисплее с высоким разрешением, как например, на экране Retina, значки должны быть вдвое больше.

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

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

"default_icon": "path/to/geo.svg"

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

В Firefox:

  • Высота и ширина значков на панели инструментов по умолчанию составляют 16 * window.devicePixelRatio.
  • Высота и ширина значков на панели меню по умолчанию составляют 32 * window.devicePixelRatio.

Таким образом, вы можете указать значки, которые точно соответствуют размеру на обычных и экранах Retina, предоставив три файла значков и указав их так:

"default_icon": {
  "16": "path/to/geo-16.png",
  "32": "path/to/geo-32.png",
  "64": "path/to/geo-64.png"
}

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

Пример

"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}

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

 browser.browserAction.onClicked.addListener(handleClick);
"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

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

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

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

Рабочий стол Мобильный
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari на IOS Samsung Internet
browser_action
Да["Доступно только в Manifest V2.", "Если расширение определяет действие браузера, оно не может определять действие страницы."]
14Доступно только в Manifest V2.
48Доступно только в Manifest V2.
?
Да["Доступно только в Manifest V2.", "Если расширение определяет действие браузера, оно не может определять действие страницы."]
14["Доступно только в Manifest V2.", "Если расширение определяет действие браузера, оно не может определять действие страницы."]
? ?
55Доступно только в Manifest V2.
?
15["Доступно только в Manifest V2.", "Если расширение определяет действие браузера, оно не может определять действие страницы."]
?
browser_style Нет Нет 48 ? Нет Нет ? ? Нет ? Нет ?
default_area Нет Нет 54 ? Нет Нет ? ? Нет ? Нет ?
default_icon
ДаИконки SVG не поддерживаются.
14["Иконки SVG не поддерживаются.", "'default_icon' должен быть объектом со явными размерами."]
48 ?
ДаИконки SVG не поддерживаются.
14Иконки SVG не поддерживаются. Оттененные изображения будут обрабатываться как шаблоны с использованием системного цвета акцента и внешнего вида системы.
? ? Нет ?
15Иконки SVG не поддерживаются. Оттененные изображения будут обрабатываться как шаблоны с использованием системного цвета акцента и внешнего вида системы.
?
default_popup Да 14 48 ? Да 14 ? ? 57 ? 15 ?
default_title Да 14 48 ? Да 14 ? ?
55Действия браузера представлены как пункты меню, и заголовок является меткой пункта меню.
? 15 ?
theme_icons Нет Нет 56 ? Нет Нет ? ? Нет ? Нет ?

См. также

  • page_action
  • sidebar_action
  • Стили браузера

© 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/manifest.json/browser_action

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API