Описание
Используйте API chrome.action
для управления значком расширения на панели инструментов Google Chrome.
Доступность
Манифест
Чтобы использовать API chrome.action
, укажите значение "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 аппаратно-независимых пикселей (DIP).
Ключ "default_icon"
представляет собой словарь размеров путей к изображениям. Chrome использует эти значки, чтобы выбрать масштаб изображения. Если точное совпадение не найдено, Chrome выбирает наиболее близкий из доступных и масштабирует его в соответствии с изображением, что может повлиять на качество изображения.
Поскольку устройства с менее распространенными коэффициентами масштабирования, такими как 1,5x или 1,2x, становятся все более распространенными, мы рекомендуем вам предоставлять значки разных размеров. Это также защитит ваше расширение от возможных изменений размера отображения значков в будущем. Однако, если указан только один размер, ключу "default_icon"
также можно задать строку с путем к одному значку вместо словаря.
Вы также можете вызвать action.setIcon()
чтобы программно установить значок вашего расширения, указав другой путь к изображению или предоставив динамически создаваемый значок с помощью HTML-элемента холста или, если установка выполняется из работника службы расширений, внеэкранного API холста .
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);
chrome.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 .
chrome.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
Неожиданно возникнуть
Всплывающее окно действия отображается, когда пользователь нажимает кнопку действия расширения на панели инструментов. Всплывающее окно может содержать любое HTML-содержимое, которое вам нравится, и его размер будет автоматически изменен в соответствии с его содержимым. Размер всплывающего окна должен находиться в диапазоне от 25x25 до 800x600 пикселей.
Всплывающее окно изначально задается свойством "default_popup"
в ключе "action"
в файле manifest.json
. Если это свойство присутствует, оно должно указывать на относительный путь в каталоге расширения. Его также можно динамически обновлять, чтобы он указывал на другой относительный путь, используя метод action.setPopup()
.
Варианты использования
Состояние на вкладке
Действия расширения могут иметь разные состояния для каждой вкладки. Чтобы установить значение для отдельной вкладки, используйте свойство tabId
в методах настройки API action
. Например, чтобы установить текст значка для определенной вкладки, сделайте следующее:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.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
chrome.action.onClicked.addListener((tab) => {
chrome.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
chrome.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
chrome.action.disable();
// Clear all rules to ensure only our expected rules are set
chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new chrome.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
chrome.declarativeContent.onPageChanged.addRules(rules);
});
});
Типы
OpenPopupOptions
Характеристики
- идентификатор окна
номер необязательно
Идентификатор окна, в котором открывается всплывающее окно действия. По умолчанию используется активное в данный момент окно, если не указано.
TabDetails
Характеристики
- идентификатор табуляции
номер необязательно
Идентификатор вкладки, для которой требуется запросить состояние. Если вкладка не указана, возвращается состояние, не зависящее от вкладки.
UserSettings
Коллекция пользовательских настроек, относящихся к действию расширения.
Характеристики
- isOnToolbar
логическое значение
Виден ли значок действия расширения на панели инструментов верхнего уровня окон браузера (т. е. было ли расширение «закреплено» пользователем).
UserSettingsChange
Характеристики
- isOnToolbar
логическое значение необязательно
Виден ли значок действия расширения на панели инструментов верхнего уровня окон браузера (т. е. было ли расширение «закреплено» пользователем).
Методы
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
Отключает действие для вкладки.
Параметры
- идентификатор табуляции
номер необязательно
Идентификатор вкладки, для которой вы хотите изменить действие.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Включает действие для вкладки. По умолчанию действия включены.
Параметры
- идентификатор табуляции
номер необязательно
Идентификатор вкладки, для которой вы хотите изменить действие.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Получает цвет фона действия.
Параметры
- подробности
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(result: ColorArray) => void
- результат
Возврат
Обещание< browserAction.ColorArray >
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Получает текст значка действия. Если вкладка не указана, возвращается текст значка, не относящийся к вкладке. Если displayActionCountAsBadgeText включен, будет возвращен текст-заполнитель, если не присутствует разрешение declarativeNetRequestFeedback или не предоставлен текст значка для конкретной вкладки.
Параметры
- подробности
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(result: string) => void
- результат
нить
Возврат
Обещание<строка>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Получает цвет текста действия.
Параметры
- подробности
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(result: ColorArray) => void
- результат
Возврат
Обещание< browserAction.ColorArray >
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Получает HTML-документ, установленный в качестве всплывающего окна для этого действия.
Параметры
- подробности
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(result: string) => void
- результат
нить
Возврат
Обещание<строка>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Получает название действия.
Параметры
- подробности
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(result: string) => void
- результат
нить
Возврат
Обещание<строка>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Возвращает заданные пользователем настройки, относящиеся к действию расширения.
Параметры
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(userSettings: UserSettings) => void
- пользовательские настройки
Возврат
Обещание < Настройки пользователя >
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
Указывает, включено ли действие расширения для вкладки (или глобально, если tabId
не указан). Действия, включенные с использованием только declarativeContent
всегда возвращают значение false.
Параметры
- идентификатор табуляции
номер необязательно
Идентификатор вкладки, для которой вы хотите проверить включенный статус.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(isEnabled: boolean) => void
- isEnabled
логическое значение
True, если действие расширения включено.
Возврат
Обещание <логическое значение>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Открывает всплывающее окно расширения. В версиях Chrome 118 и Chrome 126 это доступно только для расширений, установленных политикой.
Параметры
- параметры
OpenPopupOptions необязательно
Указывает параметры открытия всплывающего окна.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Устанавливает цвет фона для значка.
Параметры
- подробности
объект
- цвет
строка | Цветмассив
Массив из четырех целых чисел в диапазоне [0,255], составляющих цвет значка RGBA. Например, непрозрачный красный — это
[255, 0, 0, 255]
. Также может быть строкой со значением CSS, где непрозрачный красный —#FF0000
или#F00
. - идентификатор табуляции
номер необязательно
Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
Устанавливает текст значка для действия. Значок отображается поверх значка.
Параметры
- подробности
объект
- идентификатор табуляции
номер необязательно
Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
- текст
строка необязательна
Можно передать любое количество символов, но в пространстве поместится только около четырех. Если передается пустая строка (
''
), текст значка очищается. Если указанtabId
иtext
имеет значение NULL, текст указанной вкладки очищается и по умолчанию используется текст глобального значка.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
Устанавливает цвет текста для значка.
Параметры
- подробности
объект
- цвет
строка | Цветмассив
Массив из четырех целых чисел в диапазоне [0,255], составляющих цвет значка RGBA. Например, непрозрачный красный — это
[255, 0, 0, 255]
. Также может быть строкой со значением CSS, где непрозрачный красный —#FF0000
или#F00
. Если вы не установите это значение, будет автоматически выбран цвет, который будет контрастировать с цветом фона значка, поэтому текст будет виден. Цвета со значениями альфа, эквивалентными 0, не будут установлены и вернут ошибку. - идентификатор табуляции
номер необязательно
Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
Устанавливает значок для действия. Значок можно указать либо как путь к файлу изображения, либо как данные пикселей из элемента холста, либо как словарь любого из них. Необходимо указать либо путь , либо свойство 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>
Хром 96+Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
Устанавливает HTML-документ, который будет открываться во всплывающем окне, когда пользователь щелкает значок действия.
Параметры
- подробности
объект
- неожиданно возникнуть
нить
Относительный путь к HTML-файлу, который будет отображаться во всплывающем окне. Если установлена пустая строка (
''
), всплывающее окно не отображается. - идентификатор табуляции
номер необязательно
Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
Устанавливает название действия. Это отображается во всплывающей подсказке.
Параметры
- подробности
объект
- идентификатор табуляции
номер необязательно
Ограничивает изменение моментом выбора определенной вкладки. Автоматически сбрасывается при закрытии вкладки.
- заголовок
нить
Строка, которую действие должно отображать при наведении курсора мыши.
- перезвонить
функция опциональная
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
События
onClicked
chrome.action.onClicked.addListener(
callback: function,
)
Запускается при нажатии значка действия. Это событие не сработает, если у действия есть всплывающее окно.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(tab: tabs.Tab) => void
- вкладка
onUserSettingsChanged
chrome.action.onUserSettingsChanged.addListener(
callback: function,
)
Вызывается, когда изменяются заданные пользователем настройки, относящиеся к действию расширения.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(change: UserSettingsChange) => void
- изменять