chrome.action

Описание

Используйте API chrome.action для управления значком расширения на панели инструментов Google Chrome.

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

Доступность

Хром 88+ МВ3+

Манифест

Для использования этого API в манифесте необходимо объявить следующие ключи.

"action"

Чтобы использовать API chrome.action , укажите значение "manifest_version" 3 и включите ключ "action" в файл манифеста .

Примечание. У каждого расширения есть значок на панели инструментов Chrome, даже если клавиша "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}, () => { /* ... */ });

Примечание. API action.setIcon() предназначен для установки статического изображения. Не используйте анимированные изображения для своих значков.

Для упакованных расширений (установленных из файла .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() .

Примечание. Событие action.onClicked не будет отправлено, если в действии расширения указано всплывающее окно, которое отображается при нажатии на текущую вкладку.

Варианты использования

Состояние на вкладке

Действия расширения могут иметь разные состояния для каждой вкладки. Чтобы установить значение для отдельной вкладки, используйте свойство tabId в методах настройки API action . Например, чтобы установить текст значка для определенной вкладки, сделайте следующее:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

Если свойство tabId опущено, этот параметр рассматривается как глобальный. Настройки, относящиеся к вкладкам, имеют приоритет над глобальными настройками.

Включенное состояние

По умолчанию действия панели инструментов включены (кликабельны) на каждой вкладке. Вы можете контролировать это с помощью методов 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

Хром 99+

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

• идентификатор окна

  номер необязательно

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

TabDetails

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

• идентификатор табуляции

  номер необязательно

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

UserSettings

Хром 91+

Коллекция пользовательских настроек, относящихся к действию расширения.

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

• 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 110+

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 91+

chrome.action.getUserSettings(
  callback?: function,
)

Возвращает заданные пользователем настройки, относящиеся к действию расширения.

Параметры

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (userSettings: UserSettings) => void

  • пользовательские настройки

    Пользовательские настройки

Возврат

• Обещание < Настройки пользователя >

  Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

isEnabled()

Обещание Chrome 110+

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

Указывает, включено ли действие расширения для вкладки (или глобально, если tabId не указан). Действия, включенные с использованием только declarativeContent всегда возвращают значение false.

Параметры

• идентификатор табуляции

  номер необязательно

  Идентификатор вкладки, для которой вы хотите проверить включенный статус.

• перезвонить

  функция необязательна

  Параметр callback выглядит так:

  (isEnabled: boolean) => void

  • isEnabled

    логическое значение

    True, если действие расширения включено.

Возврат

• Обещание <логическое значение>

  Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

openPopup()

Обещание Chrome 127+

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 110+

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

  • вкладка

    tabs.Tab

onUserSettingsChanged

В ожидании

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

Вызывается, когда изменяются заданные пользователем настройки, относящиеся к действию расширения.

Параметры

• перезвонить

  функция

  Параметр callback выглядит так:

  (change: UserSettingsChange) => void

  • изменять

    Пользовательские настройкиИзменить