Описание
Используйте API chrome.action, чтобы управлять значком расширения на панели инструментов Google Chrome.
Доступность
Манифест
Чтобы использовать browser.action API, укажите "manifest_version" со значением 3 и добавьте ключ "action" в файл манифеста.
{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
Ключ "action" (вместе с дочерними элементами) указывать необязательно. Если его не добавить, расширение все равно будет показываться на панели инструментов, чтобы пользователи могли открыть его меню. Поэтому мы рекомендуем всегда включать в запрос как минимум ключи "action" и "default_icon".
Основные понятия и использование
Элементы интерфейса
Значок
Значок – это основное изображение на панели инструментов для расширения. Он задается ключом "default_icon" в ключе "action" манифеста. Размер значков должен составлять 16 x 16 аппаратно-независимых пикселей.
Ключ "default_icon" – это словарь размеров и путей к изображениям. Chrome использует эти значки,
чтобы выбрать масштаб изображения. Если точное совпадение не найдено, Chrome выбирает наиболее близкий вариант и масштабирует его, что может повлиять на качество изображения.
Поскольку устройства с менее распространенными коэффициентами масштабирования, такими как 1,5x или 1,2x, становятся все более популярными, мы рекомендуем предоставлять значки нескольких размеров. Это также защитит ваше расширение от возможных изменений размера отображения значков в будущем. Однако если вы указываете только один размер, то в качестве значения ключа "default_icon" можно задать строку с путем к одному значку, а не словарь.
Вы также можете вызвать action.setIcon(), чтобы установить значок расширения программно, указав другой путь к изображению или предоставив динамически генерируемый значок с помощью элемента HTML canvas или, если настройка выполняется из сервисного работника расширения, API offscreen canvas.
const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });
Для упакованных расширений (установленных из файла CRX) изображения могут быть в большинстве форматов, которые может отображать механизм рендеринга Blink, включая PNG, JPEG, BMP, ICO и другие. Формат SVG не поддерживается. В распакованных расширениях должны использоваться изображения PNG.
Подсказка (название)
Подсказка или название появляется, когда пользователь наводит указатель мыши на значок расширения на панели инструментов. Кроме того, оно включается в текст, который озвучивается программами чтения с экрана, когда кнопка оказывается в фокусе.
Подсказка по умолчанию задается с помощью поля "default_title" ключа "action" в файле manifest.json.
Вы также можете задать его программно, вызвав action.setTitle().
Значок
Действия могут дополнительно отображать "значок" – небольшой текст, наложенный на значок. Это позволяет вам обновите действие, чтобы отобразить небольшой объем информации о состоянии расширения, например счетчик. У значка есть текстовый компонент и цвет фона. Поскольку место ограничено, рекомендуем использовать в тексте значка не более четырех символов.
Чтобы создать значок, настройте его программно, вызвав action.setBadgeBackgroundColor() и action.setBadgeText(). В манифесте не задан значок по умолчанию. Цвет значка можно задать в виде массива из четырех целых чисел от 0 до 255, которые составляют цвет RGBA, или строки со значением цвета CSS.
browser.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
browser.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
browser.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
Всплывающее окно
Всплывающее окно действия появляется, когда пользователь нажимает командную кнопку расширения на панели инструментов. Всплывающее окно может содержать любой HTML-контент и автоматически подстраивается под его размер. Размер всплывающего окна должен быть от 25 x 25 до 800 x 600 пикселей.
Всплывающее окно изначально задается свойством "default_popup" в ключе "action" в файле manifest.json. Если это свойство указано, оно должно указывать на относительный путь в каталоге расширения. Его также можно динамически обновлять, чтобы он указывал на другой относительный путь, с помощью метода action.setPopup().
Примеры использования
Состояние вкладки
Действия расширения могут иметь разные состояния для каждой вкладки. Чтобы задать значение для отдельной вкладки, используйте свойство tabId в методах настройки action API. Например, чтобы установить текст значка для определенной вкладки, сделайте следующее:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
browser.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
Если свойство tabId не указано, настройка считается глобальной. Настройки на уровне вкладки имеют приоритет над глобальными настройками.
Включено
По умолчанию действия на панели инструментов включены (доступны для нажатия) на каждой вкладке. Это поведение можно изменить, задав свойство default_state в ключе action манифеста. Если для параметра default_state задано значение "disabled", действие по умолчанию отключено и его нужно включить программно, чтобы оно стало доступно для нажатия. Если для параметра default_state задано значение "enabled" (по умолчанию), действие включено и доступно для нажатия по умолчанию.
Вы можете управлять состоянием программно с помощью методов action.enable() и action.disable(). Это влияет только на то, будет ли отправлено всплывающее окно (если оно есть) или событие action.onClicked в расширение. Наличие действия на панели инструментов не изменится.
Примеры
Ниже приведены примеры распространенных способов использования действий в расширениях. Чтобы попробовать этот API, установите пример Action API из хранилища chrome-extension-samples.
Показать всплывающее окно
Обычно при нажатии на значок расширения появляется всплывающее окно. Чтобы реализовать это в своем расширении, объявите всплывающее окно в файле manifest.json и укажите контент, который Chrome должен показывать в этом окне.
// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
Внедрение скрипта для содержимого по клику
Распространенный шаблон для расширений – предоставлять доступ к основной функции с помощью действия расширения. Ниже приведен пример такого шаблона. Когда пользователь нажимает на кнопку действия, расширение внедряет скрипт контента на текущую страницу. Затем скрипт контента показывает оповещение, чтобы подтвердить, что все работает правильно.
// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
browser.action.onClicked.addListener((tab) => {
browser.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');
Эмулируйте действия с помощью declarativeContent
В этом примере показано, как фоновая логика расширения может: а) по умолчанию отключать действие; б) использовать declarativeContent, чтобы включать действие на определенных сайтах.
// service-worker.js
// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
browser.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
browser.action.disable();
// Clear all rules to ensure only our expected rules are set
browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new browser.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new browser.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
browser.declarativeContent.onPageChanged.addRules(rules);
});
});
Типы
OpenPopupOptions
Свойства
-
windowId
number (необязательно)
Идентификатор окна, в котором нужно открыть всплывающее окно действия. Если не указано, по умолчанию используется активное окно.
TabDetails
Свойства
-
tabId
number (необязательно)
Идентификатор вкладки, состояние которой нужно запросить. Если вкладка не указана, возвращается состояние, не связанное с вкладкой.
UserSettings
Набор заданных пользователем настроек, связанных с действием расширения.
Свойства
-
isOnToolbar
Логическое значение
Виден ли значок действия расширения на панели инструментов верхнего уровня в окнах браузера (то есть закреплено ли расширение пользователем).
UserSettingsChange
Свойства
-
isOnToolbar
Логическое значение (необязательно)
Виден ли значок действия расширения на панели инструментов верхнего уровня в окнах браузера (то есть закреплено ли расширение пользователем).
Методы
disable()
browser.action.disable(
tabId?: number,
): Promise<void>
Отключает действие для вкладки.
Параметры
-
tabId
number (необязательно)
Идентификатор вкладки, для которой вы хотите изменить действие.
Возвраты
-
Promise<void>
enable()
browser.action.enable(
tabId?: number,
): Promise<void>
Включает действие для вкладки. По умолчанию действия включены.
Параметры
-
tabId
number (необязательно)
Идентификатор вкладки, для которой вы хотите изменить действие.
Возвраты
-
Promise<void>
getBadgeBackgroundColor()
browser.action.getBadgeBackgroundColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
Возвращает цвет фона действия.
Параметры
-
подробные сведения
Возвраты
-
Promise<extensionTypes.ColorArray>
getBadgeText()
browser.action.getBadgeText(
details: TabDetails,
): Promise<string>
Возвращает текст значка действия. Если вкладка не указана, возвращается текст значка, не относящийся к вкладке. Если включено свойство displayActionCountAsBadgeText, будет возвращен текст-плейсхолдер, если только не предоставлено разрешение declarativeNetRequestFeedback или текст значка для определенной вкладки.
Параметры
-
подробные сведения
Возвраты
-
Promise<string>
getBadgeTextColor()
browser.action.getBadgeTextColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
Возвращает цвет текста действия.
Параметры
-
подробные сведения
Возвраты
-
Promise<extensionTypes.ColorArray>
getPopup()
browser.action.getPopup(
details: TabDetails,
): Promise<string>
Возвращает HTML-документ, заданный в качестве всплывающего окна для этого действия.
Параметры
-
подробные сведения
Возвраты
-
Promise<string>
getTitle()
browser.action.getTitle(
details: TabDetails,
): Promise<string>
Возвращает название действия.
Параметры
-
подробные сведения
Возвраты
-
Promise<string>
getUserSettings()
browser.action.getUserSettings(): Promise<UserSettings>
Возвращает заданные пользователем настройки, связанные с действием расширения.
Возвраты
-
Promise<UserSettings>
isEnabled()
browser.action.isEnabled(
tabId?: number,
): Promise<boolean>
Указывает, включено ли действие расширения для вкладки (или глобально, если tabId не указан). Действия, включенные только с помощью declarativeContent, всегда возвращают значение false.
Параметры
-
tabId
number (необязательно)
Идентификатор вкладки, статус которой нужно проверить.
Возвраты
-
Promise<boolean>
openPopup()
browser.action.openPopup(
options?: OpenPopupOptions,
): Promise<void>
Открывает всплывающее окно расширения. В версиях Chrome 118–126 это доступно только для расширений, установленных с помощью правил.
Параметры
-
Параметры
OpenPopupOptions необязательный
Задает параметры для открытия всплывающего окна.
Возвраты
-
Promise<void>
setBadgeBackgroundColor()
browser.action.setBadgeBackgroundColor(
details: object,
): Promise<void>
Задает цвет фона значка.
Параметры
-
подробные сведения
Объект
-
цвет
string | ColorArray
Массив из четырех целых чисел в диапазоне [0,255], которые составляют цвет значка в формате RGBA. Например, непрозрачный красный цвет обозначается как
[255, 0, 0, 255]. Также может быть строкой со значением CSS, где непрозрачный красный – это#FF0000или#F00. -
tabId
number (необязательно)
Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
-
Возвраты
-
Promise<void>
setBadgeText()
browser.action.setBadgeText(
details: object,
): Promise<void>
Задает текст значка для действия. Значок показывается поверх значка.
Параметры
-
подробные сведения
Объект
-
tabId
number (необязательно)
Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
-
Текст
Строка (необязательно)
Передать можно любое количество символов, но в отведенном месте поместится только около четырех. Если передается пустая строка (
''), текст значка удаляется. Если указан параметрtabId, а параметрtextимеет значение null, текст для указанной вкладки удаляется и заменяется текстом значка по умолчанию.
-
Возвраты
-
Promise<void>
setBadgeTextColor()
browser.action.setBadgeTextColor(
details: object,
): Promise<void>
Задает цвет текста для значка.
Параметры
-
подробные сведения
Объект
-
цвет
string | ColorArray
Массив из четырех целых чисел в диапазоне [0,255], которые составляют цвет значка в формате RGBA. Например, непрозрачный красный цвет обозначается как
[255, 0, 0, 255]. Также может быть строкой со значением CSS, где непрозрачный красный – это#FF0000или#F00. Если вы не зададите это значение, цвет будет выбран автоматически. Он будет контрастировать с цветом фона значка, чтобы текст был виден. Цвета со значением альфа-канала, равным 0, не будут заданы, и будет возвращена ошибка. -
tabId
number (необязательно)
Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
-
Возвраты
-
Promise<void>
setIcon()
browser.action.setIcon(
details: object,
): 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 (необязательно)
Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
-
Возвраты
-
Promise<void>
Chrome 96 и более поздние версии browser.* начиная с Chrome 148
setPopup()
browser.action.setPopup(
details: object,
): Promise<void>
Указывает, что HTML-документ должен открываться во всплывающем окне, когда пользователь нажимает на значок действия.
Параметры
-
подробные сведения
Объект
-
всплывающее окно
string
Относительный путь к HTML-файлу, который будет показан во всплывающем окне. Если задана пустая строка (
''), всплывающее окно не показывается. -
tabId
number (необязательно)
Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
-
Возвраты
-
Promise<void>
setTitle()
browser.action.setTitle(
details: object,
): Promise<void>
Задает название действия. Оно будет показываться в подсказке.
Параметры
-
подробные сведения
Объект
-
tabId
number (необязательно)
Изменение применяется только при выборе определенной вкладки. Разрешения автоматически сбрасываются, когда вы закрываете вкладку.
-
название
string
Строка, которая должна показываться при наведении указателя мыши на действие.
-
Возвраты
-
Promise<void>
События
onClicked
browser.action.onClicked.addListener(
callback: function,
)
Срабатывает при нажатии на значок действия. Это событие не активируется, если у действия есть всплывающее окно.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(tab: tabs.Tab) => void
-
табуляция
-
onUserSettingsChanged
browser.action.onUserSettingsChanged.addListener(
callback: function,
)
Срабатывает, когда меняются заданные пользователем настройки, связанные с действием расширения.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(change: UserSettingsChange) => void
-
Изменять
-