Эта страница переведена с помощью Cloud Translation API.

chrome.browserAction

Описание

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

Доступность

≤ МВ2

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

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

Манифест

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

{
  "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 пикселей.

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

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

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

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

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

Значок

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

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

Задайте текст и цвет значка, используя browserAction.setBadgeText и browserAction.setBadgeBackgroundColor соответственно.

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

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

Советы

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

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

Примеры

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

Типы

ColorArray

Тип

[номер, номер, номер, номер]

ImageDataType

Пиксельные данные для изображения. Должен быть объектом ImageData; например, из элемента canvas .

Тип

Данные изображения

TabDetails

Хром 88+

Характеристики

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

Методы

disable()

Обещать

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

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

Параметры

идентификатор табуляции
номер необязательно
Идентификатор вкладки, для которой нужно изменить действие браузера.
перезвонить
функция необязательна
Хром 67+
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

enable()

Обещать

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

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

Параметры

идентификатор табуляции
номер необязательно
Идентификатор вкладки, для которой нужно изменить действие браузера.
перезвонить
функция необязательна
Хром 67+
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getBadgeBackgroundColor()

Обещать

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

Параметры

подробности
ВкладкаПодробнее
перезвонить
функция необязательна
Параметр callback выглядит так:
```
(result: ColorArray) => void
```
- результат
  Цветмассив

Возврат

Обещание < ColorArray >
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getBadgeText()

Обещать

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

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

Параметры

подробности
ВкладкаПодробнее
перезвонить
функция необязательна
Параметр callback выглядит так:
```
(result: string) => void
```
- результат
  нить

Возврат

Обещание<строка>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getPopup()

Обещать

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

Параметры

подробности
ВкладкаПодробнее
перезвонить
функция необязательна
Параметр callback выглядит так:
```
(result: string) => void
```
- результат
  нить

Возврат

Обещание<строка>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getTitle()

Обещать

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

Параметры

подробности
ВкладкаПодробнее
перезвонить
функция необязательна
Параметр callback выглядит так:
```
(result: string) => void
```
- результат
  нить

Возврат

Обещание<строка>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

setBadgeBackgroundColor()

Обещать

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Устанавливает цвет фона для значка.

Параметры

подробности
объект
- цвет
  строка | Цветмассив
  Массив из четырех целых чисел в диапазоне 0–255, составляющих цвет значка RGBA. Также может быть строкой с шестнадцатеричным значением цвета CSS; например, #FF0000 или #F00 (красный). Отображает цвета с полной непрозрачностью.
- идентификатор табуляции
  номер необязательно
  Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
перезвонить
функция необязательна
Хром 67+
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

setBadgeText()

Обещать

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

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

Параметры

подробности
объект
- идентификатор табуляции
  номер необязательно
  Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
- текст
  строка необязательна
  Можно передать любое количество символов, но в пространство поместится только около четырех. Если передается пустая строка ( '' ), текст значка очищается. Если указан tabId и text имеет значение NULL, текст указанной вкладки очищается и по умолчанию используется текст глобального значка.
перезвонить
функция необязательна
Хром 67+
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

setIcon()

Обещать

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

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

Параметры

подробности
объект
- данные изображения
  Данные изображения | объект необязательный
  Либо объект ImageData, либо словарь {size -> ImageData}, представляющий устанавливаемый значок. Если значок указан как словарь, используемое изображение выбирается в зависимости от плотности пикселей экрана. Если количество пикселей изображения, помещающихся в одну единицу экранного пространства, равно scale , то выбирается изображение с размером scale * n, где n — размер значка в пользовательском интерфейсе. Необходимо указать хотя бы одно изображение. Обратите внимание, что 'details.imageData = foo' эквивалентно 'details.imageData = {'16': foo}'
- путь
  строка | объект необязательный
  Либо относительный путь к изображению, либо словарь {размер -> относительный путь к изображению}, указывающий на устанавливаемый значок. Если значок указан как словарь, используемое изображение выбирается в зависимости от плотности пикселей экрана. Если количество пикселей изображения, помещающихся в одну единицу экранного пространства, равно scale , то выбирается изображение с размером scale * n, где n — размер значка в пользовательском интерфейсе. Необходимо указать хотя бы одно изображение. Обратите внимание, что 'details.path = foo' эквивалентен 'details.path = {'16': foo}'.
- идентификатор табуляции
  номер необязательно
  Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
перезвонить
функция необязательна
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 116+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

setPopup()

Обещать

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

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

Параметры

подробности
объект
- неожиданно возникнуть
  нить
  Относительный путь к HTML-файлу, который будет отображаться во всплывающем окне. Если установлена пустая строка ( '' ), всплывающее окно не отображается.
- идентификатор табуляции
  номер необязательно
  Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
перезвонить
функция необязательна
Хром 67+
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

setTitle()

Обещать

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

Устанавливает заголовок действия браузера. Это название отображается во всплывающей подсказке.

Параметры

подробности
объект
- идентификатор табуляции
  номер необязательно
  Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
- заголовок
  нить
  Строка, которую действие браузера должно отображать при наведении курсора мыши.
перезвонить
функция необязательна
Хром 67+
Параметр callback выглядит так:
```
() => void
```

Возврат

Обещание<void>
Хром 88+
Промисы поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

События

onClicked

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(tab: tabs.Tab) => void
```
- вкладка
  tabs.Tab

chrome.browserAction

Описание

Доступность

Манифест

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

Икона

Подсказка

Значок

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

Советы

Примеры

Типы

ColorArray

Тип

ImageDataType

Тип

TabDetails

Характеристики

Методы

disable()

Параметры

Возврат

enable()

Параметры

Возврат

getBadgeBackgroundColor()

Параметры

Возврат

getBadgeText()

Параметры

Возврат

getPopup()

Параметры

Возврат

getTitle()

Параметры

Возврат

setBadgeBackgroundColor()

Параметры

Возврат

setBadgeText()

Параметры

Возврат

setIcon()

Параметры

Возврат

setPopup()

Параметры

Возврат

setTitle()

Параметры

Возврат

События

onClicked

Параметры