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-интерфейса offscreen-холста .

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);
  });
});

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

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

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