chrome.browserAction

дата обновления: 2026-09-25 robots: noindex

Описание

Доступность

На следующем рисунке разноцветный квадрат справа от адресной строки — это значок действия браузера. Под значком находится всплывающее окно.

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

Манифест

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

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

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

Поскольку устройства с менее распространенными коэффициентами масштабирования, такими как 1,5x или 1,2x, становятся все более распространенными, рекомендуется предоставлять значки разных размеров. Это также гарантирует, что если размер отображаемых значков когда-либо изменится, вам не придется дополнительно работать над предоставлением разных значков!

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

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Части пользовательского интерфейса

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

Икона

Значки действий в браузере Chrome имеют ширину и высоту 16 делений (пикселей, не зависящих от устройства). Значки большего размера масштабируются, но для достижения наилучших результатов используйте квадратный значок с 16 делениями.

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

Статические изображения могут быть в любом формате, который поддерживает WebKit, включая BMP, GIF, ICO, JPEG или PNG. Для распакованных расширений изображения должны быть в формате PNG.

Чтобы установить иконку, используйте поле default_icon объекта browser_action в манифесте или вызовите метод browserAction.setIcon .

Для корректного отображения значка, когда плотность пикселей экрана (отношение size_in_pixel / size_in_dip ) отличается от 1, значок можно определить как набор изображений разных размеров. Фактическое изображение для отображения будет выбрано из набора таким образом, чтобы оно наилучшим образом соответствовало размеру пикселей 16 dip. Набор значков может содержать любые спецификации размеров, и Chrome выберет наиболее подходящий вариант.

Всплывающая подсказка

Чтобы задать всплывающую подсказку, используйте поле default_title объекта browser_action в манифесте или вызовите метод browserAction.setTitle . Для поля default_title можно указать строки, специфичные для локали; подробности см. в разделе « Интернационализация» .

Значок

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

Поскольку место на бейдже ограничено, он должен содержать не более 4 символов.

Задайте текст и цвет значка с помощью browserAction.setBadgeText и browserAction.setBadgeBackgroundColor соответственно.

Неожиданно возникнуть

Если действие браузера включает всплывающее окно, оно появляется при щелчке пользователя по значку расширения. Всплывающее окно может содержать любой HTML-контент по вашему выбору и автоматически подстраивается под его размер. Размер всплывающего окна не может быть меньше 25x25 пикселей и не может быть больше 800x600 пикселей.

Чтобы добавить всплывающее окно к действию браузера, создайте HTML-файл с содержимым всплывающего окна. Укажите HTML-файл в поле default_popup объекта browser_action в манифесте или вызовите метод browserAction.setPopup .

Советы

Для достижения наилучшего визуального эффекта следуйте этим рекомендациям:

• Используйте действия браузера для функций, которые имеют смысл на большинстве страниц.
• Не используйте действия браузера для функций, которые имеют смысл только для нескольких страниц. Вместо этого используйте действия страницы .
• Используйте большие, красочные значки, максимально эффективно используя пространство 16x16. Значки действий в браузере должны выглядеть немного больше и массивнее, чем значки действий на странице.
• Не пытайтесь имитировать монохромную иконку меню Google Chrome. Это плохо сочетается с темами оформления, и, кроме того, расширения должны немного выделяться.
• Используйте альфа-канал для смягчения краев вашей иконки. Поскольку многие используют темы оформления, ваша иконка будет хорошо смотреться на фоне различных цветов.
• Не нужно постоянно анимировать иконку. Это просто раздражает.

Примеры

Простые примеры использования действий браузера можно найти в каталоге examples/api/browserAction . Другие примеры и помощь в просмотре исходного кода см. в разделе Samples .

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.onClicked.addListener(
  callback: function,
)