browser.action

Описание

Доступность

Манифест

Для использования API browser.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);
browser.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 .

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Неожиданно возникнуть

Всплывающее окно действия отображается, когда пользователь нажимает на кнопку действия расширения на панели инструментов. Всплывающее окно может содержать любой HTML-контент по вашему выбору и будет автоматически масштабироваться в соответствии с его содержимым. Размер всплывающего окна должен быть от 25x25 до 800x600 пикселей.

Первоначально всплывающее окно задается свойством "default_popup" в ключе "action" файла manifest.json . Если это свойство присутствует, оно должно указывать на относительный путь внутри каталога расширения. Его также можно динамически обновлять, указывая на другой относительный путь, используя метод action.setPopup() .

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

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

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

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

browser.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
browser.action.onClicked.addListener((tab) => {
  browser.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

Имитируйте действия с помощью декларативного контента.

В этом примере показано, как фоновая логика расширения может (а) отключать действие по умолчанию и (б) использовать declarativeContent для включения действия на определенных сайтах.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.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,
)