browser.commands

Описание

Используйте commands API, чтобы добавить быстрые клавиши, которые запускают действия в расширении, например открывают действие браузера или отправляют команду расширению.

Манифест

Чтобы использовать этот API, в манифесте нужно объявить следующие ключи:

"commands"

Основные понятия и использование

Commands API позволяет разработчикам расширений определять команды и связывать их с сочетаниями клавиш по умолчанию. Каждая команда, которую принимает расширение, должна быть объявлена как свойство объекта "commands" в манифесте расширения.

Ключ свойства используется в качестве названия команды. Объекты команд могут принимать два свойства.

suggested_key

Необязательное свойство, которое объявляет сочетания клавиш по умолчанию для команды. Если его не указать, команда не будет привязана. Это свойство может принимать значение в виде строки или объекта.

• Строковое значение определяет сочетание клавиш по умолчанию, которое будет использоваться на всех платформах.

  • Значение объекта позволяет разработчику расширения настраивать сочетание клавиш для каждой платформы. При указании быстрых клавиш для конкретной платформы допустимыми свойствами объекта являются default, chromeos, linux, mac и windows.

  Подробнее о требованиях к комбинациям клавиш…

description

Строка, которая содержит краткое описание назначения команды. This string appears in extension keyboard shortcut management UI. Описания обязательны для стандартных команд, но игнорируются для команд действий.

У расширения может быть много команд, но для него можно указать не более четырех сочетаний клавиш. Пользователь может вручную добавить больше ярлыков в диалоговом окне chrome://extensions/shortcuts.

Поддерживаемые ключи

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

Буквенные клавиши

A … Z

Цифровые клавиши

0 … 9

Стандартные строки ключей

Общие – Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

Клавиши со стрелками: Up, Down, Left, Right

Мультимедийные клавиши: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop.

Строки клавиш-модификаторов

Ctrl, Alt, Shift, MacCtrl (только macOS), Option (только macOS), Command (только macOS), Search (только ChromeOS)

Требования к сочетаниям клавиш

• В сочетаниях клавиш для команд расширений должна использоваться клавиша Ctrl или Alt.

  • Модификаторы нельзя использовать в сочетании с мультимедийными клавишами.

  • На многих клавиатурах macOS Alt – это клавиша Option.

  • В macOS вместо Ctrl можно использовать Command или MacCtrl, а вместо Alt – Option (см. следующий пункт).

• В macOS Ctrl автоматически преобразуется в Command.

  • Command также можно использовать в сочетании клавиш "mac", чтобы явно указать на клавишу Command.

  • Чтобы использовать клавишу Control в macOS, замените Ctrl на MacCtrl при определении сочетания клавиш "mac".

  • Если вы укажете MacCtrl в комбинации для другой платформы, возникнет ошибка проверки и расширение не будет установлено.

• Shift – необязательный модификатор для всех платформ.

• Search – это необязательный модификатор, который используется только в ChromeOS.

• Некоторые сочетания клавиш операционной системы и Chrome (например, для управления окнами) всегда имеют приоритет над сочетаниями клавиш для команд расширений и не могут быть переопределены.

Примечание. Сочетания клавиш, включающие Ctrl+Alt, не разрешены, чтобы избежать конфликтов с клавишей AltGr.

Обработка событий команд

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "run-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Run \"foo\" on the current page."
    },
    "_execute_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    }
  },
  ...
}

В сервис-воркере можно связать обработчик с каждой из команд, определенных в манифесте, с помощью onCommand.addListener. Пример:

service-worker.js:

browser.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

Команды действий

Команды _execute_action (Manifest V3), _execute_browser_action (Manifest V2) и _execute_page_action (Manifest V2) зарезервированы для запуска действия, действия браузера или действия страницы соответственно. Эти команды не отправляют события command.onCommand, как стандартные команды.

Если вам нужно выполнить действие на основе открытия всплывающего окна, рассмотрите возможность прослушивания события DOMContentLoaded внутри JavaScript всплывающего окна.

Область действия

По умолчанию команды применяются к браузеру Chrome. Это означает, что когда браузер не находится в фокусе, быстрые клавиши неактивны. Начиная с версии Chrome 35, разработчики расширений могут помечать команды как глобальные. Глобальные команды работают, даже когда окно Chrome неактивно.

Примечание. ChromeOS не поддерживает глобальные команды.

Предлагаемые сочетания клавиш для глобальных команд ограничены Ctrl+Shift+[0..9]. Это защитная мера, которая позволяет минимизировать риск переопределения быстрых клавиш в других приложениях. Например, если бы сочетание Alt+P было разрешено в качестве глобального, то быстрые клавиши для открытия диалогового окна печати могли бы не работать в других приложениях.

Конечные пользователи могут переназначить глобальные команды на удобные для них сочетания клавиш в интерфейсе на странице chrome://extensions/shortcuts.

Пример:

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

Примеры

В примерах ниже показаны основные функции Commands API.

Базовая команда

Команды позволяют расширениям сопоставлять логику с быстрыми клавишами, которые может вызывать пользователь. В самом простом случае для команды требуется только объявление команды в манифесте расширения и регистрация прослушивателя, как показано в следующем примере.

manifest.json:

{
  "name": "Command demo - basic",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "commands": {
    "inject-script": {
      "suggested_key": "Ctrl+Shift+Y",
      "description": "Inject a script on the page"
    }
  }
}

service-worker.js:

browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

Команда действия

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

manifest.json:

{
  "name": "Commands demo - action invocation",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "permissions": ["activeTab", "scripting"],
  "action": {},
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+U",
        "mac": "Command+U"
      }
    }
  }
}

service-worker.js:

browser.action.onClicked.addListener((tab) => {
  browser.scripting.executeScript({
    target: {tabId: tab.id},
    func: contentScriptFunc,
    args: ['action'],
  });
});

function contentScriptFunc(name) {
  alert(`"${name}" executed`);
}

// This callback WILL NOT be called for "_execute_action"
browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

Проверьте зарегистрированные команды

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

service-worker.js:

browser.runtime.onInstalled.addListener((details) => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.commands.getAll((commands) => {
    let missingShortcuts = [];

    for (let {name, shortcut} of commands) {
      if (shortcut === '') {
        missingShortcuts.push(name);
      }
    }

    if (missingShortcuts.length > 0) {
      // Update the extension UI to inform the user that one or more
      // commands are currently unassigned.
    }
  });
}

Типы

Command

Свойства

• описание

  Строка (необязательно)

  Описание команды расширения

• name

  Строка (необязательно)

  Название команды расширения.

• ярлык

  Строка (необязательно)

  Активное сочетание клавиш для этой команды или пустое поле, если оно неактивно.

Методы

getAll()

browser.commands.getAll(): Promise<Command[]>

Возвращает все зарегистрированные команды расширения и их сочетания клавиш (если они активны). В версиях до Chrome 110 эта команда не возвращала _execute_action.

Возвраты

• Promise<Command[]>

  Chrome 96 и более поздние версии browser.* начиная с Chrome 148

  Возвращает список зарегистрированных команд.

События

onCommand

browser.commands.onCommand.addListener(
  callback: function,
)

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

Параметры

• обратный вызов

  function

  Параметр callback выглядит следующим образом:

  (command: string, tab?: tabs.Tab) => void

  • команда

    string

  • табуляция

    tabs.Tab необязательно