Расширения Manifest V2 были удалены из Chrome Web Store 31 августа 2026 года. Перенесите свое расширение на Manifest V3, чтобы оно снова стало доступно пользователям.

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

chrome.browserAction

refresh date: 2026-09-25 robots: noindex

Описание

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

Доступность

&leq; MV2

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

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

Манифест

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

{
  "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 выберет наиболее подходящий и масштабирует его до нужного размера, чтобы заполнить пространство в 16 dip. Однако если точный размер не указан, значок может потерять детализацию или выглядеть размытым.

Поскольку устройства с менее распространенными коэффициентами масштабирования, такими как 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 dips (независимых от устройства пикселей). Значки большего размера будут уменьшены, но для наилучшего результата используйте квадратный значок размером 16 dip.

Значок можно задать двумя способами: с помощью статического изображения или элемента 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 можно указать строки, зависящие от региональных настроек. Подробную информацию вы найдете в статье Интернационализация.

Значок

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

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

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

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

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

Советы

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

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

Примеры

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

Типы

TabDetails

Chrome 88 и более поздних версий;

Свойства

tabId

number (необязательно)

Идентификатор вкладки, состояние которой нужно запросить. Если вкладка не указана, возвращается состояние, не связанное с вкладкой.

Методы

disable()

Promise

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

Отключает действие браузера для вкладки.

Параметры

tabId

number (необязательно)

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

function необязательно

Chrome 67 и более поздних версий

Параметр callback выглядит следующим образом:
```
() => void
```

Возвраты

Promise<void>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

enable()

Promise

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

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

Параметры

tabId

number (необязательно)

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

function необязательно

Chrome 67 и более поздних версий

Параметр callback выглядит следующим образом:
```
() => void
```

Возвраты

Promise<void>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getBadgeBackgroundColor()

Promise

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

Возвращает цвет фона кнопки расширения.

Параметры

подробные сведения

TabDetails
обратный вызов

function необязательно

Параметр callback выглядит следующим образом:
```
(result: ColorArray) => void
```
- Результат
  
  ColorArray

Возвраты

Promise<extensionTypes.ColorArray>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getBadgeText()

Promise

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

Возвращает текст значка действия браузера. Если вкладка не указана, возвращается текст значка, не относящийся к вкладке.

Параметры

подробные сведения

TabDetails
обратный вызов

function необязательно

Параметр callback выглядит следующим образом:
```
(result: string) => void
```
- Результат
  
  string

Возвраты

Promise<string>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getPopup()

Promise

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

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

Параметры

подробные сведения

TabDetails
обратный вызов

function необязательно

Параметр callback выглядит следующим образом:
```
(result: string) => void
```
- Результат
  
  string

Возвраты

Promise<string>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getTitle()

Promise

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

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

Параметры

подробные сведения

TabDetails
обратный вызов

function необязательно

Параметр callback выглядит следующим образом:
```
(result: string) => void
```
- Результат
  
  string

Возвраты

Promise<string>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setBadgeBackgroundColor()

Promise

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

Задает цвет фона значка.

Параметры

подробные сведения

Объект
- цвет
  
  string | ColorArray
  
  Массив из четырех целых чисел в диапазоне от 0 до 255, которые составляют цвет значка в формате RGBA. Также может быть строкой с шестнадцатеричным кодом цвета CSS, например #FF0000 или #F00 (красный). Цвета отображаются с полной непрозрачностью.
- tabId
  
  number (необязательно)
  
  Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
обратный вызов

function необязательно

Chrome 67 и более поздних версий

Параметр callback выглядит следующим образом:
```
() => void
```

Возвраты

Promise<void>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setBadgeText()

Promise

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

Задает текст значка для действия браузера. Значок показывается поверх значка.

Параметры

подробные сведения

Объект
- tabId
  
  number (необязательно)
  
  Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
- Текст
  
  Строка (необязательно)
  
  Можно передать любое количество символов, но в поле поместится только около четырех. Если передается пустая строка (''), текст значка удаляется. Если указан параметр tabId, а параметр text имеет значение null, текст для указанной вкладки удаляется и заменяется текстом значка по умолчанию.
обратный вызов

function необязательно

Chrome 67 и более поздних версий

Параметр callback выглядит следующим образом:
```
() => void
```

Возвраты

Promise<void>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setIcon()

Promise

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

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

Параметры

подробные сведения

Объект
- imageData
  
  ImageData | объект необязательный
  
  Объект ImageData или словарь {size -> ImageData}, представляющий значок, который нужно установить. Если значок задан в виде словаря, то используемое изображение выбирается в зависимости от плотности пикселей экрана. Если количество пикселей изображения, помещающихся в одну единицу пространства экрана, равно scale, то выбирается изображение размером scale * n, где n – размер значка в интерфейсе. Необходимо указать хотя бы одно изображение. Обратите внимание, что details.imageData = foo эквивалентно details.imageData = {'16': foo}.
- путь
  
  string | object необязательный
  
  Относительный путь к изображению или словарь {size -> relative image path}, указывающий на значок, который нужно установить. Если значок задан в виде словаря, то используемое изображение выбирается в зависимости от плотности пикселей экрана. Если количество пикселей изображения, помещающихся в одну единицу пространства экрана, равно scale, то выбирается изображение размером scale * n, где n – размер значка в интерфейсе. Необходимо указать хотя бы одно изображение. Обратите внимание, что details.path = foo эквивалентно details.path = {'16': foo}.
- tabId
  
  number (необязательно)
  
  Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
обратный вызов

function необязательно

Параметр callback выглядит следующим образом:
```
() => void
```

Возвраты

Promise<void>

Chrome 116 и более поздних версий

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setPopup()

Promise

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

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

Параметры

подробные сведения

Объект
- всплывающее окно
  
  string
  
  Относительный путь к HTML-файлу, который будет показан во всплывающем окне. Если задана пустая строка (''), всплывающее окно не показывается.
- tabId
  
  number (необязательно)
  
  Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
обратный вызов

function необязательно

Chrome 67 и более поздних версий

Параметр callback выглядит следующим образом:
```
() => void
```

Возвраты

Promise<void>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setTitle()

Promise

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

Задает название действия в браузере. Этот заголовок будет показываться в подсказке.

Параметры

подробные сведения

Объект
- tabId
  
  number (необязательно)
  
  Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
- название
  
  string
  
  Строка, которая должна отображаться при наведении указателя мыши на действие браузера.
обратный вызов

function необязательно

Chrome 67 и более поздних версий

Параметр callback выглядит следующим образом:
```
() => void
```

Возвраты

Promise<void>

Chrome 88 и более поздних версий;

Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onClicked

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

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

Параметры

обратный вызов

function

Параметр callback выглядит следующим образом:
```
(tab: tabs.Tab) => void
```
- табуляция
  
  tabs.Tab

chrome.browserAction Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

Доступность

Манифест

Элементы интерфейса

Значок

Подсказка

Значок

Всплывающее окно

Советы

Примеры

Типы

TabDetails

Свойства

Методы

disable()

Параметры

Возвраты

enable()

Параметры

Возвраты

getBadgeBackgroundColor()

Параметры

Возвраты

getBadgeText()

Параметры

Возвраты

getPopup()

Параметры

Возвраты

getTitle()

Параметры

Возвраты

setBadgeBackgroundColor()

Параметры

Возвраты

setBadgeText()

Параметры

Возвраты

setIcon()

Параметры

Возвраты

setPopup()

Параметры

Возвраты

setTitle()

Параметры

Возвраты

События

onClicked

Параметры

chrome.browserAction