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 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);
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, установите пример 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,
)