chrome.action

Описание

Доступность

Манифест

Чтобы использовать 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 опущено, этот параметр рассматривается как глобальный. Настройки, относящиеся к вкладкам, имеют приоритет над глобальными настройками.

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

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

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

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

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

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

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

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

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

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

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

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

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

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

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

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

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

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

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

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